A RetroSearch Logo

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Search Query:

Showing content from http://cloud.google.com/compute/docs/os-patch-management/create-patch-job below:

Create patch jobs | VM Manager

Skip to main content Create patch jobs

Stay organized with collections Save and categorize content based on your preferences.

You can use Patch to apply operating system patches across a group of virtual machine (VM) instances.

To apply patches to your VMs, complete the following steps:

  1. Set up your VM.
  2. Run a patch job.
Before you begin Limitations Supported operating systems

For the full list of operating systems and versions that support Patch, see Operating system details.

Set up your VM

To use the Patch feature, complete the following steps:

  1. For all VMs, set up VM Manager.
  2. For Windows VMs, Google recommends disabling automatic updates on the VMs. This reduces conflicts between the Windows automatic updates and the Patch service.
Permissions

Owners of a Google Cloud project have full access to run and manage patch jobs. For all other users, you need to grant permissions. You can grant one of the following granular roles:

Caution: The Patch Job Executor role includes the osconfig.patchJobs.exec permission that provides access to manage software packages on VMs. By granting this role, you risk granting users unintended access to run code on VMs. To mitigate this risk, we recommend that you follow the principle of least privilege and provide only the required access to each user and monitor the usage of this IAM permission by users.

For example, to grant a user access to run patch jobs, use the following command:

gcloud projects add-iam-policy-binding project-id \
    --member user:user-id@gmail.com \
    --role roles/osconfig.patchJobExecutor

Replace the following:

Run patch jobs

You can run a patch job by using either the Google Cloud console, Google Cloud CLI, or REST.

When you run a patch job, the patching of the VMs starts simultaneously on all instances specified by the instance filter.

Note: You can patch a maximum of 500 VMs in a single patch job. All VMs targeted by a single patch job are patched simultaneously.

After you have started a patch job, you can monitor your patches using the Patch dashboard. It takes approximately 30 minutes after a patch job starts before the data is populated on the dashboard.

Note: Targeting all VMs in a single patch deployment might cause a reduction in system availability. We recommend that you keep this in consideration when planning your maintenance window or that you use instance filters and patch VMs in small batches. Console
  1. In the Google Cloud console, go to the Compute Engine > VM Manager > Patch page.

    Go to the Patch page

  2. Click New patch deployment.
  3. In the Target VMs section, select the zone that contains the VMs that you want to patch. You can also choose to select all zones.

    After you select the zones, you can then further filter the VMs within that zone.

    Note: In the Google Cloud console, you can only filter by name prefix or label. If you need to apply other types of instance filters use either the Google Cloud CLI, or REST.

    For example, to patch specific VMs in the zones you selected, enter the name and label filters similar to the following:

  4. In the Patch configuration section, configure the patch.

    1. Specify a Name for your patch.
    2. Select the required updates for your operating system. For more information, see patch configuration.
  5. In the Scheduling section, complete the following:

  6. In the Rollout options section, configure the patch rollout options:

  7. Optional: In the Advanced options section, you can complete the following tasks:

  8. Click Deploy.

gcloud

Use the os-config patch-jobs execute command to run a patch job. Replace instance-filter with the instance filter that you want. For more information about instance filters, see instance filters.

gcloud compute os-config patch-jobs execute instance-filter

For more information about what updates get applied, see what is included in an OS patch job. To customize your updates, use the optional flags.

Examples

Example 1 To run a patch job with the following configurations:

gcloud compute os-config patch-jobs execute \
    --instance-filter-names="zones/us-east1-b/instances/instance-1" \
    --description "patch for instance-1"

Example 2 Suppose you want to run a patch job asynchronously with the following configurations:

You would run the following command:

gcloud compute os-config patch-jobs execute \
    --instance-filter-all \
    --duration="1h30m" --reboot-config="DEFAULT" \
    --apt-dist --windows-exclusive-patches=4339284 \
    --yum-minimal --yum-security \
    --async
REST

In the API, create a POST request to run a new patch job. You must explicitly define all of the required configuration fields as described in the patchJobs.execute API documentation.

For more information about what updates get applied, see what is included in an OS patch job. To customize your updates, use the PatchConfig parameters.

For example, a patch job with only the required fields looks like the following.

POST https://osconfig.googleapis.com/v1/projects/project-id/patchJobs:execute

{
  "instanceFilter": instance-filter
}

Replace the following:

Examples

Example 1 Suppose you want to run a patch job on an instance named instance1 located in us-east1-b. In this example, we add a description and specify that the job runs for 1 hour 30 minutes. Replace project-id with your project ID.

POST https://osconfig.googleapis.com/v1/projects/project-id/patchJobs:execute

