Manage patch jobs

After you create 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 for your 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 the Google Cloud console, the Google Cloud CLI, or REST.

Before you begin

Review OS Config quotas.
If you haven't already, then set up authentication. Authentication is the process by which your identity is verified 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
1. Install the Google Cloud CLI, then initialize it by running the following command:
  gcloud init
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
2. 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.
For more information, see Authenticate 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 the following granular roles:

roles/osconfig.patchJobExecutor: Contains permissions to run, cancel, get, and list patch jobs. It also contains permissions to view instance details for a patch job.
roles/osconfig.patchJobViewer: Contains permissions for read-only access to get and list patch jobs. It also contains permissions to view instance details for a patch job.

List patch jobs

View a list of all active and completed jobs.

console

In the Google Cloud console, go to the Compute Engine > VM Manager > Patch page.
Go to the Patch page
Select the Patch Jobs tab.

gcloud

Use the os-config patch-jobs list command to list patch jobs.

gcloud compute os-config patch-jobs list

For the Google Cloud CLI, the default output returns the 10 most recent patch jobs whether they are completed or active. You can override this setting, by using the --limit flag.

The output resembles the following:

ID                                          NAME    DESCRIPTION               CREATE_TIME               UPDATE_TIME               STATE                  TARGETED_INSTANCES
23b0815e-1c94-4dc6-91b1-30a6da395cb9                                          2019-11-05T20:22:54.150Z  2019-11-06T19:40:08.641Z  COMPLETED_WITH_ERRORS  4
4116ad72-bd57-4e48-94dc-7a577dc707b6                                          2019-08-23T20:36:03.068Z  2019-08-23T20:36:15.984Z  CANCELED               2
06856cbe-9a7b-498e-9105-9ae4eb566511                                          2019-08-12T20:27:38.410Z  2019-08-12T20:28:37.583Z  SUCCEEDED              1
04a15964-9eaa-4282-96f5-9cd535352cf6                                          2019-08-12T17:48:22.938Z  2019-08-12T17:48:42.274Z  SUCCEEDED              0
21dc1e06-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 the patch jobs that have a status of SUCCEEDED sorted by creation time and in ascending 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-9cd535352cf6
https://osconfig.googleapis.com/v1/projects/1234567/patchJobs/06856cbe-9a7b-498e-9105-9ae4eb566511

For a full list of flags, review the os-config patch-jobs list command.

REST

In the API, create a GET request to the patchJobs.list method. Replace project-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 OS patch management.

console

In the Google Cloud console, go to the Compute Engine > VM Manager > Patch page.
Go to the Patch page
Select the Patch Jobs tab.
Click the name of the patch job that you want to review.
Scroll-down to Updated VM instances.

gcloud

Use the os-config patch-jobs list-instance-details command to list the details for all VMs in a specific patch job. Replace patch-job-id with the ID for your patch job.

gcloud compute os-config patch-jobs list-instance-details patch-job-id

For example, to view the details for all instances that are a part of patch job 23b0815e-1c94-4dc6-91b1-30a6da395cb9, run the following command:

gcloud compute os-config patch-jobs list-instance-details 23b0815e-1c94-4dc6-91b1-30a6da395cb9

The output resembles the following:

NAME                        ZONE           STATE      FAILURE_REASON
instance-1                  us-central1-a  SUCCEEDED
guest-policy-test-instance  us-east1-c     TIMED_OUT  Instance timed out while in state: APPLYING_PATCHES after PT1H2.225S
my-centos                   us-west1-b     SUCCEEDED
my-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 sorted by instance name in descending order, run the following command. Replace patch-job-id with the ID for your patch job.

gcloud compute os-config patch-jobs list-instance-details patch-job-id \
   --filter="state=INACTIVE" \
   --sort-by="~name"

For a full list of flags, review the os-config patch-jobs list-instance-details command.

REST

In the API, create a GET request to the patchJobs.instanceDetails method.

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 the Compute Engine > VM Manager > Patch page.
Go to the Patch page
Select the Patch Jobs tab.
Click the name of the patch job that you want to review.
Review the Update info section.

gcloud

Use the os-config patch-jobs describe command to describe a patch job. Replace patch-job-id with the ID for your patch job.

gcloud compute os-config patch-jobs describe patch-job-id

For example, to view information about patch job 23b0815e-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-30a6da395cb9
patchConfig: {}
percentComplete: 100.0
state: COMPLETED_WITH_ERRORS
updateTime: '2019-11-06T19:40:08.641Z'

REST

In the API, create a GET request to the patchJobs.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 it is on but does not continue after that. Sub-task refers to a task performed by the 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 to completion, but the agent does not initiate additional tasks for that patch job.

console

In the Google Cloud console, go to the Compute Engine > VM Manager > Patch page.
Go to the Patch page
1. Select the Patch Jobs tab.
2. Expand the Actions menu for the patch job that you want to cancel.
3. Select Cancel.

gcloud

Use the os-config patch-jobs cancel command to cancel a patch job. Replace patch-job-id with the ID for your patch job.

gcloud compute os-config patch-jobs cancel patch-job-id

REST

In the API, create a POST request to the patchJobs.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 about Patch.
Learn more about patch compliance status.
Create a patch job.
Schedule patch jobs.

Manage patch jobs

Before you begin

Console

gcloud

REST

Permissions

List patch jobs

console

gcloud

REST

List all VM instance details for a specific patch job

console

gcloud

REST

Describe patch jobs

console

gcloud

REST

Cancel patch jobs

console

gcloud

REST

What's next?