Understanding Policies and Hierarchy Evaluation

An organization policy defines your organization's configuration restrictions for a resource. Organization policies are inherited down the resource hierarchy, and can be augmented or overridden at any level on which an organization policy can be set.

In the diagram below, you could set organization policies at the organization level, and they would flow down through to the projects level. A policy could also be applied to a project directly. The effective result on a given resource is determined by how the policy is defined along various points in the hierarchy, as described below in Hierarchical evaluation.

Policy hierarchy

Types of organization policies

Just as there are list constraints and boolean constraints, there are two corresponding types of organization policies: list policies and boolean policies. List policies can only be set for list constraints and boolean policies can only be set for boolean constraints. There is also a RestoreDefault message that can be used in a policy that replaces the inherited policy with the constraint default.

List policies

Using a list policy, you can define specific values that are allowed or denied for a given service aspect, or it can be used to allow or deny all of the values that a service defines for the aspect. Use the ListPolicy message to configure how the policy will be applied for list constraints.

In the case where you wish to allow a specific set of values, you would set ListPolicy.allowed_values to the strings that should be allowed, and set ListPolicy.all_values to ALL_VALUES_UNSPECIFIED. Likewise, if you need to specify a set of disallowed values, pass in the strings you want to deny when setting ListPolicy.denied_values, and set ListPolicy.all_values to ALL_VALUES_UNSPECIFIED.

If you simply want to either allow or disallow all valid values for the service aspect mapped to the constraint, just set ListPolicy.all_valuesto ALLOW or DENY. Note that if you use one of these settings, you must not attempt to set the ListPolicy.denied_values or ListPolicy.allowed_values properties.

At any policy attach point, the Organization Policy Administrator is free to use either allowed or denied values, regardless of what value types are used in policies above or below in the hierarchy. The evaluation of the policies within the hierarchy is discussed in detail in the section below.

Boolean policies

Boolean policies correspond to boolean constraints that are used to enable or disable a given service aspect. You would simple set Policy.enforced equal to True enforce the restriction.

Hierarchical evaluation

By default, a policy that you set at a resource replaces any policy set anywhere above it in the resource hierarchy. However, for a list constraint, if inherit_from_parent is set to true, then the values from the policy of the parent resource are inherited. This means the values set in the policy are effectively added to the values that came from further up the hierarchy.

Setting policy hierarchies that inherit both allowed values and denied values isn't recommended in most circumstances to keep the configuration simple and understandable. However, it is possible to set a policy that has allowed_values set that inherits a policy that has denied_values set. In this case, the values that are in allowed_values must not be present in denied_values.

For example, suppose you have a list constraint constraints/serviceuser.services. This is a list constraint that specifies the list of services that are allowed. The default for the constraint is set to ALLOW.

Suppose further that a policy derived from this constraint has been applied at the organization level. The policy restricts the allowed service activations to {compute.googleapis.com, datastore.googleapis.com}. If a policy is applied to a project under your organization specifying that inherit_from_parent is false and all_values set to DENY, then any attempt to activate the APIs compute.googleapis.com and datastore.googleapis.com (or any other API) will be denied.

Looking at some examples of hierarchical policy evaluation can help make this clear.

Examples of hierarchical evaluation

The following examples demonstrate different possible hierarchies and how the policies are evaluated.

Project with no inherited values

In our first example, let's look at a case where there are no inherited values. The organization has a policy with values:

{
  allowed_values: "compute.googleapis.com"
  allowed_values: "datastore.googleapis.com"
}

A project under this organization has the values:

{
  allowed_values: "dns.googleapis.com"
  allowed_values: "endpoints.googleapis.com"
  inherit_from_parent: false
}

In this case, the accepted values at the organization level are compute.googleapis.com, datastore.googleapis.com. The accepted values at the project level are dns.googleapis.com and endpoints.googleapis.com because the project is set to not inherit from the parent.

Project with inherited values

Now let's look at second example, in which a project inherits values.

As in the previous example, the organization has a policy with the values:

{
  allowed_values: "compute.googleapis.com"
  allowed_values: "datastore.googleapis.com"
}

And the project has the same values as before, except that now, inheritance is set to true:

{
  allowed_values: "dns.googleapis.com"
  allowed_values: "endpoints.googleapis.com"
  inherit_from_parent: true
}

In this case, the accepted values at the organization are compute.googleapis.com, datastore.googleapis.com. The accepted values at the project are compute.googleapis.com, datastore.googleapis.com, dns.googleapis.com, and endpoints.googleapis.com because the project is set to inherit from the parent.

Inheritance with allowed and denied values

Now let's look at a slightly more interesting case in which a project inherits allowed values and denies one of the inherited values.

Again our organization has a policy with values:

{
  allowed_values: "compute.googleapis.com"
  allowed_values: "datastore.googleapis.com"
}

The project has a policy applied that denies one of the values which was allowed at the organization level:

{
  denied_values: "compute.googleapis.com"
}

The accepted values at the organization are compute.googleapis.com, datastore.googleapis.com. The only value accepted at the project is datastore.googleapis.com.

Resetting with RestoreDefault

RestoreDefault enables you to reset a policy to the constraint's default setting.

For example, if the organization has a policy with the values:

 {
   allowed_values: "compute.googleapis.com"
   allowed_values: "datastore.googleapis.com"
 }

And the project has a policy with values:

 {
   RestoreDefault: {}
 }

The result is that the accepted values at the organization are compute.googleapis.com, datastore.googleapis.com, and the accepted values at the project are either all or none, depending on the default value of the constraint. If the constraint default is ALLOW, then all values are allowed. If the default is DENY, then none of the values are allowed.

Project with no policy

If a project has no policy, then the project will inherit the parent policy.

So if your organization has no policy set, and the project also has no policy set, then the accepted values at both levels depend on the constraint default. If the constraint default is ALLOW, then all values are allowed, and if the default is DENY, none are allowed.

If your organization has a policy set, then any project beneath it that has no policy set will inherit the policy from the organization.

Override restriction with universal ALLOW/DENY

Another example is where you have a list constraint that allows all values applied to a project that has an organization level policy with restricted values.

Here, your organization has a policy with the values:

 {
   allowed_values: "compute.googleapis.com"
   allowed_values: "datastore.googleapis.com"
 }

And the project has a policy with:

 {
   all: ALLOW
 }

In this case, the accepted values at the organization are constrained to compute.googleapis.com and datastore.googleapis.com but any value is accepted at the project. That is, the project level policy overrides the organization policy.

Similarly, as you might expect, a project can disallow any values that are allowed at the organization level. So, even if the organization has a policy with values:

 {
   allowed_values: "compute.googleapis.com"
   allowed_values: "datastore.googleapis.com"
 }

The project can set a policy with:

 {
   all: DENY
 }

The result is that the accepted values at the organization are compute.googleapis.com and datastore.googleapis.com, while no value is accepted at project level.

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Google Cloud Resource Manager Documentation