This page explains ingress and egress rules for VPC Service Controls. VPC Service Controls uses ingress and egress rules to allow access to and from the resources and clients protected by service perimeters.
The ingress and egress rule blocks specify the direction of allowed access to and from different identities and resources. Ingress and egress rules can replace and simplify use cases that previously required one or more perimeter bridges.
To learn how to apply ingress and egress policies to your service perimeter, see Configuring ingress and egress policies.
You can configure identity groups and third-party identities (Preview) in ingress and egress rules. For an example use case, see Example of using identity groups and third-party identities in ingress and egress rules.
For a list of secure data exchange use cases and samples, see Secure data exchange with ingress and egress rules.
For a list of context-aware access use cases and samples, see Context-aware access with ingress rules.
Benefits of ingress and egress rules
- Ingress and egress rules allow you to privately and efficiently exchange data within and across organizations using Google Cloud service APIs.
- Ingress and egress rules allow you to grant access to Google Cloud
resources in a perimeter based on the context of the API request:
- Constrain identity types or identities that can be used given a source network, IP address, or device.
- Constrain Google Cloud APIs and methods that can be accessed given the source network, IP address, device, and identity type.
- Minimize exfiltration risk by constraining the exact service, methods, Google Cloud projects, VPC networks, and identities used to execute the data exchange.
- Grant read-only access to external datasets and images that are not managed by you.
- Ensure that clients in less privileged segments do not have access to Google Cloud resources in more privileged segments; while allowing access in the other direction.
- Simplify configurations which have previously required one or more perimeter bridges.
Definition of ingress and egress
The definitions of ingress and egress are independent of the operation being invoked on the resource. Thus, the definitions refer to the direction of the request and not to the direction of data movement.
Ingress: Refers to any access by an API client from outside the service perimeter to resources within a service perimeter. Example:
- A Cloud Storage client outside a service perimeter calling Cloud Storage read, write, or copy operations on a Cloud Storage resource within the perimeter.
Egress Refers to any access that involves an API client or resources within the service perimeter and resources outside a service perimeter. Examples:
- A Compute Engine client within a service perimeter calling a
Compute Engine
create
operation where the image resource is outside the perimeter. - A Cloud Storage client – within or outside the perimeter – that calls a
copy
command where one bucket is within the perimeter and the other bucket is outside it.
- A Compute Engine client within a service perimeter calling a
Compute Engine
Policy model
An ingress or egress rule consists of from
and to
blocks where:
from
references the attributes of the API client.to
references the attributes of Google Cloud services and resources.
Multiple ingress and egress rules can be associated with a service perimeter. A Google Cloud service call is allowed or denied based on the following semantics:
- A request from a client outside the perimeter to a Google Cloud resource within the perimeter is allowed if the conditions of the necessary ingress rule are satisfied.
- A request from a client within the perimeter to a Google Cloud resource outside the perimeter is allowed if the conditions of the necessary egress rule are satisfied.
- An API call that involves a Google Cloud resource within the perimeter and a Google Cloud resource outside the perimeter is allowed if there is an ingress rule that the client satisfies (if the client is not within the perimeter), and an egress rule that the external resource satisfies.
Examples of API requests allowed by ingress rules
- A Cloud Storage client outside the perimeter downloading objects from a
Cloud Storage bucket inside the perimeter to the local machine (for example
using the
gcloud storage cp
command). - A BigQuery client outside the perimeter using a BigQuery job
in a project inside the perimeter to query a BigQuery dataset inside
the perimeter (for example using the
bq query
command). - A Compute Engine VM in a VPC network that is outside the perimeter writes to a Cloud Storage bucket inside the perimeter.
Examples of API requests allowed by egress rules
- A Cloud Storage client inside the perimeter copying objects between a
Cloud Storage bucket outside the perimeter and a bucket inside the
perimeter (for example using the
gcloud storage cp
command).
- A BigQuery client inside the perimeter using a BigQuery job
in a project outside the perimeter to query a BigQuery dataset inside
the perimeter (for example using the
bq query
command).
Examples of API requests allowed by combination of ingress and egress rules
- A Cloud Storage client outside the perimeter copying objects between a
Cloud Storage bucket outside the perimeter and a bucket inside the
perimeter (for example using the
gcloud storage cp
command). - A BigQuery client outside the perimeter using a BigQuery job
in a project outside the perimeter to query a BigQuery dataset inside
the perimeter (for example using the
bq query
command). - A Compute Engine client outside the perimeter creating a Compute Engine disk outside the perimeter using a Cloud KMS key inside the perimeter.
In the BigQuery and Compute Engine examples, an ingress rule is not sufficient, because the BigQuery job or the Compute Engine disk is outside the perimeter. An egress rule is required to allow an API request that involves a Google Cloud resource inside the perimeter (the BigQuery dataset or the Cloud KMS key) and a resource outside the perimeter (the BigQuery job or the Compute Engine disk).
API requests involving multiple service perimeters
When the accessed resources and/or the API client belong to different service
perimeters, the policies of all the involved perimeters must allow the API
request. For example, consider a Cloud Storage client and bucket a
within a
service perimeter A
and a bucket b
within a service perimeter B
. In this example, for the
Cloud Storage client to copy objects from the bucket a
to bucket b
and
from the bucket b
to bucket a
, the following ingress and egress rules are required:
- an egress rule in perimeter
A
to allow access to the Cloud Storage bucketb
, - an egress rule in perimeter
B
to allow access to the Cloud Storage bucketa
, - an ingress rule in perimeter
B
to allow access for the Cloud Storage client that is outside the perimeterB
.
Ingress rules reference
Ingress rules can be configured using the Google Cloud console,
a JSON file, or a YAML file. The following sample uses the .yaml
format:
- ingressFrom: identityType: ANY_IDENTITY | ANY_USER_ACCOUNT | ANY_SERVICE_ACCOUNT *OR* identities: - PRINCIPAL_IDENTIFIER sources: - resource: RESOURCE *OR* - accessLevel: ACCESS_LEVEL ingressTo: operations: - serviceName: SERVICE methodSelectors: - method: METHOD *OR* - permission: PERMISSION resources: - projects/PROJECT
- ingressFrom:
- (Required) Starts thefrom
block which lists allowed sources and identities outside the perimeter.identityType:
- (This attribute or theidentities
attribute must be used) This attribute defines the types of identities that can be used from the specifiedsources
(network origin). Acceptable values:ANY_IDENTITY
,ANY_USER_ACCOUNT
,ANY_SERVICE_ACCOUNT
.ANY_IDENTITY
allows all identities.ANY_USER_ACCOUNT
allows all human users.ANY_SERVICE_ACCOUNT
allows all service accounts.identities:
- (This attribute or theidentityType
attribute must be used) This attribute starts a list of service accounts, user accounts, Google groups, or third-party identities that can access resources in the perimeter.PRINCIPAL_IDENTIFIER
: Specify a user account, a service account, a Google group, or a third-party identity to which you want to provide access to resources in the perimeter. Use the format specified in IAMv1
API Principal identifiers. For example, use thegroup:GROUP_NAME@googlegroups.com
format to specify a Google group.VPC Service Controls supports only the
v1
identities that start with theuser
,serviceAccount
,group
(Preview), andprincipal
(Preview) prefixes in the IAMv1
API Principal identifiers.sources:
- (Required) This attribute refers to a list of network origins. Each value in the list is either an access level or a Google Cloud project. If you set theaccessLevel
attribute to"*"
, the ingress policy allows access from any network origin. If you set this attribute to a Google Cloud project, the ingress policy allows access from a VPC network that belongs to the project.This value might be removed when the associated project is permanently deleted. However, the removal of this value doesn't cause an error. Always check if this value exists while troubleshooting any issues.
- resource:
- (Use this attribute or theaccessLevel
attribute) Specifies a project or VPC network from outside the perimeter to which you want to provide access. To specify a project, use the following format:projects/PROJECT_NUMBER
. To specify a VPC network, use the following format://compute.googleapis.com/projects/PROJECT_ID/global/networks/NETWORK_NAME
.- accessLevel:
- (This attribute or theresource
attribute must be used) Specifies the access level from outside the perimeter to which access is given. If you set theaccessLevel
attribute to"*"
, the ingress policy allows access from any network origin.ingressTo:
- (Required) Starts theto
block which lists allowed service operations on specified Google Cloud resources within the perimeter.operations:
- (Required) Marks the beginning of the list of accessible services and actions/methods that a client satisfying thefrom
block conditions is allowed to access.- serviceName:
- (Required) This field can be a valid service name or be set to"*"
to allow access to all services. For example,bigquery.googleapis.com
is a validserviceName
. For a list of available services, see Supported products.methodSelectors:
- (Required ifserviceName
is not"*"
) The beginning of a list of methods that a client satisfying thefrom
block conditions is allowed to access. For a list of restrictable methods and permissions for services, see Supported service method restrictions.- method:
- (This attribute or thepermission
attribute must be used) This field can be a valid service method, or can be set to"*"
to allow access to all methods of the specified service.- permission:
- (This attribute or themethod
attribute must be used) This field must be a valid service permission. The access to the resources inside the perimeter are allowed for the operations that require the permission.When a request to a resource requires multiple permissions, you must specify all the required permissions under the same operation for the ingress rule to work. For example, if a request to a BigQuery resource requires the
bigquery.jobs.create
andbigquery.tables.create
permissions, you must specify both these permissions under the same operation. Also, if you specify the permissions multiple times for the same resource by using the Google Cloud console, the permissions are not created under the same operation. To avoid this issue, specify all the permissions at once for the resource.resources:
- (Required) This attribute specifies the list of Google Cloud resources in the Service Perimeter that the client outside the perimeter can access. This field can be set to"*"
to allow ingress access to any Google Cloud resource inside the perimeter.
To make a functional ingress rule, you must specify the following attributes:
sources
attribute. You must specify anaccessLevel
or aresource
(Google Cloud project or VPC network), or setaccessLevel
attribute to"*"
.
identityType
oridentities
attributeresources
attributeserviceName
attribute
Once you have finished configuring your ingress policy file, see Updating ingress and egress policies for instructions on applying your ingress policy file to your service perimeter.
If you configure multiple ingress rules in a service perimeter, VPC Service Controls allows a request if it satisfies the conditions of any one of the ingress rules.
Egress rules reference
Egress rules can be configured using the Google Cloud console,
a JSON file, or a YAML file. The following sample uses the .yaml
format:
- egressTo: operations: - serviceName: SERVICE_NAME methodSelectors: - method: METHOD *OR* - permission: PERMISSION resources: - projects/PROJECT *OR* externalResources: - EXTERNAL_RESOURCE_PATH egressFrom: identityType: ANY_IDENTITY | ANY_USER_ACCOUNT | ANY_SERVICE_ACCOUNT *OR* identities: - PRINCIPAL_IDENTIFIER
- egressTo:
- (Required) Starts theto
block which lists allowed service operations on Google Cloud resources in specified projects outside the perimeter.operations:
- (Required) Marks the beginning of the list of accessible services and actions/methods that a client satisfying thefrom
block conditions is allowed to access.- serviceName:
- (Required) This field can be a valid service name or be set to"*"
to allow access to all services. For a list of available services, see Supported products.methodSelectors:
- (Required ifserviceName
is not"*"
) The beginning of a list of methods that a client satisfying thefrom
block conditions is allowed to access. For a list of restrictable methods and permissions for services, see Supported service method restrictions.- method:
- (This attribute or thepermission
attribute must be used.) This field can be a valid service method, or can be set to"*"
to allow access to all methods of the specified service.- permission:
- (This attribute or themethod
attribute must be used.) This field must be a valid service permission. The access to the specified resources outside the perimeter are allowed for the operations that require the this permission.When a request to a resource requires multiple permissions, you must specify all the required permissions under the same operation for the egress rule to work. For example, if a request to a BigQuery resource requires the
bigquery.jobs.create
andbigquery.tables.create
permissions, you must specify both these permissions under the same operation. Also, if you specify the permissions multiple times for the same resource by using the Google Cloud console, the permissions are not created under the same operation. To avoid this issue, specify all the permissions at once for the resource.resources:
- This attribute is a list of Google Cloud resources specified by their projects that clients inside a perimeter can access. You can set this field to"*"
to allow egress access to any Google Cloud resource.externalResources:
- This attribute is used only to specify BigQuery Omni resources. This attribute is a list of external resources supported by BigQuery Omni that clients inside a perimeter can access. You can specify only Amazon S3 or Azure Blob Storage resources. For Amazon S3, the supported format iss3://BUCKET_NAME
. For Azure Storage, the supported format isazure://myaccount.blob.core.windows.net/CONTAINER_NAME
.egressFrom:
- (Required) Starts thefrom
block that lists allowed sources and identities within the perimeter.identityType:
- (This attribute or theidentities
attribute must be used.) This attribute defines the types of identities that can be used to access the specified resources outside the perimeter. Acceptable values:ANY_IDENTITY
,ANY_USER_ACCOUNT
,ANY_SERVICE_ACCOUNT
.ANY_IDENTITY
allows all identities.ANY_USER_ACCOUNT
allows all human users.ANY_SERVICE_ACCOUNT
allows all service accounts.identities:
- (This attribute or theidentityType
attribute must be used.) This attribute starts a list of service accounts, user accounts, Google groups, or third-party identities that can access the specified resources outside the perimeter.PRINCIPAL_IDENTIFIER
: Specify a user account, a service account, a Google group, or a third-party identity that can access the specified resources outside the perimeter. Use the format specified in IAMv1
API Principal identifiers. For example, use thegroup:GROUP_NAME@googlegroups.com
format to specify a Google group.VPC Service Controls supports only the
v1
identities that start with theuser
,serviceAccount
,group
(Preview), andprincipal
(Preview) prefixes in the IAMv1
API Principal identifiers.
Once you have finished configuring your egress policy file, see Updating ingress and egress policies for instructions on applying your egress policy file to your service perimeter.
If you configure multiple egress rules in a service perimeter, VPC Service Controls allows a request if it satisfies the conditions of any one of the egress rules.
Using dry-run mode to test ingress/egress policies
When you don't want to grant access to all methods of a service, it can sometimes be difficult to determine the precise list of methods to allow. This can occur because a given method for a service can cause a different method to be invoked on a separate Google Cloud service. For example, BigQuery loading a table from a Cloud Storage bucket to run a query.
To determine the correct set of methods to allow, you can use the VPC Service Controls Dry-run mode. Do this by first enabling a perimeter in dry-run mode with no ingress or egress policies, and collect the list of methods invoked from the audit log. Then, progressively add these methods to ingress/egress policies in the dry-run mode until all violations have ceased. At that point, the configuration can be moved from dry-run mode to enforced mode.
Unsupported features
The following features are currently unsupported for ingress and egress rules:
- Identifying Google Cloud resources by labels instead of projects.
- Not all services support per-method ingress/egress rules. See Supported service method restrictions.
ANY_SERVICE_ACCOUNT
andANY_USER_ACCOUNT
identity types cannot be used to allow the following operations:- All Container Registry operations.
- All notebooks.googleapis.com service operations.
- Cloud Storage operations using Signed URLs.
- With Cloud Run functions, deployment of a Cloud Function from the local machine.
- Export logs from a Cloud Logging sink to a Cloud Storage resource.
- All Apache Airflow web user interface operations in Cloud Composer.
Limitations
For information about ingress and egress limits, see Quotas and limits.
What's next
- Complete this codelab to learn how to fix ingress and egress violations.