Console
    Contact Us Start free

    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.

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

    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

    1. In the Google Cloud console, go to the Organization policiespage.

      Go to Organization policies

    2. From the organization selector, select your organization resource.

    3. 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 policiespage, and then click Edit constraint.

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

      1. In the Display namebox, 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 IDbox, 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 Descriptionbox, 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 typebox, 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 methodsection, 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 conditionpanel, 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 Actionsection, 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.

    5. Click Test constraint.

    6. If this is a new constraint, then the Configure organization policypane appears. To define an organization policy that enforces the custom constraint, do the following:

      1. In the Select scopebox, 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 Enforcementsection, 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 historypage 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 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.

      • DESCRIPTION : 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 For more information about how to create custom constraints, see Creating and managing custom constraints .

    2. Create or modify an organization policy that enforces the custom constraint.

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

          name 
 : 
  
 organizations/ ORGANIZATION_ID 
/policies/ CONSTRAINT_NAME 
 
 spec 
 : 
  
 rules 
 : 
  
 - 
  
 enforce 
 : 
  
 true

        Replace the following:

        • ORGANIZATION_ID with your organization ID, such as 1234567890123 .

        • CONSTRAINT_NAME with the name of the custom constraint you want to test. For example, custom.EnforceGKEBinaryAuthz .

      • To test enforcing a custom constraint conditionally based on the existence of a particular tag, create a JSON or YAML file that defines the organization policy:

          name 
 : 
  
 organizations/ ORGANIZATION_ID 
/policies/ CONSTRAINT_NAME 
 
 spec 
 : 
  
 rules 
 : 
  
 - 
  
 condition 
 : 
  
 expression 
 : 
  
  CONDITION 
 
  
 enforce 
 : 
  
 false 
  
 - 
  
 enforce 
 : 
  
 true

        Replace the following:

        • ORGANIZATION_ID with your organization ID, such as 1234567890123 .

        • CONSTRAINT_NAME with the name of the custom constraint you want to test. For example, custom.EnforceGKEBinaryAuthz .

        • CONDITION with a CEL condition that refers to a supported service resource, for example "resource.matchTag('env', 'dev')" .

        For more information about conditional organization policies, see Setting an organization policy with tags .

      • To test deleting an organization policy that enforces a custom constraint, create a JSON or YAML file that defines the organization policy with no rules set except for inheriting the policy from its parent resource:

          name 
 : 
  
 organizations/ ORGANIZATION_ID 
/policies/ CONSTRAINT_NAME 
 
 spec 
 : 
  
 inheritFromParent 
 : 
  
 true

        Replace the following:

        • ORGANIZATION_ID with your organization ID, such as 1234567890123 .

        • CONSTRAINT_NAME with the name of the custom constraint you want to test. For example, custom.EnforceGKEBinaryAuthz .

    3. To simulate the change to a custom constraint, organization policy, or both, run the policy-intelligence simulate orgpolicy command:

       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 that 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 on the Simulation history page of 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 policiespage.

      Go to Organization policies

    2. Click **Select project, and then select the organization, folder, or project resource for which you want to edit the organization policy.

    3. From the list, select the managed constraint for which you want to update the organization policy. On the Policy detailspage, 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 policypage, select Override parent's policy.

    6. Click Add a rule.

    7. In the Enforcementsection, 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 historypage 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. Create or modify an organization policy that enforces a managed constraint.

      • To test creating or updating an organization policy that enforces a managed constraint, create a JSON or YAML file that defines the organization policy.

          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 .

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

          name 
 : 
  
 organizations/ ORGANIZATION_ID 
/policies/ CONSTRAINT_NAME 
 
 spec 
 : 
  
 inheritFromParent 
 : 
  
 true

      Replace the following:

      • ORGANIZATION_ID with your organization ID.

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

    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 on the Simulation history page of 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 historypage.

    Go to Simulation history

    Select a simulation to see details. On the Simulation reportpage, 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 detailsto see the specific configuration that was simulated. If you simulated an organization policy, the Policy detailstab 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 enforce 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 historypage.

      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 clicking Set dry run policy. The Policy detailspage for the new organization policy page appears.

      You can enforce the organization policy immediately by clicking and then clicking 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 historypage.

      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
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: