Prerequisites for 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 the prerequisites for using the policy orchestrator feature in VM Manager.

Set up a quota project for organization and folder orchestrations

When you use policy orchestrators to manage OS policy resources in your organization or folders, you make requests to a client-based API. A quota project is required for client-based APIs. For more information about client-based APIs and setting up quota projects, see Quota project overview.

When you use the gcloud CLI or REST API to call the policy orchestrator methods, specify the quota project as follows:

gcloud

Set your quota project in your gcloud CLI configuration property:

gcloud config set billing/quota_project QUOTA_PROJECT_ID

Replace QUOTA_PROJECT_ID with the project ID of the quota project.

Alternatively, set the quota project for a specific command by using the --billing-project flag, which takes precedence over the configuration property.

REST

Add the x-goog-user-project HTTP header to specify a quota project in each request. For details, see Set the quota project with a REST request.

Enable OS Config API

To use the policy orchestrator feature in VM Manager, enable OS Config API in the following projects:

• For organization-level and folder-level orchestrations, enable the OS Config API for the quota project.
• For project-level orchestrations, enable the OS Config API in the project where you create policy orchestrators.

For more information, see Enable OS Config API.

Enable Progressive Rollout API for the projects

Note: This step is required only for project-level orchestrations.

Console

1. In the Google Cloud console, select the Google Cloud project for which you want to enable the API, and then go to the APIs & Services page:

   Go to APIs & Services

2. Click Enable APIs and Services.

3. Search for "Progressive Rollout".

4. In the search results, click Progressive Rollout API.

5. If the API is not already enabled, then click Enable.

gcloud

1. To see if the Progressive Rollout API is enabled, run the following command after replacing PROJECT_ID with the ID of the project for which you want to enable the API:

    gcloud services list --project=PROJECT_ID
   

   If progressiverollout.googleapis.com appears in the output, the API is enabled.

2. If the API is not enabled, then run the following command to enable it:

    gcloud services enable progressiverollout.googleapis.com
   

   For more information, see gcloud services.

Set up the OS Config service agents

The policy orchestrator uses the OS Config service agents to perform actions in your projects. It also depends on the Progressive Rollout API, which has its own service agents. For more information, see Service agents.

You must create the service agents for each project, folder, or organization in which you create the policy orchestrator.

To create the service agents, do the following.

1. Review the format of the service agent email address for each resource:

   Project

   • [e-mail]
   • [e-mail]
   • [e-mail]

   Replace PROJECT_NUMBER with the numeric ID of the project where you create the policy orchestrators.

   Folder

   • [e-mail]
   • [e-mail]
   • [e-mail]

   Replace FOLDER_NUMBER with the numeric ID of the folder where you create the policy orchestrators.

   Organization

   • [e-mail]
   • [e-mail]
   • [e-mail]

   Replace ORGANIZATION_NUMBER with the numeric ID of the organization in which you create the policy orchestrators.

2. To create the service agent for a specified API and resource, use the gcloud beta services identity create command:

   Project

   gcloud beta services identity create --service=osconfig.googleapis.com  --project=PROJECT_NUMBER
   

   gcloud beta services identity create --service=progressiverollout.googleapis.com  --project=PROJECT_NUMBER
   

   Replace PROJECT_NUMBER with the numeric ID of the project in which you want to create the service agent.

   Folder

   gcloud beta services identity create --service=osconfig.googleapis.com  --folder=FOLDER_NUMBER
   

   gcloud beta services identity create --service=progressiverollout.googleapis.com  --folder=FOLDER_NUMBER
   

   Replace FOLDER_NUMBER with the numeric ID of the folder in which you want to create the service agent.

   Organization

   gcloud beta services identity create --service=osconfig.googleapis.com --organization=ORGANIZATION_NUMBER
   

   gcloud beta services identity create --service=progressiverollout.googleapis.com  --organization=ORGANIZATION_NUMBER
   

   Replace ORGANIZATION_NUMBER with the numeric ID of the organization in which you want to create the service agent.

Grant IAM roles to the service agents

