View, edit, and delete policy orchestrators

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 view and delete policy orchestrators 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.

List all policy orchestrators in a folder

To view all policy orchestrators in a folder, complete the following steps:

Console

To list policy orchestrators in a folder, do the following:

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

   Go to OS policies

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

3. Click Policy Orchestrators.

gcloud

To view details of a policy orchestrator that was created in a folder, run the beta os-config policy-orchestrators list command:

  gcloud --billing-project=QUOTA_PROJECT_ID beta compute os-config policy-orchestrators list \
    --folder=FOLDER_NUMBER \

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 created the policy orchestrators.

Example

  gcloud beta compute os-config policy-orchestrators list \
    --folder=123456 \

REST

To view all policy orchestrators in a folder, send a GET request to the folders.locations.global.policyOrchestrators.list method:

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

Replace FOLDER_NUMBER with the numeric ID of the folder in which you created the policy orchestrators.

View details of a policy orchestrator

To view details of a policy orchestrator in a folder, complete the following steps:

Console

To view a policy orchestrator, do the following:

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

   Go to OS policies

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

3. Click Policy Orchestrators.

4. Select the name of the policy orchestrator that you want to view. The Orchestrator details page opens.

5. To view details of the OS policies applied to VMs, click OS Policy Template.

gcloud

To view details of a policy orchestrator that was created in a folder, run the beta os-config policy-orchestrators describe command:

gcloud --billing-project=QUOTA_PROJECT_ID beta compute os-config policy-orchestrators describe ORCHESTRATOR_NAME \
  --folder=FOLDER_NUMBER \

Replace the following:

• QUOTA_PROJECT_ID: the project ID of the quota or the billing project.
• ORCHESTRATOR_NAME: name for the policy orchestrator.
• FOLDER_NUMBER: the numeric ID of the folder in which you created the policy orchestrator.

Example

  gcloud --billing-project=my-quota-project beta compute os-config policy-orchestrators describe my-os-policy-orchestrator \
      --folder=123456 \

REST

To view details of a policy orchestrator, send a GET request to the folders.locations.global.policyOrchestrators.get method,

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

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 the policy orchestrator exists.
• ORCHESTRATOR_NAME: the name of the policy orchestrator that you want to delete.

The request body must be empty.

Edit a policy orchestrator

You can modify policy orchestrators to add or update the OS policy assignments, orchestrator scope and resources.

Console

To change the settings of a policy orchestrator, do the following:

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

   Go to OS policies

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

3. Click Policy Orchestrators.

4. Select the name of the policy orchestrator that you want to edit. The Orchestrator details page opens.

5. Click Edit.

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

9. Optional: Select the zones that contain the VMs that you want to apply the OS policies to.

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

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

12. Click Save.

gcloud

To update a policy orchestrator in a folder, complete the following steps:

1. Use the beta os-config policy-orchestrators update command to edit the policy orchestrator in a specified folder.

     gcloud --billing-project=QUOTA_PROJECT_ID beta compute os-config policy-orchestrators update ORCHESTRATOR_NAME \
       --folder=FOLDER_NUMBER \
       --state=stopped
   

   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 numeric folder ID of the folder in which the policy orchestrator exists.

   Example

     gcloud --billing-project=my-quota-project beta compute os-config policy-orchestrators update my-os-policy-orchestrator \
       --folder=123456 \
       --include-projects=5432134,4567890
   

REST

To update a policy orchestrator in a folder, complete the following steps, send a PATCH request to the folders.locations.global.policyOrchestrators.patch method.

In the request body, edit the OS policy assignment specifications.

    PATCH https://osconfig.googleapis.com/v2beta/folders/FOLDER_NUMBER/locations/global/policyOrchestrators/ORCHESTRATOR_NAME
    -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 the policy orchestrator exists.
• ORCHESTRATOR_NAME: the name of the policy orchestrator that you want to edit.
• 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.

Delete a policy orchestrator

Note: Deleting a policy orchestrator only deletes the policy orchestrator resource from the specified scope, not the OS policy assignments it applied on the zonal resources. If you want to delete the OS policy assignments created by a policy orchestrator, first edit the orchestrator and change its action to delete. After the orchestrator deletes the OS policy assignments, delete the orchestrator.

To delete a policy orchestrator and to cancel all ongoing rollouts, complete the following steps:

Console

To delete a policy orchestrator, do the following:

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

   Go to OS policies

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

3. Click Policy Orchestrators.

4. Select the name of the policy orchestrator that you want to delete. The Orchestrator details page opens.

5. Click Delete.

gcloud

To delete a policy orchestrator from a folder, do the following:

1. Use the beta os-config policy-orchestrators delete command:

     gcloud --billing-project=QUOTA_PROJECT_IDbeta compute os-config policy-orchestrators delete ORCHESTRATOR_NAME \
       --folder=FOLDER_NUMBER \
       --policy-id=POLICY_ID
   

   Replace the following:

   • QUOTA_PROJECT_ID: the project ID of the quota or the billing project.
   • ORCHESTRATOR_NAME: name for the policy orchestrator.
   • FOLDER_NUMBER: the numeric ID of the folder in which you created the policy orchestrator.
   • POLICY_ID: the ID assigned to the policy orchestrator.

   Example

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

REST

To delete a policy orchestrator in a folder, send a DELETE request to the folders.locations.global.policyOrchestrators.delete method:

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

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 the policy orchestrator exists.
• ORCHESTRATOR_NAME: the name of the policy orchestrator that you want to delete.

What's next?

• Learn how to manage OS policy assignments using policy orchestrator.