Manage OS policy assignments using policy orchestrator

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

This page describes how to use the policy orchestrator feature in VM Manager to create, update, or delete OS policy resources across different projects and zones in your folders or organization.

Before you begin

• Review OS policy and OS policy assignment.
• Review OS Config quotas.
• Ensure that you meet the prerequisites for using policy orchestrator.
• 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.

  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.

Create or update OS policy assignments across projects and zones

You can create policy orchestrators to apply OS policies to selected resources in a project, folder, or organization.

Console

Note: In Preview, you can only create folder-level orchestrators using the Google Cloud console.

To create a policy orchestrator and to apply OS policy assignments in a folder, do the following:

1. On your local client, create or download an OS policy file. This file 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 policies page.

   Go to OS policies

3. Click the Project Selector on the Google Cloud console action bar and select the folder in which you want to create the policy orchestrator.

4. Click Create Policy Orchestrator.

5. Specify a name and description for the policy orchestrator. See Resource naming convention. VM Manager assigns a unique orchestrator ID to the policy orchestrator. You can edit this ID if required.

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

7. Optional: In the State section, select one of the following options to specify the behavior of the policy orchestrator:

   • ACTIVE: Once created, the policy orchestrator takes actions immediately.
   • STOPPED: A policy orchestrator is created in this state does not take any actions immediately. You can edit the policy orchestrator later to change its state.

8. In the Action field, select the UPSERT action.

9. In the Orchestration scope section, specify the folders and projects in which you want to roll out the OS policies. You must enter only the project numbers and folder numbers in these fields, for example, 123456,7654321.

10. Select the zones that contain the VMs that you want to apply the OS policies to. Alternatively, click Select all to apply the OS policy changes to resources in all zones.

11. Optional: In the Target VM instances section, specify the target VMs that you want to apply the OS policies to.

    • Select the OS families.

    • 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

12. Specify a rollout plan for the OS policy assignment.

    • Specify the wave size (also referred to as the disruption budget). For example, 10%.
    • Specify the wait time. For example, 15 minutes.

13. Click Create.

gcloud

To create a policy orchestrator, complete the following steps:

1. Create or download an OS policy assignment resource in the JSON or YAML format. For more information about this file and sample policy assignments, see OS policy assignments.

2. Use the beta os-config policy-orchestrators create command to create and roll out the OS policy assignment in the specified scope.

Project

  gcloud beta compute os-config policy-orchestrators create ORCHESTRATOR_NAME \
    --policy-type=os_policy_assignment_v1 \
    --policy-file=OS_POLICY_ASSIGNMENT_YAML_FILE \
    --policy-id=POLICY_ID \

Replace the following:

• ORCHESTRATOR_NAME: name for the policy orchestrator. See Resource naming convention.
• OS_POLICY_ASSIGNMENT_FILE: the absolute path to the OS policy assignment file that you created in the previous step.
• POLICY_ID: a unique ID for the policy orchestrator. If you don't specify a value, policy orchestrator assigns a unique ID for the orchestrator resource.

Example

  gcloud beta compute os-config policy-orchestrators create my-os-policy-orchestrator \
      --policy-type=os_policy_assignment_v1 \
      --policy-file=/downloads/assignment-config.yaml \
      --policy-id=policy-123 \

Folder

  gcloud --billing-project=QUOTA_PROJECT_ID beta compute os-config policy-orchestrators create ORCHESTRATOR_NAME \
    --folder=FOLDER_NUMBER \
    --policy-type=os_policy_assignment_v1 \
    --policy-file=OS_POLICY_ASSIGNMENT_YAML_FILE \
    --policy-id=POLICY_ID \
    --include-projects=PROJECT_NUMBERS

Replace the following:

• QUOTA_PROJECT_ID: the project ID of the quota or the billing project.
• ORCHESTRATOR_NAME: name for the policy orchestrator. See Resource naming convention.
• FOLDER_NUMBER: the folder number of the folder in which you want to create the policy orchestrator.
• OS_POLICY_ASSIGNMENT_FILE: the absolute path to the OS policy assignment file that you created in the previous step.
• POLICY_ID: a unique ID for the policy orchestrator. If you don't specify a value, policy orchestrator assigns a unique ID for the orchestrator resource.
• PROJECT_NUMBERS: a list of projects for which you want to apply the OS policy assignments. You must specify the project numbers, the unique numeric ID of the projects.

