Restricting Resource Locations

Overview

This guide describes how to set an organization policy that includes the resource locations constraint.

You can limit the physical location of a new resource with the Organization Policy Service resource locations constraint. You can use the location property of a resource to identify where it is deployed and maintained by the service. For data-containing resources of some Google Cloud services, this property also reflects the location where data is stored. This constraint lets you define the allowed Google Cloud locations where the resources for supported services in your hierarchy can be created.

After you define resource locations, this limitation will apply only to newly-created resources. Resources you created before setting the resource locations constraint will continue to exist and perform their function.

A policy that includes this constraint won't be enforced on sub-resource creation for certain services, such as Cloud Storage and Dataproc.

Limitations

The resource locations Organization Policy Service constraint controls the ability to create resources for which a location can be selected. This constraint does not affect where global resources, such as Compute Engine global addresses, or resources that don't support selecting a location are created.

To avoid breaking existing serving infrastructure, you should test any new policy on non-production projects and folders, then apply the policy gradually within your organization.

For data storage commitments, see the Google Cloud Terms of Service and the Service Specific Terms . Organization policies that contain the resource locations constraint aren't data storage commitments.

This constraint applies to a specific subset of products and resource types. For a list of supported services and details on the behavior of each service, see the Resource Locations Supported Services page.

Location types

You can deploy Google Cloud resources in location types that represent different size categories. The largest location type is the multi-region , which includes more than one region . Each region is further subdivided into zones . For more information about regions and zones, see the Regions and Zones overview .

• Multi-region locations are backed by physical resources in more than one region and are typically only used by storage-based resources. Some examples include us , asia , europe , and global .

• Region locations are geographically isolated from each other. Some examples include us-west1 (Oregon), asia-northeast1 (Tokyo), and europe-west1 (Belgium).

• Zone locations are the most granular and isolated location type used for deploying resources. A zone is an independent failure domain within a region . Some examples are us-east1-b , us-west1-b , and asia-northeast1-a . Google Cloud also offers specialized AI zones that are tailored for AI and ML workloads—for example, us-central1-ai1a .

When setting up locations, you should use the in: prefix and a Value Group . Using a Value Group curated by Google Cloud lets you choose geographic location(s), without having to specify current or future Cloud locations.

The in: prefix to a Value Group specifies that all values that exist within the value group are considered to be part of the policy. If you enter a group value or a Google Cloud region without the prefix, the in: prefix will be automatically added, per these rules:

• If you enter a location that uses the in: prefix, and it contains any invalid group, the policy change will fail.
• If you enter a location that is a region, such as us-east1 , it will have the in: prefix prepended, to in:us-east1-locations in this example.
• If you enter a region or multi-region value group such as us-locations , it will have the in: prefix prepended, to in:us-locations in this example.
• If you enter a zone or multi-region such as us-east1-b or us , the values won't be changed.

Setting the organization policy

The resource locations constraint is a type of legacy managed constraint with list rules . You can add and remove locations from the allowed_values or denied_values lists of a resource locations constraint. To prevent organization policies from unexpectedly restricting service behavior as new locations are added to the available list, use a value group , or a list of allowed_values that represents the entire geographic boundary you want to define.

To set an organization policy including a resource locations constraint:

  name 
 : 
  
 organizations/ ORGANIZATION_ID 
/policies/gcp.resourceLocations 
 spec 
 : 
  
 rules 
 : 
  
 - 
  
 values 
 : 
  
 deniedValues 
 : 
  
 - 
  
 in:us-east1-locations 
  
 - 
  
 in:northamerica-northeast1-locations 
 

 gcloud  
org-policies  
set-policy  
 POLICY_PATH 
 

  name 
 : 
  
 organizations/01234567890/policies/gcp.resourceLocations 
 spec 
 : 
  
 rules 
 : 
  
 - 
  
 values 
 : 
  
 deniedValues 
 : 
  
 - 
  
 in:us-east1-locations 
  
 - 
  
 in:northamerica-northeast1-locations 
 

 curl  
-X  
POST  
-H  
 "Content-Type: application/json" 
  
-H  
 "Authorization: \ 
 Bearer 
 ${ 
 bearer_token 
 } 
 " 
  
-d  
 '{policy: {etag: "BwVtXec438Y=", constraint: \ 
 "constraints/gcp.resourceLocations", list_policy: {denied_values: \ 
 ["in:europe-locations", "in:southamerica-locations"] }}}' 
  
 \ 
https://cloudresourcemanager.googleapis.com/v1/organizations/123456789:setOrgPolicy 

  name 
 : 
  
 organizations/01234567890/policies/gcp.resourceLocations 
 spec 
 : 
  
 rules 
 : 
  
 - 
  
 values 
 : 
  
 deniedValues 
 : 
  
 - 
  
 in:europe-locations 
  
 - 
  
 in:southamerica-locations 
 

To learn about using constraints in organization policies, see Using Constraints .

