This guide explains how to create an organization policy with a particularconstraint. The constraints used in the examples on this page aren't actualconstraints, but generalized samples for educational purposes.

For more information on constraints and the problems they solve, review thelist of all Organization Policy Service constraints.

Before you begin

• Read theIntroduction to the Organization Policy Service page to learn howorganization policy works.

• Read theUnderstanding hierarchy evaluation page tolearn about policy inheritance.

Required roles

To get the permissions that you need to manage organization policies, ask your administrator to grant you theOrganization policy administrator (roles/orgpolicy.policyAdmin) IAM role on the organization. For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

Delegate organization policy administration

To delegate the administration of organization policies to another principal, adda condition to the role binding:

"bindings":[{"role":"roles/orgpolicy.policyAdmin","members":["PRINCIPAL_1","PRINCIPAL_2"],"condition":{"title":"TITLE","description":"DESCRIPTION","expression":"resource.matchTag('TAG_KEY', 'TAG_VALUE')"}}]

Replace the following:

• PRINCIPAL_1,PRINCIPAL_2: a list ofprincipals to which you want to delegate the Organization policy administratorrole.

• TITLE: the title of your conditional expression&emdash;forexample, "Organization policy administrator for development environments".

• DESCRIPTION: an optional description for yourexpression.

• TAG_KEY: The namespaced name of the tag key&emdash;forexample,123456789012/environment.

• TAG_VALUE: The name of the tag value. The role is onlygranted on resources on which this tag is attached&emdash;for example,development.

For more information about using conditions in allow policies, seeOverview of IAM Conditions.

Use list rules in an organization policy

You can set an organization policy on your organization resource that uses listrules to deny access to a particular service. The following process describeshow to set an organization policy using the Google Cloud CLI. For instructions onhow to view and set organization policies using the Google Cloud console, seeCreating and Managing Policies.

Organization policies using list rules cannot have more than 500individual allowed or denied values, and cannot be more than 32 KB. If anorganization policy is created or updated to have more than 500 values, or begreater than 32 KB in size, it can't save successfully, and the request willreturn an error.

Set up enforcement on the organization resource

To set up enforcement on an organization using gcloud CLI, followthese steps:

1. Get the current policy on the organization resource using thedescribecommand. This command returns the policy directly applied to this resource:

   gcloudorg-policiesdescribe\CONSTRAINT_NAME--organization=ORGANIZATION_ID

   Replace the following:

   • ORGANIZATION_ID: a unique identifier for theorganization resource.Organization IDis formatted as decimal numbers, and cannot have leading zeros.

   • CONSTRAINT_NAME: the constraint for theservice that you want to enforce. For example, thegcp.restrictNonCmekServices constraint restricts whichservices can create resources without customer-managed encryptionkeys (CMEK).

   You can also apply the organization policy to a folder or a project with the--folder or the--project flags, and thefolder IDandproject ID,respectively.

   The response returns the current organization policy, if one exists.For example:

   name:projects/841166443394/policies/gcp.resourceLocationsspec:etag:BwW5P5cEOGs=inheritFromParent:truerules:-condition:expression:resource.matchTagId("tagKeys/1111", "tagValues/2222")values:allowedValues:-in:us-east1-locations-condition:expression:resource.matchTag("123/env", "prod")values:allowedValues:-in:us-west1-locations-values:deniedValues:-in:asia-south1-locationsupdateTime:'2021-01-19T12:00:51.095Z'

   If a policy isn't set, this will return aNOT_FOUND error:

   ERROR:(gcloud.org-policies.describe)NOT_FOUND:Requestedentitywasnotfound.

2. Set the policy on the organization using theset-policy command. Thisoverwrites any policy attached to the resource.

   1. Create a temporary file/tmp/policy.yaml to store the policy:

      name:organizations/ORGANIZATION_ID/policies/CONSTRAINT_NAMEspec:rules:-values:deniedValues:-VALUE_A

   2. Run theset-policy command:

      gcloudorg-policiesset-policy/tmp/policy.yaml

3. View the current effective policy usingdescribe --effective. This returnsthe organization policy as it is evaluated at this point in the resourcehierarchy with inheritance included.

   gcloudorg-policiesdescribe\CONSTRAINT_NAME--effective\--organization=ORGANIZATION_ID

   The output of the command will be:

   name:organizations/ORGANIZATION_ID/policies/CONSTRAINT_NAMEspec:etag:BwVJi0OOESU=rules:-values:deniedValues:-VALUE_A

   Because this organization policy was set at the organization level, it willbeinherited by all child resources that allowinheritance.

Changes to organization policies can take up to 15 minutes to be fully enforced.

Set up enforcement against a hierarchy subtree

