Test organization policy changes with Policy Simulator

Preview

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

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.

  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.

Note: Policy Simulator cannot test changes to predefined constraints.

Test a change to a custom constraint

Console

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

   Go to Organization policies

2. Select the project picker at the top of the page.

3. From the project picker, select your organization resource.

4. If you want to test a new custom constraint, click Custom constraint. If you want to make changes to an existing custom constraint, select it from the list on the Organization policies page, and then click Edit constraint.

5. Create or update the custom constraint you want to test.

   For example, to define a custom constraint that restricts the creation of Google Kubernetes Engine cluster resources where Binary Authorization is not enabled, do the following:

   1. In the Resource type box, select container.googleapis.com/Cluster.

   2. Under Enforcement method, select Enforce on create.

   3. Click Edit condition.

   4. In the Add condition panel, enter resource.binaryAuthorization.enabled == true.

   5. Click Save.

   6. Under Action, select Allow.

   For more information, see Creating and managing custom constraints.

6. Click Test constraint.

7. If this is a new constraint or a constraint not enforced by an organization policy, you must define the organization policy.

   1. In the Select scope box, select the resource for which you want to test the custom constraint.

   2. Click Customize.

   3. Click Add a rule.

   4. Under Enforcement, select On, and then click Done.

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

1. 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 is 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.

2. 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 is 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.

   • You can test an organization policy that conditionally enforces a custom constraint based on the existence of a particular tag by including a condition in the JSON or YAML file that defines the organization policy.

     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.

   • You can test the effect of deleting an organization policy that enforces a custom constraint by creating a JSON or YAML file that defines the organization policy with no rules set except for inheriting 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
     

   Note: Only tags defined in the same organization are supported by Policy Simulator. If any tags are defined in a different organization, Policy Simulator returns an error and does not complete the simulation.

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

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

Results are also viewable in the Google Cloud console. See Policy Simulator results on this page to learn how to read the results.

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

Test a change to a managed constraint

Console

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

Go to Organization policies

1. From the project picker, select the project, folder, or organization for which you want to edit the organization policy.

2. The Organization policies page displays a filterable list of organization policy constraints that are available for this resource.

3. Select the managed constraint for which you want to update the organization policy from the list. On the Policy details page, you can see the source of this organization policy, the effective policy evaluation on this resource, and more details about the managed constraint.

4. To update the organization policy for this resource, click Manage policy.

5. On the Edit policy page, select Override parent's policy.

6. Select Add a rule.

7. Under Enforcement, select whether enforcement of this organization policy should be on or off.

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

9. Click Test changes.

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

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

   name: RESOURCE_TYPE/RESOURCE_ID/policies/CONSTRAINT_NAME
   spec:
     rules:
     - enforce: ENFORCEMENT_STATE
   

   Replace the following:

   • RESOURCE_TYPE with organizations, folders, or projects.

   • RESOURCE_ID with your organization ID, folder ID, project ID, or project number, depending on the type of resource specified in RESOURCE_TYPE.

   • CONSTRAINT_NAME with the name of the managed constraint you want to test. For example, iam.managed.disableServiceAccountKeyCreation.

   • ENFORCEMENT_STATE with true to enforce this organization policy when set, or false to disable it when set.

   Optionally, to make the organization policy conditional on a tag, add a condition block to the rules. 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.

   Note: Only tags defined in the same organization are supported by Policy Simulator. If any tags are defined in a different organization, Policy Simulator returns an error and does not complete the simulation.

   To test the deletion of an organization policy that enforces a managed constraint, the JSON or YAML file that defines the organization policy should have no rules set except for inheriting the policy from its parent resource.

   For example, the following organization policy would simulate deleting an existing iam.managed.disableServiceAccountKeyCreation managed constraint.

   name: organizations/ORGANIZATION_ID/policies/iam.managed.disableServiceAccountKeyCreation
   spec:
     inheritFromParent: true
   

2. Run the policy-intelligence simulate orgpolicy command:

   gcloud policy-intelligence simulate orgpolicy \
     --organization=ORGANIZATION_ID \
     --policies=POLICY_PATH
   

   Replace the following:

   • ORGANIZATION_ID with your organization ID, such as 1234567890123. Simulating changes over multiple organizations is not supported.

   • POLICY_PATH with the full path to your organization policy YAML file.

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

   Results are also viewable in the Google Cloud console. See Policy Simulator results on this page to learn how to read the results.

Policy Simulator results

Policy Simulator reports the results of a change in a custom constraint or organization policy as a list of violations of the simulated policy. The Google Cloud console stores results of simulations generated by you in the last 14 days.

To view simulation results, go to the Simulation history page.

Go to Simulation history

Select a simulation to see details. On the Simulation report page, you can see the preview of violations, which lists the number of total violations caused by the new custom constraint or organization policy, the number of resources that were checked in the scope of the simulation, and the time at which the simulation completed.

If you simulated a custom constraint, you can click Constraint details to see the specific configuration that was simulated. If you simulated an organization policy, the Policy details tab shows the configuration that was simulated.

All violations are listed in the table of resources. Each resource that violates the new custom constraint or organization policy is listed with a link to the resource entry in Cloud Asset Inventory. Project, folder, and organization resources are displayed with the sum total of resources below them in the hierarchy that violate the new custom constraint or organization policy.

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. You can see all Policy Simulator results in the Google Cloud console, regardless of how they were generated. If your simulation report includes changes to no more than one organization policy, you can enforced the organization policy directly through the simulation results. To enforce test changes in multiple organization policies, use the Google Cloud CLI.

Console

1. To enforce a custom constraint Policy Simulator results, go to the Simulation history page.

   Go to Simulation history

2. Select the simulation report for the custom constraint or organization policy you want to apply.

3. If this simulation report includes a custom constraint, click Save constraint.

4. If this simulation report includes changes to no more than one organization policy, you can apply that organization policy as a dry-run policy to monitor behavior in production without introducing risk by selecting Set dry run policy. The Policy details page for the new organization policy page appears.

   You can enforce the organization policy immediately by clicking and then selecting Set policy.

gcloud

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

2. To set the organization policy, 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 takes up to 15 minutes to take effect.

Save simulation results

Console

If you are using the Google Cloud console, you can save Policy Simulator results as a CSV file.

1. To save Policy Simulator results, go to the Simulation history page.

   Go to Simulation history

2. Select the simulation report you want to save.

3. Click Export full results.

gcloud

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

Replace FILENAME with a name for the output file.

What's next

• Learn about constraints in-depth.
• Read about the additional options you can use to customize your policies.
• Learn how to set organization policies based on Tags.