Creating an OS policy assignment

Use OS policies to maintain consistent software configurations across Linux and Windows virtual machine (VM) instances.

Before you begin

Supported operating systems

For a full list of operating systems and versions that support OS configuration management (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. However, users can still run code on the VM which poses a potential security risk. To mitigate this risk, we recommend that you provide only the required access to each user.

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.osPolicyAssignmentsAdmin). Contains permissions to create, delete, update, get, and list OS policies.
  • OSPolicyAssignment Editor (roles/osconfig.osPolicyAssignmentsEditor). Contains permissions to get, update, and list OS policies.
  • OSPolicyAssignment Viewer (roles/osconfig.osPolicyAssignmentsViewer). Contains permissions for read-only access to get and list OS policies.

For example, 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.osPolicyAssignmentsAdmin

Replace the following:

  • PROJECT_ID: the project ID.
  • USER_ID: the user's Google Workspace username.

Create an OS policy assignment

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

  1. Set up VM Manager.
  2. Assign the required permissions to users.
  3. Review OS policy and OS policy assignment.
  4. Create the OS policy assignment. To create the OS policy assignment, use either Google Cloud Console, the gcloud command-line tool, or the Cloud OS Config API.

    Console

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

    1. 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.
    2. In the Google Cloud Console, go to the OS configuration management page.

      Go to OS configuration management

    3. Click Create policy assignment.

    4. In the Assignment ID section, provide a name for the OS policy assignment. See Resource naming convention.

    5. In the OS policies section, upload the OS policy file.

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

      Select target VMs.

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

        Rollout configuration.

    8. Click Start rollout.

    gcloud

    To create an OS policy assignment on your local client, complete the following steps:

    1. Create an OS policy assignment. This must be a JSON or YAML file. For more information about creating OS policy assignments or to view sample OS policy assignments, see OS policy assignment.

    2. Use the os-config os-policy-assignments create command to create the OS policy assignment.

      gcloud alpha 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 file that contains the OS policy assignment file on your local client.

      Example

      gcloud alpha 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.
      
    3. 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.

    API

    To create an OS policy assignment on your local client, complete the following steps:

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

    2. In the API, create a POST request to the projects.locations.osPolicyAssignments.create method.

      In the request body, paste the OS policy assignment specifications from the previous step.

      POST https://osconfig.googleapis.com/v1alpha/projects/PROJECT_ID/locations/ZONE/OSPolicyAssignments?osPolicyAssignmentId=OS_POLICY_ASSIGNMENT_ID
      
      {
       JSON_OS_POLICY
      }
      

      Replace the following:

      • PROJECT_ID: your project ID
      • OS_POLICY_ASSIGNMENT_ID: name for the OS policy assignment
      • JSON_OS_POLICY: the OS policy assignment specifications created in the previous step. This must be in JSON format.
      • ZONE: zone to create the OS policy assignment in

      Example

      For example, to create an OS policy assignment for Google Cloud's operations suite that installs monitoring and logging agents on selected VMs by using the Sample OS policy assignment, complete the following steps:

      1. Convert the sample to JSON
      2. Make the following request:
      POST https://osconfig.googleapis.com/v1alpha/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 service 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 version or revision ID. To view the revisions for an OS policy assignment, see List OS policy assignment revisions.

You can use the gcloud command-line tool 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 alpha 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 alpha 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

To cancel a rollout, use the gcloud alpha compute os-config os-policy-assignments operations cancel command.

gcloud alpha 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 alpha 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?