Constraints with list rules take explicitly defined values to determinewhich resources should be allowed or denied. Some constraints can also acceptvalues that use the prefixunder:, which specifies a subtree with thatresource as the root. Using theunder: prefix on an allowed or denied valuecauses the organization policy to act on that resource and all of its children.For information about the constraints that allow using theunder: prefix, seetheOrganization policy constraintspage.

A value that uses theunder: prefix is called a hierarchy subtree string. Ahierarchy subtree string specifies the typeof resource it applies to. For example, using a subtree string ofprojects/PROJECT_ID when setting theconstraints/compute.storageResourceUseRestrictions constraint will allow ordeny the use of Compute Engine storage forPROJECT_IDand all of its children.

1. Get the current policy on the organization resource using thedescribecommand:

   gcloudorg-policiesdescribe\CONSTRAINT_NAME\--organization=ORGANIZATION_ID

   Replace the following:

   • ORGANIZATION_IDis a unique identifier for the organization resource.

   • CONSTRAINT_NAME is the constraint for the servicethat you want to enforce.

   You can also apply the organization policy to a folder or a project with the--folder or the--project flags, and thefolder IDandproject ID,respectively.

   If a policy isn't set, this will return aNOT_FOUND error:

   ERROR:(gcloud.org-policies.describe)NOT_FOUND:Requestedentitywasnotfound.

2. Set the policy on the project using theset-policy command. Theunder:prefix sets the constraint to deny the named resource and all of its childresources.

   1. Create a temporary file/tmp/policy.yaml to store the policy:

      name:organizations/ORGANIZATION_ID/policies/CONSTRAINT_NAMEspec:rules:-values:deniedValues:-under:folders/VALUE_A

   2. Run theset-policy command:

      gcloudorg-policiesset-policy/tmp/policy.yaml

   Where:

   • under: is a prefix that signifies what follows is a subtreestring.

   • folders/VALUE_A is thefolder IDof the root resource you want to deny. This resource and all of itschildren in the resource hierarchy will be denied.

   You can also apply theunder: prefix to organizations and projects, as inthe following examples:

   • under:organizations/VALUE_X

   • under:projects/VALUE_Y

3. View the current effective policy usingdescribe --effective.

   gcloudorg-policiesdescribe\CONSTRAINT_NAME--effective\--organization=ORGANIZATION_ID

   The output of the command will be:

   name:organizations/ORGANIZATION_ID/policies/CONSTRAINT_NAMEspec:rules:-values:deniedValues:-under:folders/VALUE_A

   The policy now evaluates to deny the folderVALUE_A andall of its child resources.

Changes to organization policies can take up to 15 minutes to be fully enforced.

Merge the organization policy on a project

You can set an organization policy on a resource, which will merge withany policy inherited from its parent resource. This merged policywill then be evaluated to create a new effective policy based on the rules ofinheritance.

1. Get the current policy on the resource using thedescribe command:

   gcloudorg-policiesdescribe\CONSTRAINT_NAME\--project=PROJECT_ID

   Replace the following:

   • PROJECT_ID: theunique identifierof your project.

   • CONSTRAINT_NAME: the constraint for the servicethat you want to enforce.

   If a policy isn't set, this will return aNOT_FOUND error:

   ERROR:(gcloud.org-policies.describe)NOT_FOUND:Requestedentitywasnotfound.

2. Display the current effective policy using thedescribe --effectivecommand:

   gcloudorg-policiesdescribe\CONSTRAINT_NAME--effective\--project=PROJECT_ID

   The output of the command will include a denied value that it inherits fromthe organization resource:

   name:projects/PROJECT_ID/policies/CONSTRAINT_NAMEspec:rules:-values:deniedValues:-VALUE_A

3. Set the policy on the project using theset-policy command.

   1. Create a temporary file/tmp/policy.yaml to store the policy:

      name:projects/PROJECT_ID/policies/CONSTRAINT_NAMEspec:inheritFromParent:truerules:-values:deniedValues:-VALUE_B-VALUE_C

   2. Run theset-policy command:

      gcloudorg-policiesset-policy/tmp/policy.yaml

4. Use thedescribe --effective command again to display the updated policy:

   gcloudorg-policiesdescribe\CONSTRAINT_NAME--effective\--project=PROJECT_ID

   The output of the command will include the effective result of merging thepolicy from the resource and from the parent:

   name:projects/PROJECT_ID/policies/CONSTRAINT_NAMEspec:rules:-values:deniedValues:-VALUE_A-VALUE_B-VALUE_C

Changes to organization policies can take up to 15 minutes to be fully enforced.

Restore default constraint behavior

You can use thereset command to reset the policy to use the constraint'sdefault behavior. For a list of all available constraints and their defaultvalues, seeOrganization policy constraints.Thefollowing example assumes that the default constraint behavior is to allow allvalues.

