Managing patch jobs

After you create a patch job, you can use the following procedures to review and manage your patches:

You can manage your patch jobs using either the Google Cloud Console, the gcloud command-line tool, or the Cloud OS Config API.

Before you begin

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.
  • roles/containeranalysis.occurrences.viewer: Contains permissions for read-only access to Container Analysis API occurrences which is required to view patch compliance data.

Listing patch jobs

View a list of all active and completed jobs.

console

  1. In the Google Cloud Console, go to the Compute Engine > VM Manager > OS patch management page.

    Go to the OS patch management page

  2. 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 gcloud command-line tool, 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.

API

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

Listing 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

  1. In the Google Cloud Console, go to the Compute Engine > VM Manager > OS patch management page.

    Go to the OS patch management page

  2. Select the Patch Jobs tab.
  3. Click the name of the patch job that you want to review.
  4. 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.

API

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.

Describing patch jobs

Review detailed information for a patch job.

console

  1. In the Google Cloud Console, go to the Compute Engine > VM Manager > OS patch management page.

    Go to the OS patch management page

  2. Select the Patch Jobs tab.
  3. Click the name of the patch job that you want to review.
  4. 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'

API

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.

Cancelling 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 easily 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

  1. In the Google Cloud Console, go to the Compute Engine > VM Manager > OS patch management page.

    Go to the OS patch management page

    1. Select the Patch Jobs tab.
    2. Click the name of the patch job that you want to cancel.
    3. At the bottom of the page, click Abort.

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

API

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.

Retrieving patch compliance data

You can retrieve patch compliance data for a given VM instance by using the Container Analysis API.

  1. Set up access. You must have the containeranalysis.occurrences.list permission on your project. Alternatively, you can grant the roles/containeranalysis.occurrences.viewer role, which automatically provides all the necessary permissions.
  2. In the Container Analysis API, create a GET request to the projects.occurrences.list method. You must define all of the required configuration fields. For example, a request with the required fields looks like the following.

    GET https://containeranalysis.googleapis.com/v1/projects/project-id/occurrences/?filter=filter-expression
    

    Replace the following:

    • project-id: Your project ID.
    • filter-expression: The filter expression. For patch compliance, your filter expression must include the following parameters:

      kind="UPGRADE" AND resourceUrl="resource_url"
      • The kind of occurrence. For patch compliance, use UPGRADE.
      • The resource_url is the complete URL of the VM instance. For example, https://www.googleapis.com/compute/projects/my-project-id/zones/my-zone/instances/my-instance-id.

      The desired resource URL should be URL encoded, and embedded in a GET request as follows:

      GET https://containeranalysis.googleapis.com/v1/projects/project-id/occurrences/?filter=kind%3D%22UPGRADE%22%20AND%20resourceUrl%3D%22resource_url%22

What's next?