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 allows
you to 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 will not 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 do not 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
.
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
will not be changed.
Setting the organization policy
The resource locations constraint is a type of
list constraint
.
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:
Console
In the Google Cloud console, go to the
Organization policies
page.
Go to Organization policies
From the project picker, select the organization, folder, or project for
which you want to set the organization policy.
Select the
Google Cloud Platform - Resource Location Restriction
constraint to open its
Policy details
page.
Click
Manage policy
.
On the
Edit policy
page, select
Override parent's policy
.
Under
Policy enforcement
, select
Replace
.
Click
Add rule
.
Under
Policy values
, select
Custom
.
Under
Policy type
, select
Allow
to create a list of allowed
locations, or select
Deny
to create a list of denied locations.
In the
Policy value
box, enter the
in
prefix and a
value group
location string, then press
Enter
.
For example,
in:us-locations
or
in:us-west1-locations
. You can
enter multiple location strings by clicking
New policy value
.
You can also enter specific zone, region, or multi-region locations as
location strings. For a list of available locations, see the
Resource Locations Supported Services
page.
To enforce the policy, click
Set policy
.
gcloud
To create an organization policy that enforces the resource locations
constraint, create a policy YAML file that references the constraint:
constraint: constraints/gcp.resourceLocations
listPolicy:
deniedValues:
- in:us-east1-locations
- in:northamerica-northeast1-locations
To enforce the organization policy containing the constraint, run the
following command:
gcloud org-policies set-policy \
--organization '
ORGANIZATION_ID
' \
POLICY_PATH
Replace the following:
- ORGANIZATION_ID
: your
organization ID, such as 01234567890.
- POLICY_PATH
: the full path to the YAML file containing the
organization policy.
A response will be returned with the results of the new organization
policy:
name: organizations/01234567890/policies/gcp.resourceLocations
spec:
rules:
- values:
allowedValues:
- in:us-east1-locations
- in:northamerica-northeast1-locations
You can also enter specific zone, region, or multi-region locations as
location strings. For a list of available locations, see the
Resource Locations Supported Services
page.
API
You can use the Resource Manager API to set an organization policy on a
resource. You will need an
OAuth 2.0
bearer token for
authentication and authorization.
To set an organization policy using the resource locations constraint:
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
A response will be returned with the results of the new organization policy:
name: organizations/01234567890/policies/gcp.resourceLocations
spec:
rules:
- values:
deniedValues:
- in:europe-locations
- in:southamerica-locations
You can also enter specific zone, region, or multi-region locations as
location strings. For a list of available locations, see the
Resource Locations Supported Services
page.
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
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:
{
insertId: "5u759gdngec"
logName: "projects/policy-violation-test/logs/cloudaudit.googleapis.com%2Factivity"
protoPayload: {
@type: "type.googleapis.com/google.cloud.audit.AuditLog"
authenticationInfo: {…}
authorizationInfo: [6]
methodName: "beta.compute.instances.insert"
request: {…}
requestMetadata: {…}
resourceLocation: {…}
resourceName: "projects/policy-violation-test/zones/us-east1-b/instances/instance-3"
response: {
@type: "type.googleapis.com/error"
error: {
code: 412
errors: [
0: {
domain: "global"
location: "If-Match"
locationType: "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."
reason: "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"
status: {
code: 3
message: "INVALID_ARGUMENT"
}
}
receiveTimestamp: "2019-06-14T03:04:23.660988360Z"
resource: {
labels: {…}
type: "gce_instance"
}
severity: "ERROR"
timestamp: "2019-06-14T03:04:22.783Z"
}
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 not
validated on the call to set the organization policy. If the group name
provided does not exist, no new values will be added to the effective
organization policy, unless that group name is created by Google later.
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:
Go to the
OAuth 2.0 Playground page
.
In the
Step 1
list of scopes, select the
Cloud Resource Manager API v2
>
https://www.googleapis.com/auth/cloud-platform
,
and then click
Authorize APIs
.
On the
Sign in with Google
page that appears, select your account and sign
in.
To provide access to
Google Oauth 2.0 Playground
, click
Allow
on the
prompt that appears.
In
Step 2
, click
Exchange authorization code for tokens
.
At the bottom of the
Request / Response
pane 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.