1. Get the effective policy on the project to show the current merged policy:

   gcloudorg-policiesdescribe\CONSTRAINT_NAME--effective\--project=PROJECT_ID

   ReplacePROJECT_ID with theunique identifierof your project. The output of the command will be:

   name:projects/PROJECT_ID/policies/CONSTRAINT_NAMEspec:rules:-values:deniedValues:-VALUE_A-VALUE_B-VALUE_C

2. Reset the organization policy using thereset command.

   gcloudorg-policiesresetCONSTRAINT_NAME\--project=PROJECT_ID

3. Get the effective policy to verify the default behavior:

   gcloudorg-policiesdescribe\CONSTRAINT_NAME--effective\--project=PROJECT_ID

   The output of the command will allow all values:

   name:projects/PROJECT_ID/policies/CONSTRAINT_NAMEspec:rules:-allowAll:true

Changes to organization policies can take up to 15 minutes to be fully enforced.

Delete an organization policy

You can delete an organization policy from a resource. A resource without anorganization policy set will inherit any policy of its parent resource. If youdelete the organization policy on the organization resource, the effectivepolicy will be the constraint's default behavior.

The following steps describe how to delete an organization policy on anorganization.

1. Delete the policy on the organization resource using thedeletecommand:

   gcloudorg-policiesdelete\CONSTRAINT_NAME\--organization=ORGANIZATION_ID

   ReplaceORGANIZATION_IDwith the unique identifier for the organization resource. The output ofthe command will be:

   Deletedpolicy[organizations/ORGANIZATION_ID/policies/CONSTRAINT_NAME].{}

2. Get the effective policy on the organization to verify it's not enforced:

   gcloudorg-policiesdescribe\CONSTRAINT_NAME--effective\--organization=ORGANIZATION_ID

   The output of the command will be:

   name:organizations/ORGANIZATION_ID/policies/CONSTRAINT_NAMEspec:rules:-allowAll:true

The following steps describe how to delete an organization policy on aproject:

1. Delete the policy on a project using thedelete command:

   gcloudorg-policiesdelete\CONSTRAINT_NAME\--project=PROJECT_ID

   WherePROJECT_ID is theunique identifierof your project. The output of the command will be:

   Deletedpolicy[projects/PROJECT_ID/policies/CONSTRAINT_NAME].{}

2. Get the effective policy on the project to verify it's not enforced:

   gcloudorg-policiesdescribe\CONSTRAINT_NAME--effective\--project=PROJECT_ID

   The output of the command will be:

   name:projects/PROJECT_ID/policies/CONSTRAINT_NAMEspec:rules:-allowAll:true

Changes to organization policies can take up to 15 minutes to be fully enforced.

Use boolean rules in organization policy

Set up enforcement on the organization resource

The following process describes how to set an organization policy with booleanrules using the Google Cloud CLI. For instructions on how to viewand set organization policies using the Google Cloud console, seeCreating and Managing Policies.

1. Get the current policy on the organization resource by using thedescribecommand:

   gcloudorg-policiesdescribe\CONSTRAINT_NAME\--organization=ORGANIZATION_ID

   ReplaceORGANIZATION_IDwith the unique identifier for the organization resource. You can alsoapply the organization policy to a folder or a project with the--folder or the--project flags, and thefolder IDandproject ID,respectively.

   If a policy isn't set, this will return aNOT_FOUND error:

   ERROR:(gcloud.org-policies.describe)NOT_FOUND:Requestedentitywasnotfound.

2. Set the policy on the project using theset-policy command.

   1. Create a temporary file/tmp/policy.yaml to store the policy:

      name:organizations/ORGANIZATION_ID/policies/CONSTRAINT_NAMEspec:rules:-enforce:true

   2. Run theset-policy command:

      gcloudorg-policiesset-policy/tmp/policy.yaml

3. View the current effective policy usingdescribe --effective:

   gcloudorg-policiesdescribe\CONSTRAINT_NAME--effective\--organization=ORGANIZATION_ID

   The output of the command will be:

   name:organizations/ORGANIZATION_ID/policies/BOOLEAN_CONSTRAINTspec:rules:-enforce:true

Changes to organization policies can take up to 15 minutes to be fully enforced.

Override the organization policy for a project

To override the organization policy for a project, set a policy that disablesenforcement of the constraint to all resources in the hierarchy below theproject.

1. Get the current policy on the resource to show it's empty.

   gcloudorg-policiesdescribe\CONSTRAINT_NAME\--project=PROJECT_ID

   WherePROJECT_ID is theunique identifierof your project.

   If a policy isn't set, this will return aNOT_FOUND error:

   ERROR:(gcloud.org-policies.describe)NOT_FOUND:Requestedentitywasnotfound.