{
  "description":"patch instance1 in us-east1-b",
  "duration":"5400s",
  "instanceFilter":{
    "instances":[
      "zones/us-east1-b/instances/instance1"
    ]
  }
}

Example 2 The following patch job selects VMs that have the following configurations:

In the following command, replace project-id with your project ID.

POST https://osconfig.googleapis.com/v1/projects/project-id/patchJobs:execute

{
  "instanceFilter":{
    "groupLabels":[
      {
        "labels":{
          "env":"dev",
          "app":"web"
        }
      }
    ],
    "instanceNamePrefixes":[
      "test-"
    ],
    "zones":[
      "asia-east1-b",
      "asia-east1-c"
    ]
  }
}

Example 3

Suppose you want to run a patch job with the following configurations:

You would create the following request:

In the following command, replace project-id with your project ID.

POST https://osconfig.googleapis.com/v1/projects/project-id/patchJobs:execute

{
 "duration":"5400s",
 "instanceFilter":{
   "all":true
 },
 "patchConfig":{
   "rebootConfig":"DEFAULT",
   "apt":{
     "type":"DIST"
   },
   "yum":{
     "security":true,
     "minimal":true
   },
   "windowsUpdate":{
     "exclusivePatches":"4339284"
   }
 }
}
Instance filters

You can specify the instances to be included in a patch job by using filters. The following filters are supported for patch jobs:

You can also run patch jobs on all instances in a Google Cloud project by setting the all field in instanceFilter to true. For more information, see example instance filters.

Note: Instance filters are resolved when the patch job starts. This means that a scheduled patch deployment that targets all VMs in a Google Cloud project patches all VMs that are available in the Google Cloud project at the time the patch starts running. Example instance filters Scenario gcloud filter API filter All instances in a Google Cloud project
--instance-filter-all
{
  "instanceFilter":{
    "all":"true"
  }
}
An instance with the name instance1 that is located in the zone us-east1-b.
--instance-filter-names="zones/us-east1-b/instances/instance1"
{
  "instanceFilter":{
    "instances":[
      "zones/us-east1-b/instances/instance1"
    ]
  }
}
Instances with the prefix app-
--instance-filter-name-prefixes="app-"
{
  "instanceFilter":{
    "instanceNamePrefixes":[
      "app-"
    ]
  }
}
Instances in zones us-east1-b or us-east1-c
--instance-filter-zones="us-east1-b","us-east1-c"
{
  "instanceFilter":{
    "zones":[
      "us-east1-b",
      "us-east1-c"
    ]
  }
}
Instances with the combination label of env=dev and app=web as well as instances with env=dev and app=worker.
--instance-filter-group-labels="env=dev,app=web"
--instance-filter-group-labels="env=dev,app=worker"
{
  "instanceFilter":{
    "groupLabels":[
      {
        "labels":{
          "env":"dev",
          "app":"web"
        }
      },
      {
        "labels":{
          "env":"dev",
          "app":"worker"
        }
      }
    ]
  }
}

Combining instance filters

Instance filters can also be combined. For example, to run a patch job for instances that have the prefix test-, that are located in the zone us-east1-c, and that have the labels env=dev and app=web, run the following command:

gcloud compute os-config patch-jobs execute \
    --instance-filter-name-prefixes="test-" \
    --instance-filter-zones="us-east1-c" \
    --instance-filter-group-labels="env=prod,app=web"
Patch configuration

When running a patch job, you can specify parameters to control the patches that are applied on the VM. The patch configuration parameters are platform dependent and are often passed through to the underlying system update tools. The actual patches are sourced from the package repositories (Linux) or the Windows Update server (Windows) that is configured on the VM.

You can specify the following patch configurations for your VMs:

Optionally, for all the supported operating systems, you can select to install approved patches only by specifying these updates. This lets you enter a list of approved packages or patches. When you select these approved patches, only the approved packages or patches are installed. All other patch configuration parameters are skipped during the update.

Examples Console
  1. Follow the steps outlined in the console tab for creating either a patch job or a patch deployment.
  2. In the Patch configuration section, select the parameters for your patch job.
  3. Make any additional configurations that are needed for your patch job or deployment.
  4. Click Deploy.
gcloud

For example, to run a patch job on all instances in the zone northamerica-northeast1-a with specific patch configurations for different operating systems, run the gcloud compute os-config patch-jobs execute command:

gcloud compute os-config patch-jobs execute \
    --instance-filter-zones="northamerica-northeast1-a" \
    --apt-dist \
    --yum-security \
    --yum-minimal \
    --zypper-categories=security \
    --windows-classifications=critical,security \
    --reboot-config=default

To learn more about the supported options, run the following command:

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

For example, to run a patch job on all instances in the zone northamerica-northeast1-a with specific patch configurations for different operating systems, run the following command:

POST https://osconfig.googleapis.com/v1/projects/project-id/patchJobs:execute
{
    "instanceFilter":{
        "zones":[
            "northamerica-northeast1-a"
        ]
    },
    "patchConfig":{
        "apt": {
            "type": "dist-upgrade"
        },
        "yum": {
            "security": true,
            "minimal": true
        },
        "zypper": {
            "categories": ["security"]
        },
        "windowsUpdate": {
            "classifications": ["CRITICAL", "SECURITY"]
        },
        "rebootConfig": "DEFAULT"
    }
}

To learn more about the supported parameters, review the PatchConfig API documentation.

Maintenance window

A maintenance window is the total length of time that you allow a patch job to run. Patch jobs will timeout if they don't complete within the specified maintenance window.

For example, if you set a maintenance window of 60 minutes, then no new patch jobs will be initiated 60 minutes after the start time. Some processes such as downloading a file or rebooting might occur outside of this maintenance window, however no new patch jobs will be initiated.

Reboot options

When running a patch job, you can specify the reboot options for the patch. The following options are available:

Pre-patch and post-patch scripts

When running a patch job, you can specify scripts to be run as part of the patching process. These scripts are useful for performing tasks such as shutting down an application and performing health checks.

A patch job accepts one pre-patch and one post-patch script for Linux, and one pre-patch and one post-patch script for Windows. Linux and Windows scripts must be provided using the appropriate flags, parameters, or sections when specified from the Google Cloud CLI, REST, or the Google Cloud console respectively. Linux scripts run on Linux VMs only and Windows scripts run on Windows VMs only.

Note: Linux scripts must begin with a shebang line to specify which shell should execute the script. For example, add #!/bin/bash to specify the Bash shell.

These script files can either be stored on the VM or in a versioned Cloud Storage bucket.

Store patch scripts in Cloud Storage buckets

If you want to use a Cloud Storage bucket to store your scripts, create a Cloud Storage bucket and upload your scripts to the bucket. When using a Cloud Storage bucket, consider the following:

Console
  1. Follow the steps outlined in the console tab for creating either a patch job or a patch deployment.
  2. In the Advanced options section, for both the pre-patch and post-patch sections, click Browse. A Cloud Storage object page displays.
  3. From the Cloud Storage object page, select the Cloud Storage bucket that contains the script, then select the Cloud Storage object or file.
  4. Make any additional configurations that are needed for your patch job or deployment.
  5. Click Deploy.
gcloud

For example, to run a patch job on all instances in the zone northamerica-northeast1-a with both pre and post patch script for Linux and Windows instances, run the following command:

gcloud compute os-config patch-jobs execute \
    --instance-filter-zones="northamerica-northeast1-a" \
    --async \
    --pre-patch-linux-executable="/tmp/pre_patch_script.sh" \
    --post-patch-linux-executable="gs://my-patch-scripts/linux/post_patch_script#1523477886880" \
    --pre-patch-windows-executable="C:\\Users\\user\\pre-patch-script.cmd" \
    --post-patch-windows-executable="gs://my-patch-scripts/windows/post_patch_script.ps1#135920493447"

To learn more about acceptable file formats, run the following command:

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

For example, to run a patch job on all instances in the zone northamerica-northeast1-a with both pre and post patch script for Linux and Windows instances, run the following command:

POST https://osconfig.googleapis.com/v1/projects/project-id/patchJobs:execute

{
  "instanceFilter":{
    "zones":[
      "northamerica-northeast1-a"
    ]
  },
  "patchConfig":{
    "preStep":{
      "linuxExecStepConfig":{
        "localPath":"/tmp/pre_patch_script.sh"
      },
      "windowsExecStepConfig":{
        "interpreter":"SHELL",
        "localPath":"C:\\Users\\user\\pre-patch-script.cmd"
      }
    },
    "postStep":{
      "linuxExecStepConfig":{
        "gcsObject":{
          "bucket":"my-patch-scripts",
          "generationNumber":"1523477886880",
          "object":"linux/post_patch_script"
        }
      },
      "windowsExecStepConfig":{
        "gcsObject":{
          "bucket":"my-patch-scripts",
          "generationNumber":"135920493447",
          "object":"windows/post_patch_script.ps1"
        },
        "interpreter":"POWERSHELL"
      }
    }
  }
}

To learn more about acceptable file formats, review the ExecStepConfig section of the PatchConfig API documentation.

Patch rollout options

You can choose to either patch VMs one zone at a time (zone by zone), or to patch all zones at once (concurrent zones).

Along with making a selection for the zone roll out, you can also specify a zone disruption budget for your VMs.

Zone disruption budget

A disruption budget is the maximum number (or percentage) of VMs per zone to disrupt at any given moment.