Example

  gcloud --billing-project=my-quota-project beta compute os-config policy-orchestrators create my-os-policy-orchestrator \
      --folder=123456 \
      --policy-type=os_policy_assignment_v1 \
      --policy-file=/downloads/assignment-config.yaml \
      --policy-id=policy-123 \
      --include-projects=87654321,4567890

Organization

  gcloud --billing-project=QUOTA_PROJECT_ID beta compute os-config policy-orchestrators create ORCHESTRATOR_NAME \
    --organization=ORGANIZATION_NUMBER \
    --policy-type=os_policy_assignment_v1 \
    --policy-file=OS_POLICY_ASSIGNMENT_YAML_FILE \
    --policy-id=POLICY_ID \
    --include-projects=PROJECT_NUMBERS

Replace the following:

• QUOTA_PROJECT_ID: the project ID of the quota or the billing project.
• ORCHESTRATOR_NAME: name for the policy orchestrator. See Resource naming convention.
• FOLDER_NUMBER: the folder number of the folder in which you want to create the policy orchestrator.
• OS_POLICY_ASSIGNMENT_FILE: the absolute path to the OS policy assignment file that you created in the previous step.
• POLICY_ID: a unique ID for the policy orchestrator. If you don't specify a value, policy orchestrator assigns a unique ID for the orchestrator resource.
• PROJECT_NUMBERS: a list of projects for which you want to apply the OS policy assignments. You must specify the project numbers, the unique numeric ID of the projects.

Example

  gcloud --billing-project=my-quota-project beta compute os-config policy-orchestrators create my-os-policy-orchestrator \
      --organization=123456 \
      --policy-type=os_policy_assignment_v1 \
      --policy-file=/downloads/assignment-config.yaml \
      --policy-id=policy-123 \
      --include-projects=87654321,4567890

REST

To create a policy orchestrator, complete the following steps:

1. Create or download an OS policy assignment file. 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.

2. Depending on the scope at which you are creating the policy orchestrator, use one of the following methods:

Project

Send a POST request to projects.locations.global.policyOrchestrators.create method.

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

POST https://osconfig.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/policyOrchestrators

  {
      JSON_OS_POLICY_ORCHESTRATOR
  }

Replace the following:

• PROJECT_NUMBER: the numeric ID of the project in which you want to create the policy orchestrator.
• JSON_OS_POLICY_ORCHESTRATOR: the policy orchestrator object in JSON format that defines the orchestrator scope, orchestrated resource, and orchestration state. For more information about the parameters and format, see Resource: folders.locations.global.policyOrchestrators.

Example

For example, to create an OS policy assignment that installs a Windows MSI downloaded from a Cloud Storage bucket 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/v2beta/projects/123456/locations/global/policyOrchestrators
   
   {
   "action": "UPSERT",
   "orchestratedResource": {
     "osPolicyAssignmentV1Payload": {
       "instanceFilter": {
         "inventories": [
           {
             "osShortName": "windows"
           }
         ]
       },
       "osPolicies": [
       {
         "id": "install-msi-policy",
         "mode": "ENFORCEMENT",
         "resourceGroups": [
           {
             "resources": [
               {
                 "id": "install-msi",
                 "pkg": {
                   "desiredState": "INSTALLED",
                   "msi": {
                     "source": {
                       "gcs": {
                         "bucket": "my-bucket",
                         "generation": "1619136883923956",
                         "object": "my-app.msi"
                       }
                     }
                   }
                 }
               }
             ]
           }
         ]
       }
       ],
       "rollout": {
         "disruptionBudget": {
           "fixed": 10
         },
         "minWaitDuration": "300s"
       }
     }
   },
   "orchestrationScope": {
   "selectors": [
     {
        "resourceHierarchySelector": {
           "includedProjects": [
           "projects/87654321",
           "projects/4567890"
           ]
         }
       }
     ]
   },
   "state": "ACTIVE"
   }
   

Folder

Send a POST request to the folders.locations.global.policyOrchestrators.create method.

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

POST https://osconfig.googleapis.com/v2beta/folders/FOLDER_NUMBER/locations/global/policyOrchestrators
-H "x-goog-user-project: QUOTA_PROJECT_ID"

