Use OS policies to maintain consistent software configurations across Linux and Windows virtual machine (VM) instances.
Before you begin
- Review OS policy and OS policy assignment.
- 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.
Terraform
To use the Terraform samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment.
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.
-
Supported operating systems
For a full list of operating systems and versions that support OS policies, see Operating system details.
Permissions
Because you can use OS policies to install and manage software packages on a VM, the creation and management of OS policies is equivalent to granting remote code execution access on a VM. When you set up OS policies, IAM permissions are used to control access to the policy resources and activities are audit logged.
Owners of a project have full access to create and manage OS policy assignments. For all other users, you need to grant permissions. You can grant one of the following granular roles:
- OSPolicyAssignment Admin (
roles/osconfig.osPolicyAssignmentAdmin
). Contains permissions to create, delete, update, get and list OS policy assignments. - OSPolicyAssignment Editor (
roles/osconfig.osPolicyAssignmentEditor
). Contains permissions to update, get, and list OS policy assignments. - OSPolicyAssignment Viewer (
roles/osconfig.osPolicyAssignmentViewer
). Contains permissions for read-only access to get and list OS policy assignments.
Example command to set permissions
To grant admin access to a user for OS policy assignments, run the following command:
gcloud projects add-iam-policy-binding PROJECT_ID \ --member user:USER_ID@gmail.com \ --role roles/osconfig.osPolicyAssignmentAdmin
Replace the following:
PROJECT_ID
: the project IDUSER_ID
: the user's Google Workspace username
Create an OS policy assignment
To create and roll out an OS policy assignment, complete the following steps:
- Set up VM Manager.
- Assign the required permissions to users.
- Review OS policy and OS policy assignment.
- Create the OS policy resources.
To create and roll out the OS policy assignment, use one of the following methods:
Console
To create and roll out an OS policy assignment, complete the following steps:
- On your local client, create or download an OS policy. This must be a JSON or YAML file. For more information about creating OS policies or to view sample OS policies, see OS policies.
In the Google Cloud console, go to the OS policies page.
Click Create OS policy assignment.
In the Assignment ID section, provide a name for the OS policy assignment. See Resource naming convention.
In the OS policies section, upload the OS policy file.
In the Target VM instances section, specify the target VMs.
- Select the zone that contains the VMs that you want to apply the policy to.
- Select the OS families.
- Optional: You can further filter the VMs by specifying include, and exclude labels.
For example, you can select all the Ubuntu VMs in your test environment, and exclude those that are running Google Kubernetes Engine, by specifying the following:
- OS family:
ubuntu
- Include:
env:test
,env:staging
- Exclude:
goog-gke-node
Specify a rollout plan.
- Specify the wave size (also referred to as the disruption budget). For example, 10%.
- Specify the wait time. For example, 15 minutes.
Click Start rollout.
gcloud
To create and roll out an OS policy assignment in a zone, complete the following steps:
Create an OS policy assignment resource in the JSON or YAML format. This file defines the OS policies that you want to apply to your VMs, the target VMs that you want to apply the policies to, and the rollout rate at which to apply the OS policies. For more information about this file and sample assignments, see OS policy assignment.
Use the
os-config os-policy-assignments create
command to create and roll out the OS policy assignment in a specified location.gcloud compute os-config os-policy-assignments create OS_POLICY_ASSIGNMENT_ID \ --location=ZONE \ --file=OS_POLICY_ASSIGNMENT_FILE \ --async
Replace the following:
OS_POLICY_ASSIGNMENT_ID
: name for the OS policy assignment. See Resource naming convention.ZONE
: zone to create the OS policy assignment in.OS_POLICY_ASSIGNMENT_FILE
: the absolute path to the OS policy assignment file that you created in the previous step.
Example
gcloud compute os-config os-policy-assignments create my-os-policy-assignment \ --location=asia-south1-a \ --file=/downloads/assignment-config.yaml \ --async
The output is similar to the following:
Create request issued for: [my-os-policy-assignment] Check operation [projects/384123488288/locations/asia-south1-a/osPolicyAssignments/my-os-policy-assignment/operations/fb2011d6-61de-46f1-afdb-bc96bdb3fbaa] for status.
Make note of the fully qualified resource name for the operation. In the previous example the fully qualified resource name is:
projects/384123488288/locations/asia-south1-a/osPolicyAssignments/my-os-policy-assignment/operations/fb2011d6-61de-46f1-afdb-bc96bdb3fbaa
You can use this fully qualified resource name to get details for a rollout, or to cancel a rollout. See Rollouts.
Terraform
To create an OS policy assignment, use the
google_os_config_os_policy_assignment
resource.The following example verifies if the Apache web server is running on CentOS VMs.
To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.
REST
To create an OS policy assignment on your local client, complete the following steps:
Create an OS policy assignment. This must be a JSON file. For more information about creating OS policy assignments or to view sample OS policy assignments, see OS policy assignment.
If you want to use the sample YAML OS policy assignment, you must convert it to JSON.
In the API, create a
POST
request to theprojects.locations.osPolicyAssignments.create
method.In the request body, paste the OS policy assignment specifications from the previous step.
POST https://osconfig.googleapis.com/v1/projects/PROJECT_ID/locations/ZONE/OSPolicyAssignments?osPolicyAssignmentId=OS_POLICY_ASSIGNMENT_ID { JSON_OS_POLICY }
Replace the following:
PROJECT_ID
: your project IDOS_POLICY_ASSIGNMENT_ID
: name for the OS policy assignmentJSON_OS_POLICY
: the OS policy assignment specifications created in the previous step. This must be in JSON format. For more information about the parameters and format, seeResource: OSPolicyAssignment
.ZONE
: zone to create the OS policy assignment in
Example
For example, to create an OS policy assignment for Google Cloud Observability that installs monitoring and logging agents on selected VMs by using the Sample OS policy assignment, complete the following steps:
- Convert the sample to JSON
- Make the following request:
POST https://osconfig.googleapis.com/v1/projects/PROJECT_ID/locations/ZONE/OSPolicyAssignments?osPolicyAssignmentId=OS_POLICY_ASSIGNMENT_ID { "osPolicies": [ { "id": "setup-repo-and-install-package-policy", "mode": "ENFORCEMENT", "resourceGroups": [ { "resources": [ { "id": "setup-repo", "repository": { "yum": { "id": "google-cloud-monitoring", "displayName": "Google Cloud Monitoring Agent Repository", "baseUrl": "https://packages.cloud.google.com/yum/repos/google-cloud-monitoring-el8-x86_64-all", "gpgKeys": [ "https://packages.cloud.google.com/yum/doc/yum-key.gpg", "https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg" ] } } }, { "id": "install-pkg", "pkg": { "desiredState": "INSTALLED", "yum": { "name": "stackdriver-agent" } } } ] } ] } ], "instanceFilter": { "inclusionLabels": [ { "labels": { "used_for": "testing" } } ] }, "rollout": { "disruptionBudget": { "fixed": 10 }, "minWaitDuration": { "seconds": 300 } } }
Rollouts
OS policy assignments are deployed according to a rollout rate. This means that assignments that target a set of VMs can be deployed gradually and aren't applied to all the VMs immediately. Changes are rolled out gradually to give you an opportunity to intervene and cancel a rollout if new changes cause regressions.
When method calls to an API might take a long time to complete, the API returns a long-running operations (LRO). For more information about LROs, see Long-running operations.
The OS Config API creates an LRO every time you create, update, or delete an OS policy assignment. Each LRO returns an operation resource. This operation resource is similar to the following:
Create request issued for: [my-os-policy-assignment] Check operation [projects/384123488288/locations/asia-south1-a/osPolicyAssignments/my-os-policy-assignment/operations/fb2011d6-61de-46f1-afdb-bc96bdb3fbaa] for status.
Each create, update, or delete operation also generates a new OS policy assignment revision. To view the revisions for an OS policy assignment, see List OS policy assignment revisions.
You can use the Google Cloud CLI to get the details of a rollout, or to cancel a rollout.
Get details for a rollout
To get details for a rollout, use the
os-config os-policy-assignments operations describe
command.
gcloud compute os-config os-policy-assignments operations describe FULLY_QUALIFIED_OPERATION_NAME
Replace FULLY_QUALIFIED_OPERATION_NAME
with the fully
qualified resource name for the operation that is returned from the create,
update, or delete operation.
Example
gcloud compute os-config os-policy-assignments operations describe \ projects/384123488288/locations/asia-south1-a/osPolicyAssignments/my-os-policy-assignment/operations/fb2011d6-61de-46f1-afdb-bc96bdb3fbaa
Example output
done: true metadata: '@type': type.googleapis.com/google.cloud.osconfig.$$api-version$$.OSPolicyAssignmentOperationMetadata apiMethod: CREATE osPolicyAssignment: projects/3841234882888/locations/asia-south1-a/osPolicyAssignments/my-os-policy-assignment@cfb78790-41d8-40d1-b8a1-1eaf6011b909 rolloutStartTime: '2021-04-15T00:53:52.963569Z' rolloutState: SUCCEEDED rolloutUpdateTime: '2021-04-15T00:53:53.094041Z' name: projects/3841234882888/locations/asia-south1-a/osPolicyAssignments/my-os-policy-assignment/operations/cfb78790-41d8-40d1-b8a1-1eaf6011b909 response: '@type': type.googleapis.com/google.cloud.osconfig.$$api-version$$.OSPolicyAssignment baseline: true description: My test policy instanceFilter: inclusionLabels: - labels: label-key-not-targeting-instances: label-value-not-targeting-instances name: projects/3841234882888/locations/asia-south1-a/osPolicyAssignments/my-os-policy-assignment osPolicies: - id: q-test-policy mode: ENFORCEMENT resourceGroups: - osFilter: osShortName: centos osVersion: '7' resources: - id: add-repo repository: yum: baseUrl: https://packages.cloud.google.com/yum/repos/google-cloud-ops-agent-el7-x86_64-all
Cancel a rollout
Console
In the Google Cloud console, go to the OS policies page.
Click the OS policy assignments tab.
For the OS policy assignment that you want to cancel the rollout, click Action (> Cancel rollout.
)Click Cancel rollout.
gcloud
To cancel a rollout, use the
gcloud compute os-config os-policy-assignments operations cancel
command.
gcloud compute os-config os-policy-assignments operations cancel FULLY_QUALIFIED_OPERATION_NAME
Replace FULLY_QUALIFIED_OPERATION_NAME
with the fully
qualified resource name for the operation that is returned from the create,
update, or delete operation.
Example
gcloud compute os-config os-policy-assignments operations cancel \ projects/384123488288/locations/asia-south1-a/osPolicyAssignments/my-os-policy-assignment/operations/fb2011d6-61de-46f1-afdb-bc96bdb3fbaa
If the command is successful, no output is returned.
What's next?
- Learn more about the OS policies.
- Manage OS policy assignments.