- NAME
-
- gcloud compute os-config patch-jobs execute - execute an OS patch on the specified VM instances
- SYNOPSIS
-
-
gcloud compute os-config patch-jobs execute
(--instance-filter-all
|--instance-filter-group-labels
=[KEY
=VALUE
,…]--instance-filter-name-prefixes
=[INSTANCE_FILTER_NAME_PREFIXES
,…]--instance-filter-names
=[INSTANCE_FILTER_NAMES
,…]--instance-filter-zones
=[INSTANCE_FILTER_ZONES
,…]) [--async
] [--description
=DESCRIPTION
] [--display-name
=DISPLAY_NAME
] [--dry-run
] [--duration
=DURATION
] [--mig-instances-allowed
] [--reboot-config
=REBOOT_CONFIG
] [--apt-dist
--apt-excludes
=[APT_EXCLUDES
,…] |--apt-exclusive-packages
=[APT_EXCLUSIVE_PACKAGES
,…]] [--post-patch-linux-executable
=POST_PATCH_LINUX_EXECUTABLE
--post-patch-linux-success-codes
=[POST_PATCH_LINUX_SUCCESS_CODES
,…]] [--post-patch-windows-executable
=POST_PATCH_WINDOWS_EXECUTABLE
--post-patch-windows-success-codes
=[POST_PATCH_WINDOWS_SUCCESS_CODES
,…]] [--pre-patch-linux-executable
=PRE_PATCH_LINUX_EXECUTABLE
--pre-patch-linux-success-codes
=[PRE_PATCH_LINUX_SUCCESS_CODES
,…]] [--pre-patch-windows-executable
=PRE_PATCH_WINDOWS_EXECUTABLE
--pre-patch-windows-success-codes
=[PRE_PATCH_WINDOWS_SUCCESS_CODES
,…]] [--rollout-mode
=ROLLOUT_MODE
--rollout-disruption-budget
=ROLLOUT_DISRUPTION_BUDGET
|--rollout-disruption-budget-percent
=ROLLOUT_DISRUPTION_BUDGET_PERCENT
] [--windows-exclusive-patches
=[WINDOWS_EXCLUSIVE_PATCHES
,…] |--windows-classifications
=[WINDOWS_CLASSIFICATIONS
,…]--windows-excludes
=[WINDOWS_EXCLUDES
,…]] [--yum-exclusive-packages
=[YUM_EXCLUSIVE_PACKAGES
,…] |--yum-excludes
=[YUM_EXCLUDES
,…]--yum-minimal
--yum-security
] [--zypper-exclusive-patches
=[ZYPPER_EXCLUSIVE_PATCHES
,…] |--zypper-categories
=[ZYPPER_CATEGORIES
,…]--zypper-excludes
=[ZYPPER_EXCLUDES
,…]--zypper-severities
=[ZYPPER_SEVERITIES
,…]--zypper-with-optional
--zypper-with-update
] [GCLOUD_WIDE_FLAG …
]
-
- DESCRIPTION
- Execute an OS patch on the specified VM instances.
- EXAMPLES
-
To start a patch job named
my patch job
that patches all instances in the current project, run:gcloud compute os-config patch-jobs execute --display-name="my patch job" --instance-filter-all
To patch an instance named
instance-1
in theus-east1-b
zone, run:gcloud compute os-config patch-jobs execute --instance-filter-names="zones/us-east1-b/instances/instance-1"
To patch all instances in the
us-central1-b
andeurope-west1-d
zones, run:gcloud compute os-config patch-jobs execute --instance-filter-zones="us-central1-b,europe-west1-d"
To patch all instances where the
env
label istest
andapp
label isweb
, run:gcloud compute os-config patch-jobs execute --instance-filter-group-labels="env=test,app=web"
To patch all instances where the
env
label istest
andapp
label isweb
or where theenv
label isstaging
andapp
label isweb
, run:gcloud compute os-config patch-jobs execute --instance-filter-group-labels="env=test,app=web" --instance-filter-group-labels="env=staging,app=web"
To apply security and critical patches to Windows instances with the prefix
windows-
in the instance name, run:gcloud compute os-config patch-jobs execute --instance-filter-name-prefixes="windows-" --windows-classifications=SECURITY,CRITICAL
To update only
KB4339284
on Windows instances with the prefixwindows-
in the instance name, run:gcloud compute os-config patch-jobs execute --instance-filter-name-prefixes="windows-" --windows-exclusive-patches=4339284
To patch all instances in the current project and specify scripts to run pre-patch and post-patch, run:
gcloud compute os-config patch-jobs execute --instance-filter-all --pre-patch-linux-executable="/bin/script" --pre-patch-linux-success-codes=0,200 --pre-patch-windows-executable="C:\Users\user\script.ps1" --post-patch-linux-executable="gs://my-bucket/linux-script#123" --post-patch-windows-executable="gs://my-bucket/windows-script#678"
To patch all instances zone-by-zone with no more than 50 percent of the instances in the same zone disrupted at a given time, run:
gcloud compute os-config patch-jobs execute --instance-filter-all --rollout-mode=zone-by-zone --rollout-disruption-budget-percent=50
- REQUIRED FLAGS
-
-
Filters for selecting which instances to patch:
Exactly one of these must be specified:
--instance-filter-all
- A filter that targets all instances in the project.
-
Individual filters. The targeted instances must meet all criteria specified.
--instance-filter-group-labels
=[KEY
=VALUE
,…]-
A filter that represents a label set. Targeted instances must have all specified
labels in this set. For example, "env=prod and app=web".
This flag can be repeated. Targeted instances must have at least one of these label sets. This allows targeting of disparate groups, for example, "(env=prod and app=web) or (env=staging and app=web)".
--instance-filter-name-prefixes
=[INSTANCE_FILTER_NAME_PREFIXES
,…]- A filter that targets instances whose name starts with one of these prefixes. For example, "prod-".
--instance-filter-names
=[INSTANCE_FILTER_NAMES
,…]- A filter that targets instances of any of the specified names. Instances are specified by the URI in the form "zones/<ZONE>/instances/<INSTANCE_NAME>", "projects/<PROJECT_ID>/zones/<ZONE>/instances/<INSTANCE_NAME>", or "https://www.googleapis.com/compute/v1/projects/<PROJECT_ID>/zones/<ZONE>/instances/<INSTANCE_NAME>".
--instance-filter-zones
=[INSTANCE_FILTER_ZONES
,…]- A filter that targets instances in any of the specified zones. Leave empty to target instances in any zone.
-
Filters for selecting which instances to patch:
- OPTIONAL FLAGS
-
--async
- Return immediately, without waiting for the operation in progress to complete.
--description
=DESCRIPTION
- Textual description of the patch job.
--display-name
=DISPLAY_NAME
- Display name for this patch job. This does not have to be unique.
--dry-run
- Whether to execute this patch job as a dry run. If this patch job is a dry run, instances are contacted, but the patch is not run.
--duration
=DURATION
-
Total duration in which the patch job must complete. If the patch does not
complete in this time, the process times out. While some instances might still
be running the patch, they will not continue to work after completing the
current step. See $ gcloud topic
datetimes for information on specifying absolute time durations.
If unspecified, the job stays active until all instances complete the patch.
--mig-instances-allowed
- If set, patching of VMs that are part of a managed instance group (MIG) is allowed.
--reboot-config
=REBOOT_CONFIG
-
Post-patch reboot settings.
REBOOT_CONFIG
must be one of:always
- Always reboot the machine after the update completes.
default
- The agent decides if a reboot is necessary by checking signals such as registry keys or '/var/run/reboot-required'.
never
- Never reboot the machine after the update completes.
-
Settings for machines running Apt:
--apt-dist
-
If specified, machines running Apt use the
apt-get dist-upgrade
command; otherwise theapt-get upgrade
command is used. -
At most one of these can be specified:
--apt-excludes
=[APT_EXCLUDES
,…]- List of packages to exclude from update.
--apt-exclusive-packages
=[APT_EXCLUSIVE_PACKAGES
,…]- An exclusive list of packages to be updated. These are the only packages that will be updated. If these packages are not installed, they will be ignored.
-
Post-patch step settings for Linux machines:
--post-patch-linux-executable
=POST_PATCH_LINUX_EXECUTABLE
-
A set of commands to run on a Linux machine after an OS patch completes.
Commands must be supplied in a file. If the file contains a shell script,
include the shebang line.
The path to the file must be supplied in one of the following formats:
An absolute path of the file on the local filesystem.
A URI for a Google Cloud Storage object with a generation number.
--post-patch-linux-success-codes
=[POST_PATCH_LINUX_SUCCESS_CODES
,…]- Additional exit codes that the executable can return to indicate a successful run. The default exit code for success is 0.
-
Post-patch step settings for Windows machines:
--post-patch-windows-executable
=POST_PATCH_WINDOWS_EXECUTABLE
-
A set of commands to run on a Windows machine after an OS patch completes.
Commands must be supplied in a file. If the file contains a PowerShell script,
include the .ps1 file extension. The PowerShell script executes with flags
-NonInteractive
,-NoProfile
, and-ExecutionPolicy Bypass
.The path to the file must be supplied in one of the following formats:
An absolute path of the file on the local filesystem.
A URI for a Google Cloud Storage object with a generation number.
--post-patch-windows-success-codes
=[POST_PATCH_WINDOWS_SUCCESS_CODES
,…]- Additional exit codes that the executable can return to indicate a successful run. The default exit code for success is 0.
-
Pre-patch step settings for Linux machines:
--pre-patch-linux-executable
=PRE_PATCH_LINUX_EXECUTABLE
-
A set of commands to run on a Linux machine before an OS patch begins. Commands
must be supplied in a file. If the file contains a shell script, include the
shebang line.
The path to the file must be supplied in one of the following formats:
An absolute path of the file on the local filesystem.
A URI for a Google Cloud Storage object with a generation number.
--pre-patch-linux-success-codes
=[PRE_PATCH_LINUX_SUCCESS_CODES
,…]- Additional exit codes that the executable can return to indicate a successful run. The default exit code for success is 0.
-
Pre-patch step settings for Windows machines:
--pre-patch-windows-executable
=PRE_PATCH_WINDOWS_EXECUTABLE
-
A set of commands to run on a Windows machine before an OS patch begins.
Commands must be supplied in a file. If the file contains a PowerShell script,
include the .ps1 file extension. The PowerShell script executes with flags
-NonInteractive
,-NoProfile
, and-ExecutionPolicy Bypass
.The path to the file must be supplied in one of the following formats:
An absolute path of the file on the local filesystem.
A URI for a Google Cloud Storage object with a generation number.
--pre-patch-windows-success-codes
=[PRE_PATCH_WINDOWS_SUCCESS_CODES
,…]- Additional exit codes that the executable can return to indicate a successful run. The default exit code for success is 0.
-
Rollout configurations for this patch job:
--rollout-mode
=ROLLOUT_MODE
-
Mode of the rollout.
ROLLOUT_MODE
must be one of:concurrent-zones
- Patches are applied to VMs in all zones at the same time.
zone-by-zone
- Patches are applied one zone at a time. The patch job begins in the region with the lowest number of targeted VMs. Within the region, patching begins in the zone with the lowest number of targeted VMs. If multiple regions (or zones within a region) have the same number of targeted VMs, a tie-breaker is achieved by sorting the regions or zones in alphabetical order.
-
Disruption budget for this rollout. A running VM with an active agent is
considered disrupted if its patching operation fails anytime between the time
the agent is notified until the patch process completes.
At most one of these can be specified:
--rollout-disruption-budget
=ROLLOUT_DISRUPTION_BUDGET
- Number of VMs per zone to disrupt at any given moment.
--rollout-disruption-budget-percent
=ROLLOUT_DISRUPTION_BUDGET_PERCENT
- Percentage of VMs per zone to disrupt at any given moment. The number of VMs calculated from multiplying the percentage by the total number of VMs in a zone is rounded up.
-
Settings for machines running Windows:
At most one of these can be specified:
--windows-exclusive-patches
=[WINDOWS_EXCLUSIVE_PATCHES
,…]- An exclusive list of Knowledge Base (KB) IDs to be updated. These are the only patches that will be updated.
-
Windows patch options
--windows-classifications
=[WINDOWS_CLASSIFICATIONS
,…]-
List of classifications to use to restrict the Windows update. Only patches of
the given classifications are applied. If omitted, a default Windows update is
performed. For more information on classifications, see: https://support.microsoft.com/en-us/help/824684.
WINDOWS_CLASSIFICATIONS
must be one of:critical
,security
,definition
,driver
,feature-pack
,service-pack
,tool
,update-rollup
,update
. --windows-excludes
=[WINDOWS_EXCLUDES
,…]- Optional list of Knowledge Base (KB) IDs to exclude from the update operation.
-
Settings for machines running Yum:
At most one of these can be specified:
--yum-exclusive-packages
=[YUM_EXCLUSIVE_PACKAGES
,…]- An exclusive list of packages to be updated. These are the only packages that will be updated. If these packages are not installed, they will be ignored.
-
Yum patch options
--yum-excludes
=[YUM_EXCLUDES
,…]-
Optional list of packages to exclude from updating. If this argument is
specified, machines running Yum exclude the given list of packages using the Yum
--exclude
flag. --yum-minimal
-
If specified, machines running Yum use the command
yum update-minimal
; otherwise the patch usesyum-update
. --yum-security
-
If specified, machines running Yum append the
--security
flag to the patch command.
-
Settings for machines running Zypper:
At most one of these can be specified:
--zypper-exclusive-patches
=[ZYPPER_EXCLUSIVE_PATCHES
,…]- An exclusive list of patches to be updated. These are the only patches that will be installed using the 'zypper patch patch:<patch_name>' command.
-
Zypper patch options
--zypper-categories
=[ZYPPER_CATEGORIES
,…]- If specified, machines running Zypper install only patches with the specified categories. Categories include security, recommended, and feature.
--zypper-excludes
=[ZYPPER_EXCLUDES
,…]- List of Zypper patches to exclude from the patch job.
--zypper-severities
=[ZYPPER_SEVERITIES
,…]- If specified, machines running Zypper install only patch with the specified severities. Severities include critical, important, moderate, and low.
--zypper-with-optional
-
If specified, machines running Zypper add the
--with-optional
flag tozypper patch
. --zypper-with-update
-
If specified, machines running Zypper add the
--with-update
flag tozypper patch
.
- GCLOUD WIDE FLAGS
-
These flags are available to all commands:
--access-token-file
,--account
,--billing-project
,--configuration
,--flags-file
,--flatten
,--format
,--help
,--impersonate-service-account
,--log-http
,--project
,--quiet
,--trace-token
,--user-output-enabled
,--verbosity
.Run
$ gcloud help
for details. - NOTES
-
This variant is also available:
gcloud beta compute os-config patch-jobs execute
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-02-06 UTC.
[{
"type": "thumb-down",
"id": "hardToUnderstand",
"label":"Hard to understand"
},{
"type": "thumb-down",
"id": "incorrectInformationOrSampleCode",
"label":"Incorrect information or sample code"
},{
"type": "thumb-down",
"id": "missingTheInformationSamplesINeed",
"label":"Missing the information/samples I need"
},{
"type": "thumb-down",
"id": "otherDown",
"label":"Other"
}]
[{
"type": "thumb-up",
"id": "easyToUnderstand",
"label":"Easy to understand"
},{
"type": "thumb-up",
"id": "solvedMyProblem",
"label":"Solved my problem"
},{
"type": "thumb-up",
"id": "otherUp",
"label":"Other"
}]
{
"last_modified": "Last updated 2024-02-06 UTC.",
"state": ""
}