2. Get the effective policy on the project, which confirms that the constraintis being enforced at this project.

   gcloudorg-policiesdescribe\CONSTRAINT_NAME--effective\--project=PROJECT_ID

   The output of the command will be:

   name:projects/PROJECT_ID/policies/BOOLEAN_CONSTRAINTspec:rules:-enforce:true

3. Set the policy on the project using theset-policy command.

   1. Create a temporary file/tmp/policy.yaml to store the policy:

      name:projects/PROJECT_ID/policies/CONSTRAINT_NAMEspec:rules:-enforce:false

   2. Run theset-policy command:

      gcloudorg-policiesset-policy/tmp/policy.yaml

4. Get the effective policy to show that it is no longer enforced on theproject.

   gcloudorg-policiesdescribe\CONSTRAINT_NAME--effective\--project=PROJECT_ID

   The output of the command will be:

   name:organizations/ORGANIZATION_ID/policies/BOOLEAN_CONSTRAINTspec:rules:-enforce:false

Changes to organization policies can take up to 15 minutes to be fully enforced.

Delete an organization policy

You can delete an organization policy from a resource. A resource without anorganization policy set will inherit any policy of its parent resource. If youdelete the organization policy on the organization resource, the effectivepolicy will be the constraints' default behavior.

The following steps describe how to delete an organization policy on anorganization and a project.

1. Delete the policy from the organization resource using thedelete command:

   gcloudorg-policiesdelete\CONSTRAINT_NAME\--organization=ORGANIZATION_ID

   ReplaceORGANIZATION_IDwith a unique identifier for the organization resource. The output ofthe command will be:

   Deletedpolicy[organizations/ORGANIZATION_ID/policies/CONSTRAINT_NAME].{}

2. Get the effective policy on the organization to verify it's not enforced:

   gcloudorg-policiesdescribe\CONSTRAINT_NAME--effective\--organization=ORGANIZATION_ID

   If a policy isn't set, this will return aNOT_FOUND error:

   ERROR:(gcloud.org-policies.describe)NOT_FOUND:Requestedentitywasnotfound.

3. Delete the organization policy from the project using thedelete command:

   gcloudorg-policiesdelete\CONSTRAINT_NAME\--project=PROJECT_ID

   The output of the command will be:

   Deletedpolicy[organizations/ORGANIZATION_ID/policies/CONSTRAINT_NAME].{}

4. Get the effective policy on the project to verify it's not enforced:

   gcloudorg-policiesdescribe\CONSTRAINT_NAME--effective\--project=PROJECT_ID

   ReplacePROJECT_IDwith the unique identifier of your project.

   If a policy isn't set, this will return aNOT_FOUND error:

   ERROR:(gcloud.org-policies.describe)NOT_FOUND:Requestedentitywasnotfound.

Changes to organization policies can take up to 15 minutes to be fully enforced.

Using managed constraints in an organization policy

Managed constraints are built on thecustom organization policyplatform. They can use Policy Simulator for Organization Policy Service and dry-runorganization policies to more safely deploy policy changes.

View and identify managed constraints

To see the available managed constraints for your organization, do thefollowing:

gcloudorg-policieslist-custom-constraints\--organization=ORGANIZATION_ID

gcloudorg-policiesdescribe-custom-constraintCONSTRAINT_NAME\--organization=ORGANIZATION_ID

GEThttps://orgpolicy.googleapis.com/v2/{parent=organizations/ORGANIZATION_ID}/customConstraints

Creating and updating managed constraints

Organization policies are defined by the configuration of the constraint. Theycan be set on a resource, inherited from a parent resource, or reset to theGoogle-managed default behavior.

Note: Managed constraints that are inherited from a parent resource aren't merged to evaluate the effective policy on a given resource. A resource that inherits a managed constraint enforces the constraint as it was set on the parent resource or overrides the constraint with its own policy.

To create or update an organization policy based on a managed constraint, do thefollowing:

POSThttps://orgpolicy.googleapis.com/v2/{parent=organizations/ORGANIZATION_ID}/policies

{"name":"RESOURCE_TYPE/RESOURCE_ID/policies/CONSTRAINT_NAME","spec":{"rules":[{"enforce":["ENFORCEMENT_STATE"],"parameters":{"LIST_PARAMETER":["LIST_VALUE_1","LIST_VALUE_2"],BOOLEAN_PARAMETER:BOOLEAN_VALUE}}]}"dryRunSpec":{"rules":[{"enforce":["ENFORCEMENT_STATE"],"parameters":{"LIST_PARAMETER":["LIST_VALUE_1","LIST_VALUE_2"],BOOLEAN_PARAMETER:BOOLEAN_VALUE}}]}}

Changes to organization policies can take up to 15 minutes to be fully enforced.