Manage patch jobs
After youcreate a patch job,you can use the following procedures to review and manage your patches:
- List patch jobs: View a list of all active and completed jobs.
- List VM instance details: Review patch status foryour VM instances.
- Describe patch job: Get details about a specific patch job.
- Cancel a patch job: Cancel a specific patch job.
You can manage your patch jobs using either theGoogle Cloud console, theGoogle Cloud CLI, orREST.
Before you begin
- ReviewOS Config quotas.
- If you haven't already, set upauthentication. Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:
gcloudinit
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.- Set a default region and zone.
REST
To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:
gcloudinit
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.For more information, seeAuthenticate for using REST in the Google Cloud authentication documentation.
Permissions
Owners of a project have full access to run and manage patch jobs.For all other users, you need to grant permissions. You can grant one of thefollowing granular roles:
roles/osconfig.patchJobExecutor: Contains permissions to run, cancel, get,and list patch jobs. It also contains permissions to view instance details fora patch job.roles/osconfig.patchJobViewer: Contains permissions for read-only access toget and list patch jobs. It also contains permissions to view instance detailsfor a patch job.
List patch jobs
View a list of all active and completed jobs.
console
- In the Google Cloud console, go to theCompute Engine >VM Manager >Patch page.
- Select thePatch Jobs tab.
gcloud
Use theos-config patch-jobs listcommand to list patch jobs.
gcloud compute os-config patch-jobs list
For the Google Cloud CLI, the default output returns the 10 most recentpatch jobs whether they are completed or active. You can overridethis setting, by using the--limit flag.
The output resembles the following:
ID NAME DESCRIPTION CREATE_TIME UPDATE_TIME STATE TARGETED_INSTANCES23b0815e-1c94-4dc6-91b1-30a6da395cb9 2019-11-05T20:22:54.150Z 2019-11-06T19:40:08.641Z COMPLETED_WITH_ERRORS 44116ad72-bd57-4e48-94dc-7a577dc707b6 2019-08-23T20:36:03.068Z 2019-08-23T20:36:15.984Z CANCELED 206856cbe-9a7b-498e-9105-9ae4eb566511 2019-08-12T20:27:38.410Z 2019-08-12T20:28:37.583Z SUCCEEDED 104a15964-9eaa-4282-96f5-9cd535352cf6 2019-08-12T17:48:22.938Z 2019-08-12T17:48:42.274Z SUCCEEDED 021dc1e06-deee-4e3a-821e-8082a32abde5 testing patch job reboot 2019-07-24T22:45:07.451Z 2019-07-25T00:44:44.459Z TIMED_OUT 1
You can use more flags to filter, order, and format your search.For example, to filter the above output to list only the URIs for thepatch jobs that have a status ofSUCCEEDED sorted by creation time and inascending order, run the following command:
gcloud compute os-config patch-jobs list \ --filter="state=SUCCEEDED" \ --sort-by="create_time" --uri
The output resembles the following:
https://osconfig.googleapis.com/v1/projects/1234567/patchJobs/04a15964-9eaa-4282-96f5-9cd535352cf6https://osconfig.googleapis.com/v1/projects/1234567/patchJobs/06856cbe-9a7b-498e-9105-9ae4eb566511
For a full list of flags, review theos-config patch-jobs listcommand.
REST
In the API, create aGET request to thepatchJobs.listmethod. Replaceproject-id with your project ID.
GET https://osconfig.googleapis.com/v1/projects/project-id/patchJobs
List all VM instance details for a specific patch job
Review the patch job status for the full list of VM instances that use OSpatch management.
console
- In the Google Cloud console, go to theCompute Engine >VM Manager >Patch page.
- Select thePatch Jobs tab.
- Click the name of the patch job that you want to review.
- Scroll-down toUpdated VM instances.
gcloud
Use theos-config patch-jobs list-instance-detailscommand to list the details for all VMs in a specific patch job.Replacepatch-job-id with the ID for yourpatch job.
gcloud compute os-config patch-jobs list-instance-detailspatch-job-id
For example, to view the details for all instances that are apart of patch job23b0815e-1c94-4dc6-91b1-30a6da395cb9, run the followingcommand:
gcloud compute os-config patch-jobs list-instance-details 23b0815e-1c94-4dc6-91b1-30a6da395cb9
The output resembles the following:
NAME ZONE STATE FAILURE_REASONinstance-1 us-central1-a SUCCEEDEDguest-policy-test-instance us-east1-c TIMED_OUT Instance timed out while in state: APPLYING_PATCHES after PT1H2.225Smy-centos us-west1-b SUCCEEDEDmy-windows us-west1-b FAILED Error running pre-patch step: fork/exec /tmp/pre_patch_script.sh: no such file ..."
You can use more flags to filter, order, and format your search.For example, to list details for all inactive VMs sortedby instance name in descending order, run the following command. Replacepatch-job-id with the ID for your patch job.
gcloud compute os-config patch-jobs list-instance-detailspatch-job-id \ --filter="state=INACTIVE" \ --sort-by="~name"
For a full list of flags, review theos-config patch-jobs list-instance-detailscommand.
REST
In the API, create aGET request to thepatchJobs.instanceDetailsmethod.
GET https://osconfig.googleapis.com/v1/projects/project-id/patchJobs/patch-job-id/instanceDetails
Replace the following:
project-id: Your project ID.patch-job-id: Your patch job ID.
Describe patch jobs
Review detailed information for a patch job.
console
- In the Google Cloud console, go to theCompute Engine >VM Manager >Patch page.
- Select thePatch Jobs tab.
- Click the name of the patch job that you want to review.
- Review theUpdate info section.
gcloud
Use theos-config patch-jobs describecommand to describe a patch job. Replacepatch-job-id with the ID for your patch job.
gcloud compute os-config patch-jobs describepatch-job-id
For example, to view information aboutpatch job23b0815e-1c94-4dc6-91b1-30a6da395cb9, run the following command:
gcloud compute os-config patch-jobs describe 23b0815e-1c94-4dc6-91b1-30a6da395cb9
The output resembles the following:
createTime: '2019-11-05T20:22:54.150Z'errorMessage: Completed with 2 instance failure(s).filter: id=*instanceDetailsSummary: instancesFailed: '1' instancesSucceeded: '2' instancesTimedOut: '1'instanceFilter: {}name: projects/1234567/patchJobs/23b0815e-1c94-4dc6-91b1-30a6da395cb9patchConfig: {}percentComplete: 100.0state: COMPLETED_WITH_ERRORSupdateTime: '2019-11-06T19:40:08.641Z'REST
In the API, create aGET request to thepatchJobs.get method.
GET https://osconfig.googleapis.com/v1/projects/project-id/patchJobs/patch-job-id
Replace the following:
project-id: Your project ID.patch-job-id: Your patch job ID.
Cancel patch jobs
When cancelling a patch job, the OS Config agent finishes the sub-task that itis on but does not continue after that. Sub-task refers to a task performed bythe agent that cannot be halted.
For example, if the patch job is canceled while the VM instance is rebooting,the reboot (and any potential post-reboot auto-patching) still runs tocompletion, but the agent does not initiate additional tasks for that patch job.
Note: You can only cancel active patch jobs.console
- In the Google Cloud console, go to theCompute Engine >VM Manager >Patch page.
- Select thePatch Jobs tab.
- Expand theActionsmenu for the patch job that you want to cancel.
- SelectCancel.
gcloud
Use theos-config patch-jobs cancelcommand to cancel a patch job. Replacepatch-job-id with the ID for your patch job.
gcloud compute os-config patch-jobs cancelpatch-job-id
REST
In the API, create aPOST request to thepatchJobs.cancel method.
POST https://osconfig.googleapis.com/v1/projects/project-id/patchJobs/patch-job-id:cancel
Replace the following:
project-id: Your project ID.patch-job-id: Your patch job ID.
What's next?
- Learn more aboutPatch.
- Learn more aboutpatch compliance status.
- Create a patch job.
- Schedule patch jobs.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-15 UTC.