{
  JSON_OS_POLICY_ORCHESTRATOR
}

Replace the following:

• QUOTA_PROJECT_ID: the project ID of the quota or the billing project.
• FOLDER_NUMBER: the numeric ID of the folder in which you want to create the policy orchestrator.
• JSON_OS_POLICY_ORCHESTRATOR: the policy orchestrator object in JSON format that defines the orchestrator scope, orchestrated resource, and orchestration state. For more information about the parameters and format, see Resource: folders.locations.global.policyOrchestrators.

Example

For example, to create an OS policy assignment that installs a Windows MSI downloaded from a Cloud Storage bucket 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/v2beta/folders/123456/locations/global/policyOrchestrators \
   -H "x-goog-user-project: my-quota-project
   
   {
   "action": "UPSERT",
   "orchestratedResource": {
     "osPolicyAssignmentV1Payload": {
       "instanceFilter": {
         "inventories": [
           {
             "osShortName": "windows"
           }
         ]
       },
       "osPolicies": [
       {
         "id": "install-msi-policy",
         "mode": "ENFORCEMENT",
         "resourceGroups": [
           {
             "resources": [
               {
                 "id": "install-msi",
                 "pkg": {
                   "desiredState": "INSTALLED",
                   "msi": {
                     "source": {
                       "gcs": {
                         "bucket": "my-bucket",
                         "generation": "1619136883923956",
                         "object": "my-app.msi"
                       }
                     }
                   }
                 }
               }
             ]
           }
         ]
       }
       ],
       "rollout": {
         "disruptionBudget": {
           "fixed": 10
         },
         "minWaitDuration": "300s"
       }
     }
   },
   "orchestrationScope": {
   "selectors": [
     {
        "resourceHierarchySelector": {
           "includedProjects": [
           "projects/87654321",
           "projects/4567890"
           ]
         }
       }
     ]
   },
   "state": "ACTIVE"
   }
   

Organization

Send a POST request to the organizations.locations.global.policyOrchestrators.create method.

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

POST https://osconfig.googleapis.com/v2beta/organizations/ORGANIZATION_NUMBER/locations/global/policyOrchestrators \
-H "x-goog-user-project: QUOTA_PROJECT_ID"

  {
      JSON_OS_POLICY_ORCHESTRATOR
  }

Replace the following:

• QUOTA_PROJECT_ID: the project ID of the quota or the billing project.
• ORGANIZATION_NUMBER: the numeric ID of the organization in which you want to create the policy orchestrator.
• JSON_OS_POLICY_ORCHESTRATOR: the policy orchestrator object in JSON format that defines the orchestrator scope, orchestrated resource, and orchestration state. For more information about the parameters and format, see Resource: organizations.locations.global.policyOrchestrators.

Example

For example, to create an OS policy assignment that installs a Windows MSI downloaded from a Cloud Storage bucket 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/v2beta/organizations/567890/locations/global/policyOrchestrators \
   -H "x-goog-user-project: my-quota-project
   {
   "action": "UPSERT",
   "orchestratedResource": {
     "osPolicyAssignmentV1Payload": {
       "instanceFilter": {
         "inventories": [
           {
             "osShortName": "windows"
           }
         ]
       },
       "osPolicies": [
       {
         "id": "install-msi-policy",
         "mode": "ENFORCEMENT",
         "resourceGroups": [
           {
             "resources": [
               {
                 "id": "install-msi",
                 "pkg": {
                   "desiredState": "INSTALLED",
                   "msi": {
                     "source": {
                       "gcs": {
                         "bucket": "my-bucket",
                         "generation": "1619136883923956",
                         "object": "my-app.msi"
                       }
                     }
                   }
                 }
               }
             ]
           }
         ]
       }
       ],
       "rollout": {
         "disruptionBudget": {
           "fixed": 10
         },
         "minWaitDuration": "300s"
       }
     }
   },
   "orchestrationScope": {
   "selectors": [
     {
        "resourceHierarchySelector": {
           "includedProjects": [
           "projects/87654321",
           "projects/4567890"
           ]
         }
       }
     ]
   },
   "state": "ACTIVE"
   }
   

Delete OS policy assignments from multiple projects

