Setting an organization policy with tags

Tags provides a way to conditionally allow or deny policies based on whether a resource has a specific tag. You can use tags and conditional enforcement of organization policies to provide centralized control of the resources in your hierarchy.

Before you begin

For more information about what tags are and how they work, see the Tags overview.

For detailed instructions about how to use tags, see Creating and managing tags.

Setting an organization policy with tags

To use tags to determine where an organization policy should take effect, you must specify a condition in the organization policy YAML file. You can set the condition to match a particular tag key-value pair, requiring that a particular tag value is set for the organization policy to be enforced.

Most organization policies are evaluated and enforced when a resource is created or updated. It's not possible to attach a tag to a resource before it is created, so conditional organization policies can't evaluate tags on a resource as it is created, only on tags that are inherited from parent resources.

Tags are evaluated for organization, folder, and project resources. Most resources below projects in the resource hierarchy are not evaluated by organization policy, with certain exceptions, such as Cloud Run services. For information about particular organization policy constraints, see Organization policy constraints.

List policy example

The following example demonstrates how to set an organization policy file that enforces the gcp.resourceLocations constraint. This organization policy uses both conditional and unconditional values, set within the same policy file.

Console

To set the organization policy, do the following:

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

Go to Organization policies
From the project picker, select the project for which you want to set the organization policy.
On the Organization policies page, select a constraint from the list. The Policy details page for that constraint appears.
To update the organization policy for this resource, click Manage policy.
On the Edit policy page, select Override parent's policy.
Under Policy enforcement, select an enforcement option:
- To merge and evaluate your organization policies together, select Merge with parent. For more information about inheritance and the resource hierarchy, see Understanding Hierarchy Evaluation.
- To override policies inherited from a parent resource, select Replace.
Click Add rule.
Under Policy values, select whether this organization policy should allow all values, deny all values, or specify a custom set of values.
- Specific values accepted by the policy depend on the service to which the policy applies. For a list of constraints and the values they accept, see Organization policy constraints.
Optionally, to make the organization policy conditional on a tag, click Add condition.
1. In the Title field, enter a name for the condition.
2. In the Description field, give your condition a description. The description provides context on the tags that are required and how they impact resources.
3. You can use the Condition builder to create a condition that requires a particular tag for the constraint to take effect.
  1. In the Condition type box, select Tag.
  2. Select the Operator for your condition. To match an entire tag, use the matches operator. To match a tag key and a tag value, use the matches ID operator.
  3. If you selected the matches operator, enter the value namespaced name of the tag. If you selected the matches ID operator, enter the key and value IDs.
  4. You can create multiple conditions by clicking Add. If you add another condition, you can set the conditional logic to require all of them by toggling And. You can set the conditional logic to require only one of the conditions to be true by toggling Or.
  5. You can delete an expression by clicking the large X to the right of the condition fields.
  6. When you have finished editing your conditions, click Save.
  The following figure shows an example configuration of an organization policy that includes conditions.
4. The Condition editor can be used to create a conditional expression programmatically. It will also display a programmatic rendering of your current set of conditions.
  1. You can use the Condition editor to apply the ! logical operator. For example, the query !resource.matchTag('ORGANIZATION_ID/location', 'us-west1') would apply the organization policy constraint to any resource that does not have the us-west1 tag.
  Warning: If you create a query that includes the ! logical operator in the Condition editor, the Condition builder displays an error message and is not able to render the query. The query will function, but you must use the Condition editor to make any further changes to the query.
To enforce the policy, click Set policy.

gcloud

To set the organization policy, run the following command:

gcloud org-policies set-policy POLICY_PATH

Where POLICY_PATH is the full path to your organization policy JSON file, which should look like the following:

{
  "name":"RESOURCE_TYPE/RESOURCE_ID/policies/gcp.resourceLocations",
  "spec":{
    "rules":[
       {
        // As there is no condition specified, this allowedValue is enforced
        // unconditionally.
        "values":{
          "allowedValues": ["us-east1-locations"]
        },
      },
     {
        // This condition applies to the values block.
        "condition":{
          "expression":"resource.matchTag('ORGANIZATION_ID/location', 'us-west1')"
        },
        "values":{
          "allowedValues": ["us-west1-locations"]
        }
      }
    ]
  }
}