What is considered a disrupted VM?

During patching, a VM is considered disrupted from the time the OS Config agent is notified to begin until patching has completed. This disruption time includes the time to complete reboot and any post-patch steps.

A VM is also counted as a part of the disruption budget if it meets any of the following conditions:

Note: VMs that are not running or those that don't have an active agent don't count toward this disruption budget. How disruption budgets work

For zone-by-zone rollouts, if the disruption budget in a zone is exceeded, the patch job stops. This happens because continuing to the next zone requires completion of the patch process in the previous zone.

For example, if the disruption budget has a value of 10, and 8 VMs fail to patch in the current zone, the patch job continues to patch 2 VMs at a time until the zone is completed. When that zone is completed successfully, patching begins with 10 VMs at a time in the next zone. If 10 VMs in the next zone fail to patch, the patch job stops.

Examples Console
  1. Follow the steps outlined in the console tab for creating either a patch job or a patch deployment.
  2. In the Rollout options section, configure the rollout options:
  3. Make any additional configurations that are needed for your patch job or deployment.
  4. Click Deploy.
gcloud

Example 1

This example shows the os-config patch-jobs execute command for running a patch job with the following specifications:

gcloud compute os-config patch-jobs execute \
   --instance-filter-all \
   --rollout-mode=zone-by-zone \
   --rollout-disruption-budget=10

Example 2

This example shows the os-config patch-jobs execute command for running a patch job with the following specifications:

gcloud compute os-config patch-jobs execute \
   --instance-filter-all \
   --rollout-mode=concurrent-zones \
   --rollout-disruption-budget-percent=50
REST

This example shows the patchJobs.execute method for running a patch job with the following specifications:

POST https://osconfig.googleapis.com/v1/projects/project-id/patchJobs:execute

{
  "instanceFilter":{
    "zones":[
      "us-central1-a",
      "us-central1-c",
      "us-central1-f"
    ]
  },
  "rollout": {
    "disruptionBudget": {
      "percent": 25
    },
    "mode": "CONCURRENT_ZONES"
  }
}

To learn more about patch rollout, review the PatchRollout API documentation.

Enable patching Microsoft software on Windows VMs

When you run a patch job on Windows VMs, by default, Patch applies only the patches for the Windows operating system.

You can apply updates for Microsoft software such as Microsoft SQL Server, SharePoint Server, or .NET framework running on your Windows VMs when you run a patch job. By default, patching these applications is disabled to avoid disruption of service and to separate planned updates for these software. To enable patching Microsoft software automatically, you can either use the Windows UI or the PowerShell.

Windows UI
  1. In the Windows Start menu, select Settings > Update & Security > Windows Update.
  2. In the Advanced options section, toggle on Receive updates for other Microsoft products when you update Windows.
PowerShell
 $service_manager = New-Object -ComObject 'Microsoft.Update.ServiceManager'
 $service_manager.AddService2("7971f918-a847-4430-9279-4a52d1efe18d",7,"")
Debug a patch job

If your patch fails, you can use the following steps to help find and resolve the issues.

  1. Review the instance details for the affected patch job. This helps you to identify which instances failed or what state they are stuck in. The instance details list also contains a brief error message for each instance.

    If a patch fails with a status of NO_AGENT_DETECTED or TIMED_OUT, this usually means that the service sent a request to the agent to begin patching but never heard back from the agent. Review the following possible causes and fixes:

  2. If the instance details don't provide enough information, review the Cloud Logging logs or serial port console. The OS Config agent writes its log entries to both locations. In Cloud Logging, you can filter using the patch job ID to see all log entries related to that patch job. You can also enable debug logging by setting the osconfig-log-level=debug metadata value at the VM or Google Cloud project level.

What's next?

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 2025-08-07 UTC.

[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-07 UTC."],[[["Patch can be used to apply operating system updates to virtual machines (VMs) in a single Google Cloud project, but not across multiple projects, even in Shared VPCs."],["To use Patch, you need to set up VM Manager and optionally disable automatic updates on Windows VMs to avoid conflicts, and project owners have full access to patch jobs, while other users need specific granular roles assigned."],["Patch jobs can be run using the Google Cloud console, CLI, or REST API, and they allow filtering of target instances by name, name prefix, zone, or label, and have a maximum of 500 VMs in a single job."],["Patch configurations can be customized based on the operating system, including options for Windows, RHEL, Rocky Linux, CentOS, Debian, Ubuntu, and SuSE, with features like specifying patch classifications, security updates, or approved patches only."],["Patch jobs support maintenance windows, reboot options, pre-patch and post-patch scripts, and rollout options, including zone-by-zone or concurrent patching, and also allow for specifying a disruption budget to control the number of VMs affected simultaneously."]]],[]]


RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4