In addition to running patch jobs on demand, you might want to have patch jobs that run automatically based on a set schedule by creating a patch deployment.
Each patch deployment can have either a one-time schedule, which runs a patch job at one specific date and time, or a recurring schedule, which runs a patch job at a specified interval.
Instance filters
allow you to simultaneously patch many instances at the same
time. These filters are applied to each individual patch job at the time it
runs. This ensures that changes in your project are captured on a real-time basis.
For example, say a patch deployment is created to apply patches to all instances
in zone asia-souteast1-b
starting two weeks from now. At the time of creating
the patch, you had 20 instances in the zone but then 40 new instances are added
to the zone a few days later. Because the filter is applied at the time the patch
starts, all 60 instances are updated. This lets you add and remove instances
without the need to update the patch deployment schedule.
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
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- 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.
-
You can schedule your patch jobs using either the Google Cloud console, the Google Cloud CLI, or REST.
Permissions
Owners of a project have full access to create and manage patch deployments. For all other users, you need to grant permissions. You can grant one of the following granular roles:
roles/osconfig.patchDeploymentAdmin
: Contains permissions to create, delete, get, and list patch deployments.roles/osconfig.patchDeploymentViewer
: Contains permissions for read-only access to get and list patch deployments.
For example, to grant a user administrator access to patch deployments, run the following command:
gcloud projects add-iam-policy-binding project-id \ --member user:user-id@gmail.com \ --role roles/osconfig.patchDeploymentAdmin
Replace the following:
project-id
: The project ID.user-id
: The user's Google Workspace username.
Creating a patch deployment
When you create a patch deployment, the name of the patch deployment must meet the following naming requirements:
- Each name must be unique within a project
- Contain only lowercase letters, numbers, and hyphens
- Start with a letter
- End with a number or a letter
- Be between 1 and 63 characters
In the Google Cloud CLI and REST, the
name of the patch deployment is referred to as the patch-deployment-id
.
After you have started a patch deployment, 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.
console
- In the Google Cloud console, go to the Compute Engine > VM Manager > Patch page.
- Click New patch deployment.
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.
For example, to patch specific VMs in the zones you selected, enter the name and label filters similar to the following:
- Name prefix:
test-
- Labels:
env=dev
andapp=web
- Name prefix:
In the Patch configuration section, configure the patch.
- Specify a Name for your patch.
- Select the required updates for your operating system. For more information, see what is included in an OS patch job.
In the Scheduling section, complete the following:
- Select a schedule. You can schedule a one-time patch job or recurring patch jobs.
- (Optional) Set a duration or maintenance window.
In the Rollout options section, configure the patch rollout options:
- Select whether to patch one zone at a time or to patch zones concurrently.
- Set a disruption budget. A disruption budget is the number or percentage of VMs in a zone that you want to be disrupted at one time by the patching process.
(Optional) In the Advanced options section, you can complete the following tasks:
- Select a reboot option.
- Upload pre-patch and post-patch scripts. For more information about pre-patch and post-patch scripts, see Specifying pre-patch and post-patch scripts.
Click Deploy.
gcloud
Use the
os-config patch-deployments create
command to create a patch deployment.
gcloud compute os-config patch-deployments create patch-deployment-id \ --file patch-deployment-file
Replace the following:
patch-deployment-id
: The name of your patch deployment.patch-deployment-file
: The path to the YAML or JSON file that contains the configurations for the patch deployment.
Example patch deployment YAML files
The following sample YAML file can be used to create a recurring schedule for
all instances in the zones us-west2-b
and us-west2-c
. The recurring
schedule has the following specifications:
- Start date is January 09, 2019 at 7:30 PM
- End date is January 09, 2020 at 7:30 PM
- The time zone to use is "America/Los_Angeles"
- Runs every week on a Tuesday
instanceFilter: zones: - us-west2-b - us-west2-c recurringSchedule: frequency: WEEKLY weekly: dayOfWeek: TUESDAY timeOfDay: hours: 19 minutes: 30 timeZone: id: America/Los_Angeles startTime: '2019-09-01T12:00:00Z' endTime: '2020-09-01T12:00:00Z'
REST
In the API, create a POST
request to create a new patch deployment.
You must explicitly define all of the required configuration fields
as described in the
patchDeployments.create
API documentation. For example,
a patch deployment with the minimal required fields
(instance filter and schedule) looks like the following.
Replace project-id
with your project ID.
POST https://osconfig.googleapis.com/v1/projects/project-id/patchJobs:execute { "instanceFilter": instance-filter // Add one of the following parameters: "recurringSchedule": schedule "oneTimeSchedule": schedule }
Replace the following:
project-id
: Your project ID.instance-filter
: The filter parameters that you want. For more information about instance filters, see instance filters.schedule
: Provide either theoneTimeSchedule
orrecurringSchedule
parameter that details scheduling parameters such as date, time and frequency to run the patch job.
Examples
Example 1: Create a one-time schedule to run a patch job on January 10,
2020 at 12am UTC on all instances in zones us-west2-b
and us-west2-c
.
{ "instanceFilter":{ "zones":[ "us-west2-b", "us-west2-c" ] }, "oneTimeSchedule": { "executeTime": "2020-01-10T00:00:00Z" } }
Example 2: Create a recurring schedule for all instances in the zones
us-west2-b
and us-west2-c
. The recurring schedule has the following
specifications:
- Start date is January 09, 2019 at 7:30 PM
- End date is January 09, 2020 at 7:30 PM
- The time zone to use is "America/Los_Angeles"
- Runs every week on a Tuesday
POST https://osconfig.googleapis.com/v1/projects/project-id/patchDeployments { "instanceFilter":{ "zones":[ "us-west2-b", "us-west2-c" ] }, "recurringSchedule":{ "frequency":"WEEKLY", "weekly":{ "dayOfWeek":"TUESDAY" }, "timeOfDay":{ "hours":19, "minutes":30 }, "timeZone":{ "id":"America/Los_Angeles" }, "startTime":"2019-09-01T12:00:00Z", "endTime":"2020-09-01T12:00:00Z" } }
List patch deployments
console
- In the Google Cloud console, go to the Compute Engine > VM Manager > Patch page.
- Select the Scheduled deployments tab.
gcloud
Use the
os-config patch-deployments list
command to list patch deployments.
gcloud compute os-config patch-deployments list
This command returns all patch deployments. The output resembles the following:
NAME LAST_RUN NEXT_RUN FREQUENCY first-deployment 2019-12-18T00:07:00.738Z --- Once: Scheduled for 2019-12-18T00:07:00.000Z my-deployment1 2020-01-05T14:00:00.228Z 2020-01-12T14:00:00Z Recurring - Weekly my-deployment2 --- 2020-01-15T05:30:00Z Recurring - Monthly on specific date(s)
You can use more flags to limit and format your search.
For example, to list the first 10 patch deployments in pages of 2, run the
following command. Replace project-id
with your
project ID.
gcloud compute os-config patch-deployments list --limit 10 --page-size 2
REST
In the API, create a GET
request to the
patchDeployments.list
method. Replace project-id
with your project ID.
GET https://osconfig.googleapis.com/v1/projects/project-id/patchDeployments
Describe a patch deployment
console
- In the Google Cloud console, go to the Compute Engine > VM Manager > Patch page.
- Select the Scheduled deployments tab.
- Click the name of the deployment that you want to review.
gcloud
Use the
os-config patch-deployments describe
command to describe a patch deployment. Replace
patch-deployment-id
with the name for your patch deployment.
gcloud compute os-config patch-deployments describe patch-deployment-id
REST
In the API, create a GET
request to the
patchDeployments.get
method.
GET https://osconfig.googleapis.com/v1/projects/project-id/patchDeployments/patch-deployment-id
Replace the following:
project-id
: Your project ID.patch-deployment-id
: Your patch deployment name.
Delete a patch deployment
console
- In the Google Cloud console, go to the Compute Engine > VM Manager > Patch page.
- Select the Scheduled deployments tab.
- Click the name of the deployment that you want to delete.
- Click Delete this schedule.
gcloud
Use the
os-config patch-deployments delete
command to delete a patch deployment. Replace
patch-deployment-id
with the name for your
patch deployment.
gcloud compute os-config patch-deployments delete patch-deployment-id
REST
In the API, create a DELETE
request to the
patchDeployments.delete
method.
DELETE https://osconfig.googleapis.com/v1/projects/project-id/patchDeployments/patch-deployment-id
Replace the following:
project-id
: Your project ID.patch-deployment-id
: Your patch deployment name.
What's next?
- Learn more about Patch.
- Create a patch job.
- Manage your patch jobs.