Where:

RESOURCE_TYPE is organizations, folders or projects.
RESOURCE_ID is your organization ID, folder ID, project ID, or project number, depending on the type of resource specified in RESOURCE_TYPE.
ORGANIZATION_ID is the parent organization of your tag key.

For the above organization policy, the resource and all of its child resources will have the gcp.resourceLocations constraint enforced against them, with allowedValues of us-east1-locations only. Any of these resources that have the tag location: us-west1 will have the gcp.resourceLocations constraint enforced against it, with allowedValues of us-east1-locations and us-west1-locations.

In this way, both conditional and unconditional sets of values can be enforced for a constraint in a single organization policy.

Boolean policy example

The following example demonstrates how to set an organization policy file that enforces the compute.disableSerialPortAccess constraint. This organization policy specifies that all serial ports are accessible to resources, but uses a condition to only restrict serial port access to resources that have the matching tag.

Console

To set the organization policy, do the following:

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

Go to Organization policies
From the project picker, select the project for which you want to set the organization policy.
Select a constraint from the list on the Organization policies page. The Policy details page for that constraint should appear.
To update the organization policy for this resource, click Manage policy.
On the Edit policy page, select Override parent's policy.
Click Add rule.
Under Enforcement, select whether enforcement of this organization policy should be on or off.
Optionally, to make the organization policy conditional on a tag, click Add condition. Note that if you add a conditional rule to an organization policy, you must add only one unconditional rule or the policy cannot be saved.
1. In the Title field, enter a name for the condition.
2. In the Description field, give your condition a description. The description provides context on the tags that are required and how they impact resources.
3. You can use the Condition builder to create a condition that requires a particular tag for the constraint to take effect.
  1. In the Condition type box, select Tag.
  2. Select the Operator for your condition. To match an entire tag, use the matches operator. To match a tag key and a tag value, use the matches ID operator.
  3. If you selected the matches operator, enter the value namespaced name of the tag. If you selected the matches ID operator, enter the key and value IDs.
  4. You can create multiple conditions by clicking Add. If you add another condition, you can set the conditional logic to require all of them by toggling And. You can set the conditional logic to require only one of the conditions to be true by toggling Or.
  5. You can delete an expression by clicking the large X to the right of the condition fields.
  6. When you have finished editing your conditions, click Save.
  7. An organization policy with a condition enforced must have only one unconditional rule. Click Add rule, and set whether enforcement of this organization policy should default to on or off.
  The following figure shows an example configuration of an organization policy that includes conditions.
4. The Condition editor can be used to create a conditional expression programmatically. It will also display a programmatic rendering of your current set of conditions.
  1. You can use the Condition editor to apply the ! logical operator. For example, the query !resource.matchTag('ORGANIZATION_ID/location', 'us-west1') would apply the organization policy constraint to any resource that does not have the us-west1 tag.
  Warning: If you create a query that includes the ! logical operator in the Condition editor, the Condition builder displays an error message and is not able to render the query. The query will function, but you must use the Condition editor to make any further changes to the query.
To finish and apply the organization policy, click Save.

gcloud

To set the organization policy, run the following command:

gcloud org-policies set-policy POLICY_PATH

Where POLICY_PATH is the full path to your organization policy JSON file, which should look like the following:

{
  "name": "RESOURCE_TYPE/RESOURCE_ID/policies/gcp.disableSerialPortAccess",
  "spec": {
    "rules": [
      {
        "condition": {
          "expression": "resource.matchTag(\"ORGANIZATION_ID/disableSerialAccess\", \"yes\")"
        },
        "enforce": true
      },
      {
        "enforce": false
      }
    ]
  }
}

Where:

RESOURCE_TYPE is organizations, folders or projects.
RESOURCE_ID is your organization ID, folder ID, project ID, or project number.
ORGANIZATION_ID is the parent organization of your tag key.