Using inheritance in organization policy

You can refine your organization policy to inherit the organization policy from the resource's parent nodes. Inheritance gives you granular control over the organization policies used throughout your resource hierarchy.

To enable inheritance on a resource node, set inheritFromParent = true in the organization policy YAML file. For example:

  name 
 : 
  
 organizations/01234567890/policies/gcp.resourceLocations 
 spec 
 : 
  
 inheritFromParent 
 : 
  
 true 
  
 rules 
 : 
  
 - 
  
 values 
 : 
  
 deniedValues 
 : 
  
 - 
  
 in:us-west1 
 

Allow or deny VM creation in AI zones

You can allow or deny VMs from being created in AI zones by creating and enforcing a custom constraint in a custom organization policy.

An AI zone is identified with the string ai in its name. For example, us-west4-ai2b is an AI zone in the us-west4 region, and us-west4-b is the parent zone. When creating a custom constraint, use the string -ai in your condition. For more information about AI zones, see About AI zones .

For permissions required to manage organization policies, see Required roles in the Creating and managing custom constraints page.

To set a custom organization policy to allow or deny VMs from being created in AI zones, complete the following steps:

1. Create a custom constraint for AI zones

   Depending on whether you want to allow or deny VMs from being created in AI zones, create a YAML file with one of the following constraints.

   • To allow VMs to be created in AI zones only, use the following constraint:

       name 
      : 
       
      organizations/ ORGANIZATION_ID 
     /customConstraints/custom.allowOnlyAiZones 
      resource_types 
      : 
      - 
       
      compute.googleapis.com/Instance 
      method_types 
      : 
      - 
       
      CREATE 
      - 
       
      UPDATE 
      actionType 
      : 
       
      ALLOW 
      condition 
      : 
       
      "resource.zone.contains('-ai')" 
      displayName 
      : 
       
      allowOnlyAiZones 
      description 
      : 
       
      Allow VMs to be created in AI zones only. 
      
     

   • To deny VMs from being created in AI zones, use the following constraint:

       name 
      : 
       
      organizations/ ORGANIZATION_ID 
     /customConstraints/custom.denyAiZones 
      resource_types 
      : 
      - 
       
      compute.googleapis.com/Instance 
      method_types 
      : 
      - 
       
      CREATE 
      - 
       
      UPDATE 
      actionType 
      : 
       
      DENY 
      condition 
      : 
       
      "resource.zone.contains('-ai')" 
      displayName 
      : 
       
      denyAiZones 
      description 
      : 
       
      Deny VMs from being created in AI zones. 
      
     

     Replace ORGANIZATION_ID with your organization ID—for example, 01234567890 .

2. Set the custom constraint

   After you've created the YAML file for the custom constraint, you must set the custom constraint to make it available for organization policies.

   To set the custom constraint, use the gcloud org-policies set-custom-constraint command:

    gcloud  
   org-policies  
   set-custom-constraint  
    CONSTRAINT_PATH 
    
   

   Replace CONSTRAINT_PATH with the full path to your custom constraint YAML file—for example, /home/user/customconstraint.yaml .

3. Create an organization policy

   To create an organization policy that enforces the custom constraint, create a policy YAML file that references the constraint:

     name 
    : 
     
    projects/ PROJECT_ID 
   /policies/ CONSTRAINT_NAME 
    
    spec 
    : 
     
    rules 
    : 
     
    - 
     
    enforce 
    : 
     
    true 
    
   

   Replace the following:

   • PROJECT_ID : the project that you want to enforce your constraint on.

   • CONSTRAINT_NAME : the name of your custom constraint— custom.allowOnlyAiZones or custom.denyAiZones .

4. Enforce the custom organization policy on your project

   To enforce the organization policy containing the custom constraint, run the following command:

    gcloud  
   org-policies  
   set-policy  
    POLICY_PATH 
    
   

   Replace POLICY_PATH with the full path to your organization policy YAML file. Changes to organization policies can take up to 15 minutes to be fully enforced.

For more information about custom constraints, see Creating and managing custom constraints . For troubleshooting, see Troubleshooting custom constraints .

Example error message

Services that support the resource location constraint are prevented from creating new resources in locations that would violate the constraint. If a service attempts to create a resource in a location that violates the constraint, the attempt will fail and an error message will be generated.

This error message will have this format: LOCATION_IN_REQUEST violates constraint constraints/gcp.resourceLocations on the resource RESOURCE_TESTED .

In the following example, a Compute Engine resource fails to create a new instance due to policy enforcement:

 Location ZONE:us-east1-b violates constraint constraints/gcp.resourceLocations
on the resource
projects/policy-violation-test/zones/us-east1-b/instances/instance-3. 