You can use policy orchestrator to delete OS policies from multiple projects in your folder or organization by specifying the unique policy ID for the OS policy resource.

Console

Note: In Preview, you can only create folder-level orchestrators using the Google Cloud console.

To delete OS policies in a folder, do the following:

1. On your local client, create or download an OS policy file. This file 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 policies page.

   Go to OS policies

3. Click the Project Selector on the Google Cloud console action bar and select the folder in which you want to create the policy orchestrator.

4. Click Create Policy Orchestrator.

5. Specify a name and description for the policy orchestrator. See Resource naming convention. VM Manager assigns a unique orchestrator ID to the policy orchestrator. You can edit this ID if required.

6. In the OS policies section, select and upload the OS policy file.

7. Optional: In the State section, select one of the following options to specify the behavior of the policy orchestrator:

   • ACTIVE: Once created, the policy orchestrator takes actions immediately.
   • STOPPED: A policy orchestrator is created in this state does not take any actions immediately. You can edit the policy orchestrator later to change its state.

8. In the Action field, select the DELETE action.

9. In the Orchestration scope section, specify the folders and projects in which you want to roll out the OS policies. You must enter only the project numbers and folder numbers in these fields, for example, 123456,7654321.

10. Select the zones that contain the VMs that you want to apply the OS policies to.

11. Optional: In the Target VM instances section, specify the target VMs that you want to apply the OS policies to.

    • Select the OS families.

    • 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

12. Specify a rollout plan for the OS policy assignment.

    • Specify the wave size (also referred to as the disruption budget). For example, 10%.
    • Specify the wait time. For example, 15 minutes.

13. Click Create.

gcloud

To delete OS policies from multiple projects using a policy orchestrator, use the beta os-config policy-orchestrators create command and specify the action as delete for the policy-id associated with the OS policy assignment.

Project

  gcloud beta compute os-config policy-orchestrators create ORCHESTRATOR_NAME \
    --policy-type=os_policy_assignment_v1 \
    --policy-file=OS_POLICY_ASSIGNMENT_YAML_FILE \
    --policy-id=POLICY_ID \
    --action=delete

Replace the following:

• FOLDER_NUMBER: the numeric ID of the folder from which you want to delete the OS policy resources.
• POLICY_ID: the policy ID for the OS policy orchestrator resource.

Example

 gcloud beta compute os-config policy-orchestrators create my-os-policy-orchestrator \
   --policy-type=os_policy_assignment_v1
   --policy-id=my-policy \
   --action=delete

Folder

  gcloud --billing-project=QUOTA_PROJECT_ID beta compute os-config policy-orchestrators create ORCHESTRATOR_NAME \
    --policy-type=os_policy_assignment_v1 \
    --policy-id=POLICY_ID \
    --action=delete

Replace the following:

• QUOTA_PROJECT_ID: the project ID of the quota or the billing project.
• FOLDER_NUMBER: the numeric ID of the folder from which you want to delete the OS policy resources.
• POLICY_ID: the policy ID for the OS policy orchestrator resource.

Example

gcloud --billing-project=my-quota-project beta compute os-config policy-orchestrators create my-os-policy-orchestrator \
  --folder=123456 \
  --policy-type=os_policy_assignment_v1 \
  --policy-id=my-policy \
  --action=delete

Organization

    gcloud --billing-project=QUOTA_PROJECT_ID beta compute os-config policy-orchestrators create ORCHESTRATOR_NAME \
      --organization=ORGANIZATION_NUMBER \
      --policy-type=os_policy_assignment_v1 \
      --policy-id=POLICY_ID \
      --action=delete

Replace the following:

• QUOTA_PROJECT_ID: the project ID of the quota or the billing project.
• ORGANIZATION_NUMBER: the numeric ID of the organization from which you want to delete the OS policy resources.
• POLICY_ID: the policy ID for the OS policy orchestrator resource.

Example

    gcloud --billing-project=my-quota-project beta compute os-config policy-orchestrators create my-os-policy-orchestrator \
      --organization=987654321
      --policy-type=os_policy_assignment_v1
      --policy-id=my-policy \
      --action=delete

REST

To create a policy orchestrator that deletes OS policies from multiple projects, use one of the following methods and specify the action as DELETE:

