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

  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.

  Install the Google Cloud CLI, then initialize it by running the following command:

  gcloud init

  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.

gcloud compute os-config patch-jobs list

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

gcloud compute os-config patch-jobs list \
   --filter="state=SUCCEEDED" \
   --sort-by="create_time" --uri

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

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.

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

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

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 ..."

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

GET https://osconfig.googleapis.com/v1/projects/project-id/patchJobs/patch-job-id/instanceDetails

Describe patch jobs

Review detailed information for a patch job.

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

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

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'

GET https://osconfig.googleapis.com/v1/projects/project-id/patchJobs/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.

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

POST https://osconfig.googleapis.com/v1/projects/project-id/patchJobs/patch-job-id:cancel

What's next?

• Learn more about Patch.
• Learn more about patch compliance status.
• Create a patch job.
• Schedule patch jobs.