This guide explains how to create an organization policy with a particular constraint. The constraints used in the examples on this page will not be actual constraints, but generalized samples for educational purposes.
For more information on constraints and the problems they solve, review the list of all Organization Policy Service constraints.
Before you begin
Read the Introduction to the Organization Policy Service page to learn how organization policy works.
Read the Understanding hierarchy evaluation page to learn about policy inheritance.
Required roles
To get the permissions that you need to manage organization policies,
ask your administrator to grant you the
Organization policy administrator (roles/orgpolicy.policyAdmin
) 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 manage organization policies. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to manage organization policies:
-
orgpolicy.constraints.list
-
orgpolicy.policies.create
-
orgpolicy.policies.delete
-
orgpolicy.policies.list
-
orgpolicy.policies.update
-
orgpolicy.policy.get
-
orgpolicy.policy.set
You might also be able to get these permissions with custom roles or other predefined roles.
Use list constraints with an organization policy
You can set an organization policy on your organization resource that uses a list constraint to deny access to a particular service. The following process describes how to set an organization policy using the Google Cloud CLI. For instructions on how to view and set organization policies using the Google Cloud console, see Creating and Managing Policies.
Organization policies using list constraints cannot have more than 500 individual allowed or denied values, and cannot be more than 32 KB. If an organization policy is created or updated to have more than 500 values, or be greater than 32 KB in size, it can't save successfully, and the request will return an error.
Set up enforcement on the organization resource
To set up enforcement on an organization using gcloud CLI, follow these steps:
Get the current policy on the organization resource using the
describe
command. This command returns the policy directly applied to this resource:gcloud org-policies describe \ LIST_CONSTRAINT --organization=ORGANIZATION_ID
Replace the following:
ORGANIZATION_ID
: a unique identifier for the organization resource. Organization ID is formatted as decimal numbers, and cannot have leading zeros.LIST_CONSTRAINT
: the list constraint for the service that you want to enforce. For example, theconstraints/gcp.restrictNonCmekServices
constraint restricts which services can create resources without customer-managed encryption keys (CMEK).
You can also apply the organization policy to a folder or a project with the
--folder
or the--project
flags, and the folder ID and project ID, respectively.The response returns the current organization policy, if one exists. For example:
name: projects/841166443394/policies/gcp.resourceLocations spec: etag: BwW5P5cEOGs= inheritFromParent: true rules: - 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-locations updateTime: '2021-01-19T12:00:51.095Z'
If a policy isn't set, this will return a
NOT_FOUND
error:ERROR: (gcloud.org-policies.describe) NOT_FOUND: Requested entity was not found.
Set the policy on the organization using the
set-policy
command. This overwrites any policy attached to the resource.Create a temporary file
/tmp/policy.yaml
to store the policy:name: organizations/ORGANIZATION_ID/policies/LIST_CONSTRAINT spec: rules: - values: deniedValues: - VALUE_A
Run the
set-policy
command:gcloud org-policies set-policy /tmp/policy.yaml
View the current effective policy using
describe --effective
. This returns the organization policy as it is evaluated at this point in the resource hierarchy with inheritance included.gcloud org-policies describe \ LIST_CONSTRAINT --effective \ --organization=ORGANIZATION_ID
The output of the command will be:
name: organizations/ORGANIZATION_ID/policies/LIST_CONSTRAINT spec: etag: BwVJi0OOESU= rules: - values: deniedValues: - VALUE_A
Because this organization policy was set at the organization level, it will be inherited by all child resources that allow inheritance.
Changes to organization policies can take up to 15 minutes to be fully enforced.
Set up enforcement against a hierarchy subtree
List constraints take explicitly defined values to determine which resources
should be allowed or denied. Some constraints can also accept values that use
the prefix under:
, which specifies a subtree with that resource as the root.
Using the under:
prefix on an allowed or denied value causes the organization
policy to act on that resource and all of its children. For information about
the constraints that allow using the under:
prefix, see the
Organization policy constraints
page.
A value that uses the under:
prefix is called a hierarchy subtree string. A
hierarchy subtree string specifies the type
of resource it applies to. For example, using a subtree string of
projects/PROJECT_ID
when setting the
constraints/compute.storageResourceUseRestrictions
constraint will allow or
deny the use of Compute Engine storage for PROJECT_ID
and all of its children.
Get the current policy on the organization resource using the
describe
command:gcloud org-policies describe \ LIST_CONSTRAINT \ --organization=ORGANIZATION_ID
Replace the following:
ORGANIZATION_ID
is a unique identifier for the organization resource.LIST_CONSTRAINT
is the list constraint for the service that 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 the folder ID and project ID, respectively.If a policy isn't set, this will return a
NOT_FOUND
error:ERROR: (gcloud.org-policies.describe) NOT_FOUND: Requested entity was not found.
Set the policy on the project using the
set-policy
command. Theunder:
prefix sets the constraint to deny the named resource and all of its child resources.Create a temporary file
/tmp/policy.yaml
to store the policy:name: organizations/ORGANIZATION_ID/policies/LIST_CONSTRAINT spec: rules: - values: deniedValues: - under:folders/VALUE_A
Run the
set-policy
command:gcloud org-policies set-policy /tmp/policy.yaml
Where:
under:
is a prefix that signifies what follows is a subtree string.folders/VALUE_A
is the folder ID of the root resource you want to deny. This resource and all of its children in the resource hierarchy will be denied.
You can also apply the
under:
prefix to organizations and projects, as in the following examples:under:organizations/VALUE_X
under:projects/VALUE_Y
View the current effective policy using
describe --effective
.gcloud org-policies describe \ LIST_CONSTRAINT --effective \ --organization=ORGANIZATION_ID
The output of the command will be:
name: organizations/ORGANIZATION_ID/policies/LIST_CONSTRAINT spec: rules: - values: deniedValues: - under:folders/VALUE_A
The policy now evaluates to deny the folder VALUE_A and all 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 with any policy inherited from its parent resource. This merged policy will then be evaluated to create a new effective policy based on the rules of inheritance.
Get the current policy on the resource using the
describe
command:gcloud org-policies describe \ LIST_CONSTRAINT \ --project=PROJECT_ID
Replace the following:
PROJECT_ID
: the unique identifier of your project.LIST_CONSTRAINT
: the list constraint for the service that you want to enforce.
If a policy isn't set, this will return a
NOT_FOUND
error:ERROR: (gcloud.org-policies.describe) NOT_FOUND: Requested entity was not found.
Display the current effective policy using the
describe --effective
command:gcloud org-policies describe \ LIST_CONSTRAINT --effective \ --project=PROJECT_ID
The output of the command will include a denied value that it inherits from the organization resource:
name: projects/PROJECT_ID/policies/LIST_CONSTRAINT spec: rules: - values: deniedValues: - VALUE_A
Set the policy on the project using the
set-policy
command.Create a temporary file
/tmp/policy.yaml
to store the policy:name: projects/PROJECT_ID/policies/LIST_CONSTRAINT spec: inheritFromParent: true rules: - values: deniedValues: - VALUE_B - VALUE_C
Run the
set-policy
command:gcloud org-policies set-policy /tmp/policy.yaml
Use the
describe --effective
command again to display the updated policy:gcloud org-policies describe \ LIST_CONSTRAINT --effective \ --project=PROJECT_ID
The output of the command will include the effective result of merging the policy from the resource and from the parent:
name: projects/PROJECT_ID/policies/LIST_CONSTRAINT spec: 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 the reset
command to reset the policy to use the constraint's
default behavior. For a list of all available constraints and their default
values, see Organization policy constraints.The
following example assumes that the default constraint behavior is to allow all
values.
Get the effective policy on the project to show the current merged policy:
gcloud org-policies describe \ LIST_CONSTRAINT --effective \ --project=PROJECT_ID
Replace PROJECT_ID with the unique identifier of your project. The output of the command will be:
name: projects/PROJECT_ID/policies/LIST_CONSTRAINT spec: rules: - values: deniedValues: - VALUE_A - VALUE_B - VALUE_C
Reset the organization policy using the
reset
command.gcloud org-policies reset LIST_CONSTRAINT \ --project=PROJECT_ID
Get the effective policy to verify the default behavior:
gcloud org-policies describe \ LIST_CONSTRAINT --effective \ --project=PROJECT_ID
The output of the command will allow all values:
name: projects/PROJECT_ID/policies/LIST_CONSTRAINT spec: 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 an organization policy set will inherit any policy of its parent resource. If you delete the organization policy on the organization resource, the effective policy will be the constraint's default behavior.
The following steps describe how to delete an organization policy on an organization.
Delete the policy on the organization resource using the
delete
command:gcloud org-policies delete \ LIST_CONSTRAINT \ --organization=ORGANIZATION_ID
Replace ORGANIZATION_ID with the unique identifier for the organization resource. The output of the command will be:
Deleted policy [organizations/ORGANIZATION_ID/policies/LIST_CONSTRAINT]. {}
Get the effective policy on the organization to verify it's not enforced:
gcloud org-policies describe \ LIST_CONSTRAINT --effective \ --organization=ORGANIZATION_ID
The output of the command will be:
name: organizations/ORGANIZATION_ID/policies/LIST_CONSTRAINT spec: rules: - allowAll: true
The following steps describe how to delete an organization policy on a project:
Delete the policy on a project using the
delete
command:gcloud org-policies delete \ LIST_CONSTRAINT \ --project=PROJECT_ID
Where
PROJECT_ID
is the unique identifier of your project. The output of the command will be:Deleted policy [projects/PROJECT_ID/policies/LIST_CONSTRAINT]. {}
Get the effective policy on the project to verify it's not enforced:
gcloud org-policies describe \ LIST_CONSTRAINT --effective \ --project=PROJECT_ID
The output of the command will be:
name: projects/PROJECT_ID/policies/LIST_CONSTRAINT spec: rules: - allowAll: true
Changes to organization policies can take up to 15 minutes to be fully enforced.
Using boolean constraints in organization policy
Set up enforcement on the organization resource
You can set an organization policy on your organization resource to enforce a boolean constraint. The following process describes how to set an organization policy using the Google Cloud CLI. For instructions on how to view and set organization policies using the Google Cloud console, see Creating and Managing Policies.
Get the current policy on the organization resource by using the
describe
command:gcloud org-policies describe \ BOOLEAN_CONSTRAINT \ --organization=ORGANIZATION_ID
Replace
ORGANIZATION_ID
with the unique identifier for the organization resource. You can also apply the organization policy to a folder or a project with the--folder
or the--project
flags, and the folder ID and project ID, respectively.If a policy isn't set, this will return a
NOT_FOUND
error:ERROR: (gcloud.org-policies.describe) NOT_FOUND: Requested entity was not found.
Set the policy on the project using the
set-policy
command.Create a temporary file
/tmp/policy.yaml
to store the policy:name: organizations/ORGANIZATION_ID/policies/BOOLEAN_CONSTRAINT spec: rules: - enforce: true
Run the
set-policy
command:gcloud org-policies set-policy /tmp/policy.yaml
View the current effective policy using
describe --effective
:gcloud org-policies describe \ BOOLEAN_CONSTRAINT --effective \ --organization=ORGANIZATION_ID
The output of the command will be:
name: organizations/ORGANIZATION_ID/policies/BOOLEAN_POLICY spec: 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 disables enforcement of the boolean constraint to all resources in the hierarchy below the project.
Get the current policy on the resource to show it's empty.
gcloud org-policies describe \ BOOLEAN_CONSTRAINT \ --project=PROJECT_ID
Where
PROJECT_ID
is the unique identifier of your project.If a policy isn't set, this will return a
NOT_FOUND
error:ERROR: (gcloud.org-policies.describe) NOT_FOUND: Requested entity was not found.
Get the effective policy on the project, which confirms that the constraint is being enforced at this project.
gcloud org-policies describe \ BOOLEAN_CONSTRAINT --effective \ --project=PROJECT_ID
The output of the command will be:
name: projects/PROJECT_ID/policies/BOOLEAN_POLICY spec: rules: - enforce: true
Set the policy on the project using the
set-policy
command.Create a temporary file
/tmp/policy.yaml
to store the policy:name: projects/PROJECT_ID/policies/BOOLEAN_CONSTRAINT spec: rules: - enforce: false
Run the
set-policy
command:gcloud org-policies set-policy /tmp/policy.yaml
Get the effective policy to show that it is no longer enforced on the project.
gcloud org-policies describe \ BOOLEAN_CONSTRAINT --effective \ --project=PROJECT_ID
The output of the command will be:
name: organizations/ORGANIZATION_ID/policies/BOOLEAN_POLICY spec: 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 an organization policy set will inherit any policy of its parent resource. If you delete the organization policy on the organization resource, the effective policy will be the constraints' default behavior.
The following steps describe how to delete an organization policy on an organization and a project.
Delete the policy from the organization resource using the
delete
command:gcloud org-policies delete \ BOOLEAN_CONSTRAINT \ --organization=ORGANIZATION_ID
Replace
ORGANIZATION_ID
with a unique identifier for the organization resource. The output of the command will be:Deleted policy [organizations/ORGANIZATION_ID/policies/BOOLEAN_CONSTRAINT]. {}
Get the effective policy on the organization to verify it's not enforced:
gcloud org-policies describe \ BOOLEAN_CONSTRAINT --effective \ --organization=ORGANIZATION_ID
If a policy isn't set, this will return a
NOT_FOUND
error:ERROR: (gcloud.org-policies.describe) NOT_FOUND: Requested entity was not found.
Delete the organization policy from the project using the
delete
command:gcloud org-policies delete \ BOOLEAN_CONSTRAINT \ --project=PROJECT_ID
The output of the command will be:
Deleted policy [organizations/ORGANIZATION_ID/policies/BOOLEAN_CONSTRAINT]. {}
Get the effective policy on the project to verify it's not enforced:
gcloud org-policies describe \ BOOLEAN_CONSTRAINT --effective \ --project=PROJECT_ID
Replace
PROJECT_ID
with the unique identifier of your project.If a policy isn't set, this will return a
NOT_FOUND
error:ERROR: (gcloud.org-policies.describe) NOT_FOUND: Requested entity was not found.
Changes to organization policies can take up to 15 minutes to be fully enforced.