Manage OS policy assignments

After you create an OS policy assignment, review and manage your assignments using the following procedures:

Update OS policy assignments: modify the configurations for your OS policy assignment
Describe OS policy assignments: get details about a specific OS policy assignment
List OS policy assignments: view a list of OS policy assignments in a specific zone
List OS policy assignment revisions: view a list of revisions that are available for a specific OS policy assignment
Delete an OS policy assignment: delete a specific OS policy assignment
Debug an OS policy assignment: troubleshoot an OS policy assignment

You can manage your OS policy assignments using either the Google Cloud console, the Google Cloud CLI, or the OS Config API.

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 manage OS policy assignments. For all other users, you need to grant permissions. To manage OS policy assignments, 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 a user admin access to 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 ID
USER_ID: the user's Google Workspace username

Update OS policy assignments

To update an OS policy assignment, complete the following steps:

Update the YAML or JSON file that has the OS policy assignment.

The update request supports field masks. You might need to update only certain fields in the OS policy assignment while leaving the other fields unchanged. The update or patch command uses field masks to tell the API which fields are changed. The update or patch request ignores any fields that aren't specified in the field mask, leaving them with their current values. For more information about field masks, see FieldMask.
Update the OS policy assignment using either the Google Cloud console, Google Cloud CLI, or the OS Config API.

When you update an OS policy assignment, a rollout is created. You can view the progress of the update by monitoring the rollout. For more information, see Getting details for a rollout.
Console
1. In the Google Cloud console, go to the OS policies > Assignments page.
  
  Go to Google Cloud console
2. For the OS policy assignment that you want to edit, click Action () > Edit Assignment.
3. Make the needed updates. For example, you can upload the updated OS policy file.
4. Click Start rollout.
gcloud
Use the os-config os-policy-assignments update command to update an OS policy assignment.
```
gcloud compute os-config os-policy-assignments update OS_POLICY_ASSIGNMENT_ID \
    --location=ZONE \
    --file=FILE
```
Replace the following:
- OS_POLICY_ASSIGNMENT_ID: the name of the OS policy assignment that you want to update
- ZONE: the zone where the OS policy assignment is located
- FILE: the absolute path to the JSON or YAML file that contains the updated OS policy assignment specifications
  
  If the OS policy assignment doesn't exist, and if you specify the --allow-missing flag, VM Manager creates the OS policy assignment with the specified ID and specifications.
REST
In the API, create a PATCH request to the projects.locations.osPolicyAssignments.patch method.
```
PATCH https://osconfig.googleapis.com/v1/projects/PROJECT_ID/locations/ZONE/OSPolicyAssignments/OS_POLICY_ASSIGNMENT_ID

{
 JSON_OS_POLICY
}
```
Replace the following:
- PROJECT_ID: your project ID
- OS_POLICY_ASSIGNMENT_ID: name of the OS policy assignment that you want to update
- JSON_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, see Resource: OSPolicyAssignment.
- ZONE: the zone where the OS policy assignment is located

List OS policy assignments

Console

In the Google Cloud console, go to the OS policies > Assignments page.

Go to Google Cloud console

gcloud

To view a list of OS policy assignments in a specific zone, use the os-config os-policy-assignments list command.

 gcloud compute os-config os-policy-assignments list \
     --location=ZONE

Replace ZONE with the zone where the OS policy assignments are located.

REST

In the API, create a GET request to the projects.locations.osPolicyAssignments.list method.

GET https://osconfig.googleapis.com/v1/projects/PROJECT_ID/locations/ZONE/OSPolicyAssignments

Replace the following:

PROJECT_ID: your project ID
ZONE: the zone where the OS policy assignments are located

Describe an OS policy assignment

Console

In the Google Cloud console, go to the OS policies > Assignments page.

Go to Google Cloud console
Click the name of the assignment that you want to view details for.

gcloud

To view details about an OS policy assignment, use the compute os-config os-policy-assignments describe command.

gcloud compute os-config os-policy-assignments describe OS_POLICY_ASSIGNMENT_ID \
     --location=ZONE

Replace the following:

OS_POLICY_ASSIGNMENT_ID: the name of the OS policy assignment that you want to view
ZONE: the zone where the OS policy assignment is located

REST

In the API, create a GET request to the projects.locations.osPolicyAssignments.get method.

GET https://osconfig.googleapis.com/v1/projects/PROJECT_ID/locations/ZONE/OSPolicyAssignments/OS_POLICY_ASSIGNMENT_ID

Replace the following:

PROJECT_ID: your project ID
OS_POLICY_ASSIGNMENT_ID: name of the OS policy assignment that you want to view
ZONE: the zone where the OS policy assignment is located

List OS policy assignment revisions

gcloud

A revision ID is generated when you create an OS policy assignment. A new revision ID is also generated each time you update or delete the OS policy assignment.

To view a list of revisions that are available for an OS policy assignment, use the os-config os-policy-assignments list-revisions command.

gcloud compute os-config os-policy-assignments list-revisions OS_POLICY_ASSIGNMENT_ID \
    --location=ZONE

Replace the following:

OS_POLICY_ASSIGNMENT_ID: the name of the OS policy assignment whose revisions you want to view
ZONE: the zone where the OS policy assignment is located

REST

In the API, create a GET request to the projects.locations.osPolicyAssignments.listRevisions method.

GET https://osconfig.googleapis.com/v1/projects/PROJECT_ID/locations/ZONE/OSPolicyAssignments/OS_POLICY_ASSIGNMENT_ID:listRevisions

Replace the following:

PROJECT_ID: your project ID
OS_POLICY_ASSIGNMENT_ID: the name of the OS policy assignment whose revisions you want to view
ZONE: the zone where the OS policy assignment is located

Delete OS policy assignments

When you delete an OS policy assignment, a rollout is created. You can view the progress of the deletion by monitoring the rollout. For more information, see Getting details for a rollout.

Console

In the Google Cloud console, go to the OS policies > Assignments page.

Go to Google Cloud console
For the OS policy assignment that you want to delete, click Action () > Delete Assignment.
Click Delete.

gcloud

To delete an OS policy assignment, use the os-config os-policy-assignments delete command.

gcloud compute os-config os-policy-assignments delete OS_POLICY_ASSIGNMENT_ID \
    --location=ZONE

Replace the following:

OS_POLICY_ASSIGNMENT_ID: the name of the OS policy assignment that you want to delete
ZONE: the zone where the OS policy assignment is located

REST

In the API, create a DELETE request to the projects.locations.osPolicyAssignments.delete method.

DELETE https://osconfig.googleapis.com/v1/projects/PROJECT_ID/locations/ZONE/OSPolicyAssignments/OS_POLICY_ASSIGNMENT_ID

Replace the following:

PROJECT_ID: your project ID
OS_POLICY_ASSIGNMENT_ID: name of the OS policy assignment that you want to delete
ZONE: the zone where the OS policy assignment is located

Troubleshooting

To troubleshoot an OS policy assignment, see Troubleshooting VM Manager.

What's next?

Learn more about the OS policies.
Create an OS policy assignment.