For the policy orchestrator to work properly, you must grant all required service agent roles to the respective service accounts, at the parent resource of the orchestrator:

• OSConfig Service Agent (roles/osconfig.serviceAgent) for the @gcp-sa-osconfig.iam.gserviceaccount.com account
• OSConfig Rollout Service Agent (roles/osconfig.rolloutServiceAgent) for the @gcp-sa-osconfig-rollout.iam.gserviceaccount.com account
• Progressiverollout Service Agent (roles/progressiverollout.serviceAgent) for the @gcp-sa-progrollout.iam.gserviceaccount.com account

To grant IAM roles to the service agents, use the Google Cloud console or the add-iam-policy-binding command. For more information, see Grant a role to the service agent.

Required roles

• To get the permissions that you need to grant the service agents access, ask your administrator to grant you the following IAM roles on the project, folder, or organization that you're granting access to:

  • Grant service agents access to a project: Project IAM Admin (roles/resourcemanager.projectIamAdmin)
  • Grant service agents access to a folder: Folder Admin (roles/resourcemanager.folderAdmin)
  • Grant service agents access to projects, folders, and organizations: Organization Admin (roles/resourcemanager.organizationAdmin)

  For more information about granting roles, see Manage access to projects, folders, and organizations.

  These predefined roles contain the permissions required to grant the service agents access. To see the exact permissions that are required, expand the Required permissions section:

  Required permissions

  The following permissions are required to grant the service agents access:

  • Grant service agents access to a project:
    • resourcemanager.projects.getIamPolicy
    • resourcemanager.projects.setIamPolicy
  • Grant service agents access to a folder:
    • resourcemanager.folders.getIamPolicy
    • resourcemanager.folders.setIamPolicy
  • Grant service agents access to an organization:
    • resourcemanager.organizations.getIamPolicy
    • resourcemanager.organizations.setIamPolicy

  You might also be able to get these permissions with custom roles or other predefined roles.

To grant the service agent roles, run the gcloud add-iam-policy-binding as follows:

Project

gcloud projects add-iam-policy-binding PROJECT_ID \
 --member="serviceAccount:[e-mail]" \
 --role="roles/osconfig.rolloutServiceAgent"

 gcloud projects add-iam-policy-binding PROJECT_ID \
 --member="serviceAccount:[e-mail]" \
 --role="roles/osconfig.serviceAgent"

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="serviceAccount:[e-mail]" \
--role="roles/progressiverollout.serviceAgent"

Replace the PROJECT_NUMBER with the numeric ID of the project to which the IAM policy binding is being added.

Folder

gcloud resource-manager folders add-iam-policy-binding FOLDER_NUMBER \
 --member="serviceAccount:[e-mail]" \
 --role="roles/osconfig.rolloutServiceAgent"

 gcloud resource-manager folders add-iam-policy-binding FOLDER_NUMBER \
 --member="serviceAccount:[e-mail]" \
 --role="roles/osconfig.serviceAgent"

gcloud resource-manager folders add-iam-policy-binding FOLDER_NUMBER \
--member="serviceAccount:[e-mail]" \
--role="roles/progressiverollout.serviceAgent"

Replace the FOLDER_NUMBER with the numeric ID of the folder to which the IAM policy binding is being added.

Organization

gcloud organizations add-iam-policy-binding ORGANIZATION_NUMBER \
 --member="serviceAccount:[e-mail]" \
 --role="roles/osconfig.rolloutServiceAgent"

 gcloud organizations add-iam-policy-binding ORGANIZATION_NUMBER \
 --member="serviceAccount:[e-mail]" \
 --role="roles/osconfig.serviceAgent"

gcloud organizations add-iam-policy-binding ORGANIZATION_NUMBER \
--member="serviceAccount:[e-mail]" \
--role="roles/progressiverollout.serviceAgent"

Replace the ORGANIZATION_NUMBER with the numeric ID of the organization to which the IAM policy binding is being added.

What's next?

• Learn how to manage OS policy assignments using policy orchestrator.
• Learn how to view and edit policy orchestrators.