Google Cloud Observability and Cloud Audit Logs log entry:

  { 
  
 i 
 nsert 
 Id 
 : 
  
 "5u759gdngec" 
  
 logName 
 : 
  
 "projects/policy-violation-test/logs/cloudaudit.googleapis.com%2Factivity" 
  
 pro 
 t 
 oPayload 
 : 
  
 { 
  
 @ 
 t 
 ype 
 : 
  
 "type.googleapis.com/google.cloud.audit.AuditLog" 
  
 au 
 t 
 he 
 nt 
 ica 
 t 
 io 
 n 
 I 
 nf 
 o 
 : 
  
 { 
 … 
 } 
  
 au 
 t 
 horiza 
 t 
 io 
 n 
 I 
 nf 
 o 
 : 
  
 [ 
 6 
 ] 
  
 me 
 t 
 hodName 
 : 
  
 "beta.compute.instances.insert" 
  
 reques 
 t 
 : 
  
 { 
 … 
 } 
  
 reques 
 t 
 Me 
 ta 
 da 
 ta 
 : 
  
 { 
 … 
 } 
  
 resourceLoca 
 t 
 io 
 n 
 : 
  
 { 
 … 
 } 
  
 resourceName 
 : 
  
 "projects/policy-violation-test/zones/us-east1-b/instances/instance-3" 
  
 respo 
 nse 
 : 
  
 { 
  
 @ 
 t 
 ype 
 : 
  
 "type.googleapis.com/error" 
  
 error 
 : 
  
 { 
  
 code 
 : 
  
 412 
  
 errors 
 : 
  
 [ 
  
 0 
 : 
  
 { 
  
 domai 
 n 
 : 
  
 "global" 
  
 loca 
 t 
 io 
 n 
 : 
  
 "If-Match" 
  
 loca 
 t 
 io 
 n 
 Type 
 : 
  
 "header" 
  
 message 
 : 
  
 "Location ZONE:us-east1-b violates constraint constraints/gcp.resourceLocations on the resource projects/policy-violation-test/zones/us-east1-b/instances/instance-3." 
  
 reaso 
 n 
 : 
  
 "conditionNotMet" 
  
 } 
  
 ] 
  
 message 
 : 
  
 "Location ZONE:us-east1-b violates constraint constraints/gcp.resourceLocations on the resource projects/policy-violation-test/zones/us-east1-b/instances/instance-3." 
  
 } 
  
 } 
  
 serviceName 
 : 
  
 "compute.googleapis.com" 
  
 s 
 tatus 
 : 
  
 { 
  
 code 
 : 
  
 3 
  
 message 
 : 
  
 "INVALID_ARGUMENT" 
  
 } 
  
 } 
  
 receiveTimes 
 ta 
 mp 
 : 
  
 "2019-06-14T03:04:23.660988360Z" 
  
 resource 
 : 
  
 { 
  
 labels 
 : 
  
 { 
 … 
 } 
  
 t 
 ype 
 : 
  
 "gce_instance" 
  
 } 
  
 severi 
 t 
 y 
 : 
  
 "ERROR" 
  
 t 
 imes 
 ta 
 mp 
 : 
  
 "2019-06-14T03:04:22.783Z" 
 } 
 

Vulnerability findings and remediation

The resource location constraint restricts the creation of resources at runtime. This feature helps to prevent location violations from occurring, but does not identify or remediate existing violations. You can use Security Health Analytics, a built-in service of Security Command Center, to discover location violations in your resource hierarchy. For more information, see Organization Policy vulnerability findings .

If there are Security Health Analytics findings of location violations, see Remediating Security Health Analytics findings for steps to remediate those findings.

Value groups

Value groups are collections of groups and locations that are curated by Google to provide a simple way to define your resource locations. Value groups include many related locations and are expanded over time by Google without needing to change your organization policy to accommodate the new locations.

To use value groups in your organization policy, prefix your entries with the string in: . For more information on using value prefixes, see Using Constraints . Group names are validated on the call to set the organization policy. Using an invalid group name will cause the policy setting to fail.

The following table contains the current list of available groups:

Authentication

Organization Policy Service uses OAuth 2.0 for API authentication and authorization. To get an OAuth 2.0 bearer token:

1. Go to the OAuth 2.0 Playground page .

2. In the Step 1list of scopes, select the Cloud Resource Manager API v2> https://www.googleapis.com/auth/cloud-platform, and then click Authorize APIs.

3. On the Sign in with Googlepage that appears, select your account and sign in.

4. To provide access to Google OAuth 2.0 Playground, click Allowon the prompt that appears.

5. In Step 2, click Exchange authorization code for tokens.

6. At the bottom of the Request / Responsepane on the right, your access token string is displayed:

     { 
     
    "access_token" 
    : 
     
    " ACCESS_TOKEN 
   " 
    , 
     
    "token_type" 
    : 
     
    "Bearer" 
    , 
     
    "expires_in" 
    : 
     
    3600 
    } 
    
   

   Where ACCESS_TOKEN is the OAuth 2.0 bearer token string that you can use for API authorization.