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.

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.

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 the 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.

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

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.