For the above organization policy, the resource and all of its child resources will have the gcp.disableSerialPortAccess constraint enforced against them. Any resources that have the tag disableSerialAccess: yes will be denied by the organization policy. Any resource that does not have the tag disableSerialAccess: yes will not have the constraint enforced against them.

Conditionally add constraints to organization policy

You can use tags to conditionally add organization policy constraints to resources based on the tags they have attached. You can add multiple conditions within the same organization policy, which gives you fine-grained control of the resources to which you want the organization policy to apply.

Common Expression Language, or CEL, is the expression language used to specify conditional expressions. A conditional expression consists of one or more statements that are joined using logical operators (&&, ||, or !). For more information, see the CEL spec and its language definition.

Consider an organization policy to restrict the locations in which resources could be created based on the tags applied to those resources. To do this, create an organization policy that enforces the gcp.resourceLocations constraint, and use conditions to narrow enforcement to only certain resources.

Start by creating a temporary file, /tmp/policy.yaml, to contain your organization policy:

name: organizations/ORGANIZATION_ID/policies/gcp.resourceLocations
spec:
    rules:
    - condition:
        expression: "resource.matchTag('ORGANIZATION_ID/location', 'us-east')"
      values:
        allowedValues:
        - in:us-east1-locations
    - condition:
        expression: "resource.matchTag('ORGANIZATION_ID/location', 'us-west')"
      values:
        allowedValues:
        - in:us-west1-locations
    - values:
        deniedValues:
        - in:asia-south1-locations

Where ORGANIZATION_ID is the parent organization of your tag key.

In the above example, any resource that has the location: us-east tag attached will be restricted to locations within the us-east1-locations value group. Any resource that has the location: us-west tag attached will be restricted to locations within the us-west1-locations value group. All resources in the organization will be blocked from locations within the asia-south1-locations value group.

Then, set the policy using the set-policy command:

gcloud org-policies set-policy /tmp/policy.yaml

Restricting untagged resources

You can use tags and conditional organization policies to restrict any resources that are not using a particular tag. If you set an organization policy on a resource that restricts services and make it conditional on the presence of a tag, no child resources descended from that resource can be used unless they have been tagged. In this way, resources must be set up in accordance with your governance plan before they can be used.

To restrict untagged organization, folder, or project resources, you can use the ! logical operator in a conditional query when creating your organization policy.

For example, to allow the usage of sqladmin.googleapis.com only in projects that have the tag sqladmin=enabled, you can create an organization policy that denies sqladmin.googleapis.com on projects that do not have the tag sqladmin=enabled.

Create a tag that identifies whether the resources have had proper governance applied. For example, you could create a tag with the key sqlAdmin and the value enabled, to designate that this resource should allow the usage of the Cloud SQL Admin API. For example:
Click on the name of the newly created tag. You need the namespaced name of the tag key, listed under Tag key path, in the next steps to create a condition.
Create a Restrict Resource Service Usage organization policy at the level of your organization resource to deny access to the Cloud SQL Admin API. For example:
Add a condition to the above organization policy, specifying that the policy is enforced if the governance tag is not present. The logical NOT operator is not supported by the condition builder, so this condition must be built in the condition editor. For example:

!resource.matchTag("012345678901/sqlAdmin", "enabled")

Now, the sqlAdmin=enabled tag must be attached to or inherited by a project, before your developers can use the Cloud SQL Admin API with that project.

Organization policy inheritance

Organization policy List constraints that are enabled using tags will merge with the existing organization policy, per normal rules of inheritance. These conditional rules will only apply if the condition is true.

Organization policy Boolean constraints that are enabled using tags will override the existing organization policy. In addition, since boolean policies can only have two states, true or false, then all conditional statements must be the opposite of the non-condition statement to prevent multiple tags from conflicting with each other.

For example, consider an organization policy that enforces the disableSerialPortAccess constraint. The unconditional value, which is the value that is used if no conditions override it, is true. Therefore any other conditional statements for this policy must be set to false to not conflict.

What's next

For more information about how to use tags, read the Creating and managing tags page.

For more information about how to create and manage organization policy constraints, see Using constraints.