gcloud-help/gcloud/compute/os-config/patch-jobs/execute

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 the us-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 and europe-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 is test and app label is web,
    run:

        $ gcloud compute os-config patch-jobs execute \
        --instance-filter-group-labels="env=test,app=web"

    To patch all instances where the env label is test and app label is web or
    where the env label is staging and app label is web, 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 prefix windows- 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.

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 the apt-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 uses yum-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
            to zypper patch.

         --zypper-with-update
            If specified, machines running Zypper add the --with-update flag to
            zypper 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