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

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

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 constraint, or both at the same time.

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

For example, a custom constraint that restricts the creation of Google Kubernetes Engine cluster resources where Binary Authorization is not enabled should look similar to the following:
```
name: "organizations/ORGANIZATION_ID/customConstraints/custom.EnforceGKEBinaryAuthz"
resource_types: "container.googleapis.com/Cluster"
method_types: CREATE
condition: "resource.binaryAuthorization.enabled == true"
action_type: ALLOW
```
Replace ORGANIZATION_ID with your organization ID, such as 1234567890123.

For more information about how to create custom constraints, see Creating and managing custom constraints.
To test an organization policy that enforces a custom constraint, create a JSON or YAML file that defines the organization policy you want to test.

For example, an organization policy that restricts the creation of Google Kubernetes Engine cluster resources where Binary Authorization is not enabled should look similar to the following:
```
name: "organizations/ORGANIZATION_ID/policies/custom.EnforceGKEBinaryAuthz"
spec:
    rules:
    - enforce: true
```
Replace ORGANIZATION_ID with your organization ID, such as 1234567890123.
To test an organization policy that conditionally enforces a custom constraint based on the existence of a particular tag, create a JSON or YAML file that defines the organization policy you want to test.

For example, the following organization policy restricts the creation of Google Kubernetes Engine cluster resources where Binary Authorization is not enabled, except on resources that have the tag env=dev attached.
```
name: "organizations/ORGANIZATION_ID/policies/custom.EnforceGKEBinaryAuthz"
spec:
    rules:
    - condition:
        expression: resource.matchTag('env', 'dev')
      enforce: false
    - enforce: true
```
Replace ORGANIZATION_ID with your organization ID, such as 1234567890123.

For more information about conditional organization policies, see Setting an organization policy with tags.
To test the deletion of an organization policy that enforces a custom constraint, create a JSON or YAML file that defines the organization policy but sets no rules, and inherits the policy from its parent resource.

For example, the following organization policy would simulate deleting an existing custom.EnforceGKEBinaryAuthz custom constraint.
```
name: "organizations/ORGANIZATION_ID/policies/custom.EnforceGKEBinaryAuthz"
spec:
    inheritFromParent: true
```

Run the following command to simulate the change to the custom constraint, organization policy, or both:

gcloud beta policy-intelligence simulate orgpolicy \
   --organization=ORGANIZATION_ID \
   --custom-constraints=CONSTRAINT_PATH \
   --policies=POLICY_PATH

Replace the following:

ORGANIZATION_ID: your organization ID, such as 1234567890123. Simulating changes over multiple organizations is not supported.
CONSTRAINT_PATH: the full path to the custom constraint you have created or updated. For example, tmp/constraint.yaml If you set the --policies flag, you don't need to set the --custom-constraints flag.
POLICY_PATH: the full path to the organization policy you have created or updated. For example, tmp/policy.yaml If you set the --custom-constraints flag, you don't need to set the --policies flag.

After several minutes, the command prints a list of resources that would violate the changes to the custom constraint, the organization policy, or both.

The following is a sample response for an organization policy simulation. This simulation involves a custom constraint that restricts the creation of Google Kubernetes Engine cluster resources where Binary Authorization is not enabled. In this case, if the proposed change were applied, two cluster resources would violate the policy: orgpolicy-test-cluster under the project simulator-test-project, and autopilot-cluster-1 under the project orgpolicy-test-0.

Waiting for operation [organizations/012345678901/locations/global/orgPolic
yViolationsPreviews/85be9a2d-8c49-470d-a65a-d0cb9ffa8f83/operations/1883a83
c-c448-42e5-a7c5-10a850928f06] to complete...done.
---
customConstraint:
 actionType: ALLOW
 condition: resource.binaryAuthorization.enabled == true
 methodTypes:
 - CREATE
 name: organizations/012345678901/customConstraints/custom.EnforceGKEBinaryAuthz
 resourceTypes:
 - container.googleapis.com/Cluster
name: organizations/012345678901/locations/global/orgPolicyViolationsPreviews/3dd47fd3-6df1-4156-8f10-413a3fc0ed83/orgPolicyViolations/b9fd23a5-7163-46de-9fec-7b9aa6af1113
resource:
 ancestors:
 - organizations/012345678901
 - projects/456789012345
 assetType: container.googleapis.com/Cluster
 resource: //container.googleapis.com/projects/simulator-test-project/locations/us-central1/clusters/orgpolicy-test-cluster
---
customConstraint:
 actionType: ALLOW
 condition: resource.binaryAuthorization.enabled == true
 methodTypes:
 - CREATE
 name: organizations/012345678901/customConstraints/custom.EnforceGKEBinaryAuthz
 resourceTypes:
 - container.googleapis.com/Cluster
name: organizations/012345678901/locations/global/orgPolicyViolationsPreviews/3dd47fd3-6df1-4156-8f10-413a3fc0ed83/orgPolicyViolations/e73896e6-7613-4a8d-8436-5df7a6455121
resource:
 ancestors:
 - organizations/012345678901
 - folders/789012345678
 - projects/456789012345
 assetType: container.googleapis.com/Cluster
 resource: //container.googleapis.com/projects/orgpolicy-test-0/locations/us-central1/clusters/autopilot-cluster-1

Apply a tested policy change

After you have tested your custom constraint, organization policy, or both, you can set up the custom constraint and enforce the organization policy using the normal processes.

To enforce a custom constraint, you must set it up to make it available for organization policies in your organization. To set up a custom constraint, use the gcloud org-policies set-custom-constraint command:
```
gcloud org-policies set-custom-constraint CONSTRAINT_PATH
```
Replace CONSTRAINT_PATH with the full path to your custom constraint file. For example, /home/user/customconstraint.yaml.

After this is completed, your custom constraint is available in your list of Google Cloud organization policies.
To enforce an organization policy containing a custom constraint, use the gcloud org-policies set-policy command:
```
gcloud org-policies set-policy POLICY_PATH
```
Replace POLICY_PATH with the full path to your organization policy YAML file.

The policy will take up to 15 minutes to take effect.

Save simulation results

If you are using the gcloud CLI, you can save Policy Simulator results as JSON or YAML files.

By default, test results in the Google Cloud CLI are output in YAML format. To save a test result as a YAML file, redirect the output of the simulate orgpolicy command when running the simulation:

> FILENAME

Replace FILENAME with a name for the output file.

To save a test result as a JSON file, add the following flag to the simulate orgpolicy command when running the simulation:

--format=json > FILENAME