Project

Send a POST request to projects.locations.global.policyOrchestrators.create method.

In the request body, specify the policy ID associated with the OS policy assignment.

POST https://osconfig.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/policyOrchestrators

  {
      JSON_OS_POLICY_ORCHESTRATOR
  }

Replace the following:

• PROJECT_NUMBER: the numeric ID of the project in which you want to create the policy orchestrator.
• JSON_OS_POLICY_ORCHESTRATOR: the policy orchestrator object in JSON format that defines the orchestrator scope, orchestrated resource, and orchestration state. For more information about the parameters and format, see Resource: folders.locations.global.policyOrchestrators.

Example

POST https://osconfig.googleapis.com/v2beta/projects/567890/locations/global/policyOrchestrators

{
    "action": "DELETE",
    "orchestratedResource": {
      "id": "my-policy",
      "osPolicyAssignmentV1Payload": {}
    },
    "orchestrationScope": {
      "selectors": [
        {
          "resourceHierarchySelector": {
            "includedProjects": [
              "projects/87654321",
              "projects/4567890"
            ]
          }
        }
      ]
    },
    "state": "ACTIVE"
  }

Folder

Send a POST request to the folders.locations.global.policyOrchestrators.create method.

In the request body, specify the policy ID associated with the OS policy assignment.

POST https://osconfig.googleapis.com/v2beta/folders/FOLDER_NUMBER/locations/global/policyOrchestrators
-H "x-goog-user-project: QUOTA_PROJECT_ID"

{
  JSON_OS_POLICY_ORCHESTRATOR
}

Replace the following:

• QUOTA_PROJECT_ID: the project ID of the quota or the billing project.
• FOLDER_NUMBER: the numeric ID of the folder from which you want to delete the OS policy resources.
• JSON_OS_POLICY_ORCHESTRATOR: the policy orchestrator object in JSON format that defines the policy id, orchestrator scope, orchestrated resource, and orchestration state. For more information about the parameters and format, see Resource: folders.locations.global.policyOrchestrators.

Example

For example, to delete OS policy resources from multiple projects, make the following request:

 POST https://osconfig.googleapis.com/v2beta/folders/567890/locations/global/policyOrchestrators
 -H "x-goog-user-project: my-quota-project

 {
    "action": "DELETE",
    "orchestratedResource": {
      "id": "my-policy",
      "osPolicyAssignmentV1Payload": {}
    },
    "orchestrationScope": {
      "selectors": [
        {
          "resourceHierarchySelector": {
            "includedProjects": [
              "projects/87654321",
              "projects/4567890"
            ]
          }
        }
      ]
    },
    "state": "ACTIVE"
  }

Organization

Send a POST request to the organizations.locations.global.policyOrchestrators.create method.

In the request body, specify the policy ID associated with the OS policy assignment.

POST https://osconfig.googleapis.com/v2beta/organizations/ORGANIZATION_NUMBER/locations/global/policyOrchestrators
-H "x-goog-user-project: QUOTA_PROJECT_ID"

{
  JSON_OS_POLICY_ORCHESTRATOR
}

Replace the following:

• QUOTA_PROJECT_ID: the project ID of the quota or the billing project.
• ORGANIZATION_NUMBER: the numeric ID of the organization from which you want to delete the OS policy resources.
• JSON_OS_POLICY_ORCHESTRATOR: the policy orchestrator object in JSON format that defines the policy id, orchestrator scope, orchestrated resource, and orchestration state. For more information about the parameters and format, see Resource: organizations.locations.global.policyOrchestrators.

Example

For example, to delete OS policy resources from multiple projects, make the following request:

POST https://osconfig.googleapis.com/v2beta/organizations/567890/locations/global/policyOrchestrators
-H "x-goog-user-project: my-quota-project

{
    "action": "DELETE",
    "orchestratedResource": {
      "id": "my-policy",
      "osPolicyAssignmentV1Payload": {}
    },
    "orchestrationScope": {
      "selectors": [
        {
          "resourceHierarchySelector": {
            "includedProjects": [
              "projects/87654321",
              "projects/4567890"
            ]
          }
        }
      ]
    },
    "state": "ACTIVE"
  }

What's next?

• Manage OS policy assignments.
• Troubleshoot VM Manager