Test organization policy changes with Policy Simulator

Policy Simulator for Organization Policy lets you preview the impact of a new custom constraint or organization policy that enforces a custom or managed constraint before it is enforced on your production environment. Policy Simulator provides a list of resources that violate the proposed policy before it is enforced, allowing you to reconfigure those resources, request exceptions, or change the scope of your organization policy, all without disrupting your developers or bringing down your environment.

This page describes how to test a change to an organization policy using Policy Simulator. It also explains how to interpret the results of the simulation and how to apply the tested organization policy if you so choose.

Before you begin

If you are using the Google Cloud CLI, set the project you want to use for making API calls:

gcloud config set project PROJECT_ID

Replace PROJECT_ID with the name or ID of the project.
Enable the Policy Simulator and Resource Manager APIs.
Roles required to enable APIs
To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.
Enable the APIs
Optional: Get an introduction to the Organization Policy Service.

Required roles

To get the permissions that you need to run and access simulations, ask your administrator to grant you the OrgPolicy Simulator Admin (roles/policysimulator.orgPolicyAdmin) IAM role on the organization. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to run and access simulations. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to run and access simulations:

orgpolicy.constraints.list
orgpolicy.customConstraints.get
orgpolicy.policies.list
cloudasset.assets.searchAllResources
cloudasset.assets.listResource
cloudasset.assets.listOrgPolicy
policysimulator.orgPolicyViolationsPreviews.list
policysimulator.orgPolicyViolationsPreviews.get
policysimulator.orgPolicyViolationsPreviews.create
policysimulator.orgPolicyViolations.list

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

Test a policy change

You can test a change to a custom constraint, an organization policy that enforces a custom or managed constraint, or both at the same time.

Test a change to a custom constraint

Console

In the Google Cloud console, go to the Organization policies page.

Go to Organization policies
From the organization selector, select your organization resource.
Do one of the following:
- To test a new custom constraint, click Custom constraint.
- To make changes to an existing custom constraint, select it from the list on the Organization policies page, and then click Edit constraint.
Create or update the custom constraint you want to test.
1. In the Display name box, enter a human-friendly name for the constraint. This field has a maximum length of 200 characters. Don't use PII or sensitive data in display names, because it could be exposed in error messages.
2. In the Constraint ID box, enter the name you want for your new custom constraint. A custom constraint must start with custom., and can only include uppercase letters, lowercase letters, or numbers, for example, custom.disableGkeAutoUpgrade. The maximum length of this field is 70 characters, not counting the prefix, for example, organizations/123456789/customConstraints/custom.. Don't include PII or sensitive data in your constraint ID, because it could be exposed in error messages.
  
  The constraint ID can't be changed after a custom constraint is created.
3. In the Description box, enter a human-friendly description of the constraint to display as an error message when the policy is violated. This field has a maximum length of 2000 characters. Don't include PII or sensitive data in your description, because it could be exposed in error messages.
4. In the Resource type box, select the name of the Google Cloud REST resource containing the object and field you want to restrict—for example, container.googleapis.com/NodePool. Most resource types can have a maximum of 20 custom constraints per resource. If you try to create a custom constraint for a resource that already has the maximum number of custom constraints, the operation fails.
5. In the Enforcement method section, select whether to enforce the constraint on a REST CREATE method, or on both CREATE and UPDATE methods. Not all Google Cloud services support both methods. To see supported methods for each service, find the service in Supported services.
6. To define a condition, click Edit condition.
7. In the Add condition panel, create a CEL condition that refers to a supported service resource, for example resource.management.autoUpgrade == false. This field has a maximum length of 1000 characters. For details about CEL usage, see Common Expression Language. For more information about the service resources you can use in your custom constraints, see Custom constraint supported services.
8. Click Save.
9. In the Action section, select whether to allow or deny the evaluated method if the condition you wrote is met.
  
  The deny action means that the operation to create or update the resource is blocked if the condition evaluates to true.
  
  The allow action means that the operation to create or update the resource is permitted only if the condition evaluates to true. Every other case except ones explicitly listed in the condition is blocked.
Click Test constraint.
If this is a new constraint, then the Configure organization policy pane appears. To define an organization policy that enforces the custom constraint, do the following:
1. In the Select scope box, select the resource for which you want to test the custom constraint.
2. Click Override parents' policy.
3. Click Add a rule.
4. In the Enforcement section, select On.
5. Optionally, to make the organization policy conditional on a tag, click Add condition. If you add a conditional rule to an organization policy, you must add at least one unconditional rule or the policy cannot be saved. For more details, see Setting an organization policy with tags.
6. Click Done, and then click Continue.

The Simulation history page appears, with a list of simulations performed by you in the last 14 days. See Policy Simulator results on this page for more information.

gcloud

To test enforcing a new or updated custom constraint, create a JSON or YAML file that defines the custom constraint you want to test.

If you want to test changes to an existing custom constraint, you can use the organizations.customConstraints.get gcloud CLI command to retrieve the current JSON or YAML representation of the custom constraint, and then make edits to that file.

A YAML file that defines a custom constraint looks similar to the following:
```
name: organizations/ORGANIZATION_ID/customConstraints/CONSTRAINT_NAME
resourceTypes:
- RESOURCE_NAME
methodTypes:
- METHOD1
- METHOD2
condition: "CONDITION"
actionType: ACTION
displayName: DISPLAY_NAME
description: DESCRIPTION
```
Replace the following:
- ORGANIZATION_ID: your organization ID, such as 123456789.
- CONSTRAINT_NAME: the name you want for your new custom constraint. A custom constraint must start with custom., and can only include uppercase letters, lowercase letters, or numbers, for example, custom.disableGkeAutoUpgrade. The maximum length of this field is 70 characters, not counting the prefix, for example, organizations/123456789/customConstraints/custom..
- RESOURCE_NAME: the fully qualified name of the Google Cloud REST resource containing the object and field you want to restrict. For example, container.googleapis.com/NodePool. Most resource types can have a maximum of 20 custom constraints per resource. If you try to create a custom constraint for a resource that already has the maximum number of custom constraints, the operation fails. For more information about the service resources you can use in your custom constraints, see Custom constraint supported services.
- METHOD1,METHOD2: a list of RESTful methods for which to enforce the constraint. Can be CREATE or CREATE and UPDATE. Not all Google Cloud services support both methods. To see supported methods for each service, find the service in Supported services.
- CONDITION: a CEL condition that refers to a supported service resource, for example "resource.management.autoUpgrade == false". This field has a maximum length of 1000 characters. For details about CEL usage, see Common Expression Language.
- ACTION: the action to take if the condition is met. This can be either ALLOW or DENY.
  - The deny action means that if the condition evaluates to true, the operation to create or update the resource is blocked.
  - The allow action means that if the condition evaluates to true, the operation to create or update the resource is permitted. This also means that every other case except the one explicitly listed in the condition is blocked.
- DISPLAY_NAME: a human-friendly name for the constraint. This field has a maximum length of 200 characters.