Stay organized with collections
Save and categorize content based on your preferences.
Connect to a VPC network
We recommend using Direct VPC egress to
send traffic to a VPC network—with no connector required.
However, if Direct VPC egress isn't an option for you, you can configure a Serverless VPC Access
connector instead. This page shows you how to connect a
Cloud Run service or job to your VPC network with a
connector, allowing egress (outbound) traffic from Cloud Run to
Compute Engine VM instances, Memorystore instances, and any other
resources with an internal IP address.
Before you begin
If you don't already have a VPC network in your project,
create one.
If you use Shared VPC, see the documentation that specifically covers
configuration of Serverless VPC Access for your product.
If you have an organizational policy constraint that prevents the use of
Cloud Deployment Manager, you won't be able to create or delete
Serverless VPC Access connectors. Creating or deleting a
connector requires Deployment Manager functionality.
If you have a trusted image policy
set up for your project, make sure to allow the serverless-vpc-access-images
project in the constraints/compute.trustedimageProjects organization policy.
Connector subnet requirements
Each connector requires its own dedicated, PRIVATE-purpose subnet with a /28 primary IPv4
address range. This subnet cannot be used by other resources, such as VMs,
Private Service Connect, or load balancers. After creating the connector,
the subnet cannot be expanded. It must stay as a /28.
To create a connector in a service project that uses a Shared VPC network
in a host project, a network administrator for the Shared VPC network must
manually create the connector's subnet before you can create the connector.
To determine if an existing, manually created subnet can be used by a connector, describe
the subnet:
Replace SUBNET with the subnet's name and REGION
with the region that contains the subnet.
In the output, verify the following:
The subnet is a regular subnet. In the Google Cloud CLI, this means that
the value for purpose is PRIVATE.
The subnet's primary IPv4 address range, ipCidrRange, is a /28.
If you need to create a Serverless VPC Access connector in the same project that contains
the VPC network used by the connector, you can either manually create the connector's subnet
before creating the connector, or Google Cloud can create the subnet for the connector automatically.
When Google Cloud creates a subnet for a connector, note the following:
Automatically created subnets for connectors aren't visible when you
list subnets,
regardless of whether you use the Google Cloud console, the Google Cloud CLI, or the
Compute Engine API.
Automatically created subnets for connectors cannot be
described.
Automatically created subnets are included in the list of subnets that
is presented when you describe a VPC
network.
For more information about subnets, including how to list existing ones to determine which IP address
ranges are already used, see Work with subnets.
Limitations
IPv6 traffic is not supported.
Creating Serverless VPC Access connectors in the asia-southeast3 region is not supported.
Create a connector
To send requests to your VPC network and receive the
corresponding responses without using the public internet, you can use a
Serverless VPC Access connector.
If your connector is located in the same project as its VPC
network, you can either create a connector using an existing subnet or create
a connector and a new subnet.
If your connector is located in a service project and uses a Shared VPC
network, the connector and its associated VPC network are in
different projects. When a connector and its VPC network are in
different projects, a Shared VPC network administrator must create the
connector's subnet in the Shared VPC network before you can create the
connector, and you must create the connector using an existing subnet.
Configure your serverless environment to use a connector
After you create a Serverless VPC Access connector,
configure your serverless environment to use the connector by following the
instructions for your serverless environment:
When you create a new service
or deploy a new revision, you can configure the
service to use a connector by using the Google Cloud console, Google Cloud CLI,
a YAML file, or a Terraform resource.
Select Services from the Cloud Run navigation menu, and click
Deploy container to configure a new service.
If you are configuring an existing service, click the
service, then click Edit and deploy new revision.
If you are configuring a new service, fill out the initial service
settings page, then click Containers, Networking, Security to expand the
service configuration page.
Click the Connections tab.
In the VPC Connector field, select a connector to use or select None to disconnect your service from a VPC network.
Click Create or Deploy.
gcloud
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a
Cloud Shell
session starts and displays a command-line prompt. Cloud Shell is a shell environment
with the Google Cloud CLI
already installed and with values already set for
your current project. It can take a few seconds for the session to initialize.
Replace CONNECTOR_NAME with the name of your
connector. If your connector is in the host project of a
Shared VPC, this must be the fully specified name, for example:
where HOST_PROJECT_ID is the ID of the host project,
CONNECTOR_REGION is the region of your connector, and
CONNECTOR_NAME is the name that you gave your connector.
To attach, update, or remove a connector for an existing service, use the
gcloud run services update
command with either of the following flags as needed:
Replace SERVICE with the name of your
Cloud Run service.
Replace CONNECTOR_NAME with the name of your
connector. If your connector is in the host project of a
Shared VPC, this must be the fully specified name, for example:
where HOST_PROJECT_ID is the ID of the host project,
CONNECTOR_REGION is the region of your connector, and
CONNECTOR_NAME is the name that you gave your connector.
Replace the service with its new configuration using the following command:
gcloudbetarunservicesreplaceservice.yaml
Terraform
You can use a Terraform resource to create a service and configure it to use your connector.
# Cloud Run service
resource "google_cloud_run_v2_service" "gcr_service" {
name = "mygcrservice"
location = "us-west1"
deletion_protection = false # set to "true" in production
template {
containers {
image = "us-docker.pkg.dev/cloudrun/container/hello"
resources {
limits = {
cpu = "1000m"
memory = "512Mi"
}
}
# the service uses this SA to call other Google Cloud APIs
# service_account_name = myservice_runtime_sa
}
scaling {
# Limit scale up to prevent any cost blow outs!
max_instance_count = 5
}
vpc_access {
# Use the VPC Connector
connector = google_vpc_access_connector.connector.id
# all egress from the service should go through the VPC Connector
egress = "ALL_TRAFFIC"
}
}
}
Configure Cloud Run functions to use a connector
You can configure a function to use a connector from the Google Cloud console
or the Google Cloud CLI:
However, if you create a connector in a service project and the connector targets
a Shared VPC network in the host project, you must add firewall rules
to allow necessary traffic for the connector's operation from the following
ranges:
These ranges are used by the Google infrastructure underlying
Cloud Run, Cloud Run functions, and App Engine standard environment. All requests from
these IP addresses originate from Google infrastructure to make sure
that each serverless resource only communicates with the
connector that it's connected to.
You must also allow traffic from the connector's subnet to resources in your
VPC network.
To perform these steps, you must have one of the following roles on the
host project:
For a basic configuration, apply the rules to allow serverless resources in any
service project connected to the Shared VPC network to send requests to
any resource in the network.
To apply these rules, run the following commands in the host project:
Create firewall rules that allow requests from Google's serverless
infrastructure and health check probes to reach all connectors in the
network. In these commands, UDP and TCP ports are used as proxies and for
HTTP health checks, respectively. Don't change the specified ports.
This rule gives the connector access to every resource in the network. To
limit the resources that your serverless environment can reach by using
Serverless VPC Access, see
Restrict connector VM access to VPC network resources.
Create firewall rules for specific connectors
Following the procedure in
Required firewall rules for connectors in service projects
results in firewall rules that apply to all connectors, both current ones
and ones created in the future. If you don't want this, but instead want to
create rules for specific connectors only, you can scope the rules so that
they apply only to those connectors.
To limit the scope of the rules to specific connectors, you can use one of the
following mechanisms:
Network tags: Every connector has two network tags: vpc-connector and
vpc-connector-REGION-CONNECTOR_NAME.
Use the latter format to limit the scope of your firewall rules to a specific
connector.
IP ranges: Use this for the egress rules only, because it doesn't work for
ingress rules. You can use the IP range of the connector
subnet to limit the scope of your firewall rules to a single VPC
connector.
Restrict connector VM access to VPC network resources
You can restrict your connector's access to resources in its target
VPC network by using VPC firewall
rules or rules in firewall
policies. You can accomplish these
restrictions using one of the following strategies:
Create ingress rules whose targets represent the resources that you want
to limit connector VM access to and whose sources represent the connector VMs.
Create egress rules whose targets represent the connector VMs and whose
destinations represent the resources that you want to limit connector VM
access to.
The following examples illustrate each strategy.
Restrict access using ingress rules
Choose either network tags or
CIDR ranges to control the incoming traffic to your VPC network.
Create an egress firewall rule on your Serverless VPC Access
connector to prevent it from sending outgoing traffic, with the exception of
established responses, to any destination.
RULE_NAME: the name of your new firewall rule. For example,
deny-vpc-connector.
PROTOCOL: one or more protocols that you want to allow from your
VPC connector. Supported protocols are tcp or udp. For example, tcp:80,udp
allows TCP traffic through port 80 and UDP traffic. For more information, see
the documentation for the allow
flag.
For security and validation purposes, you can also
configure deny rules to block traffic for the following unsupported
protocols:
ah, all, esp, icmp, ipip, and sctp.
VPC_CONNECTOR_NETWORK_TAG: the universal VPC
connector network tag if you want the rule to apply to all existing
VPC connectors and any VPC connectors made
in the future. Or, the unique VPC connector network tag
if you want to control a specific connector.
VPC_NETWORK: the name of your VPC network
PRIORITY: an integer between 0-65535. For example, 0 sets the
highest priority.
Allow egress traffic when the destination is in the CIDR range that you want
your connector to access.
Use the allow and destination-ranges flags to create a firewall rule
allowing egress traffic from your connector for a specific destination range.
Set the destination range to the CIDR range of the resource in your
VPC network that you want your connector to be able to access.
Set the priority for this rule to be a lower value than the priority of the
rule you made in the previous step.
RULE_NAME: the name of your new firewall rule. For example,
allow-vpc-connector-for-select-resources.
PROTOCOL: one or more protocols that you want to allow from your
VPC connector. Supported protocols are tcp or udp. For example, tcp:80,udp
allows TCP traffic through port 80 and UDP traffic. For more information, see
the documentation for the allow
flag.
RESOURCE_CIDR_RANGE: the CIDR range for the connector whose
access you are restricting
VPC_NETWORK: the name of your VPC network
VPC_CONNECTOR_NETWORK_TAG: the universal VPC
connector network tag if you want the rule to apply to all existing
VPC connectors and any VPC connectors made
in the future. Or, the unique VPC connector network tag
if you want to control a specific connector. If you used the unique
network tag in the previous step, use the unique network tag.
PRIORITY: an integer less than the priority you set in
the previous step. For example, if you set the priority for the rule
you created in the previous step to 990, try 980.
Monitoring usage over time can help you determine when to adjust a connector's
settings. For example, if CPU utilization spikes, you might try increasing
the maximum number of instances for better results. Or if you are maxing out
throughput, you might decide to switch to a larger machine type.
To display charts for the connector's throughput, number of instances, and CPU
utilization metrics over time by using the Google Cloud console:
Click the name of the connector you want to monitor.
Select the number of days you want to display between 1 and 90 days.
In the Throughput chart, hold the pointer over the chart to view the connector's
recent throughput.
In the Number of instances chart, hold the pointer over the chart to view the
number of instances recently used by the connector.
In the CPU Utilization chart, hold the pointer over the chart to view the
connector's recent CPU usage. The chart displays the CPU usage distributed
across instances for the 50th, 95th, and 99th percentiles.
Delete a connector
Before you delete a connector, you must remove it from any serverless resources
that still use it. Deleting a connector before removing it from your serverless
resources prohibits you from deleting the VPC network
later.
For Shared VPC users who set up connectors in the Shared VPC
host project, you can use the command
gcloud compute networks vpc-access connectors describe
to list the projects in which there are serverless resources that use a given
connector.
To delete a connector, use the Google Cloud console or the Google Cloud CLI:
This section describes how to create custom constraints for Serverless VPC Access
connectors and enforce them at the project level. For information about custom
organization policies, see
Creating and managing custom organization policies.
Google Cloud Organization Policy gives you centralized, programmatic
control over your organization's resources. As the
organization policy administrator, you can define an organization policy,
which is a set of restrictions called constraints that apply to
Google Cloud resources and descendants of those resources in the
Google Cloud resource hierarchy. You can enforce organization policies at
the organization, folder, or project level.
Organization Policy provides predefined constraints for various
Google Cloud services. However, if you want more granular, customizable
control over the specific fields that are restricted in your organization
policies, you can also create custom organization policies.
Benefits
Serverless VPC Access lets you write any number of custom
constraints using most user-configured fields in the
Serverless VPC Access API. For example, you can create a custom
constraint specifying which subnets a Serverless VPC Access
connector can use.
Once applied, requests that violate a policy that enforces a custom constraint
show an error message in the gcloud CLI and in
Serverless VPC Access logs. The error message contains the
constraint ID and description of the violated custom constraint.
Policy inheritance
By default, organization policies are inherited by the descendants of the
resources that you enforce the policy on. For example, if you enforce a policy
on a folder, Google Cloud enforces the policy on all projects in the
folder. To learn more about this behavior and how to change it, refer to
Hierarchy evaluation rules.
Limitations
Specifying machine type, minimum instances, or maximum instances is not
supported.
A custom constraint is defined in a YAML file by the resources, methods,
conditions, and actions that are supported by the service that you are
enforcing the organization policy on. Conditions for your custom constraints are
defined using
Common Expression Language (CEL). For more information about how to build
conditions in custom constraints using CEL, see the CEL section of
Creating and managing custom constraints.
To create a YAML file for a Serverless VPC Access custom
constraint, refer to the following example:
ORGANIZATION_ID: your organization ID, such as
123456789.
CONSTRAINT_NAME: the name you want for your new
custom constraint. A custom constraint must start with custom., and can
only include uppercase letters, lowercase letters, or numbers, for
example, custom.defaultNetworkConstraint. The maximum length of this field is 70
characters, not counting the prefix.
CONDITION: a CEL condition that is written against
a representation of a supported service resource. This
field has a maximum length of 1000 characters. For example,
"resource.network == default".
ACTION: the action to take if the condition is
met. This can be either ALLOW or DENY.
DISPLAY_NAME: a human-friendly name for the
constraint. This field has a maximum length of 200 characters.
DESCRIPTION: a human-friendly description of the
constraint to display as an error message when the policy is violated, for
example, "Require network to not be set to default."
This field has a maximum length of 2000 characters.
You can enforce a constraint by creating an organization policy that references it, and then
applying that organization policy to a Google Cloud resource.
Operation denied by custom org policies: ["customConstraints/custom.defaultNetworkConstraint": "Require network to not be set to default."]
Example custom organization policies for common use cases
The following table provides examples of custom constraints that you might find
useful with Serverless VPC Access connectors:
Description
Constraint syntax
Require that Serverless VPC Access connectors can
only use a specific network.
name:organizations/ORGANIZATION_ID/customConstraints/custom.allowlistNetworksresourceTypes:-vpcaccess.googleapis.com/ConnectormethodTypes:-CREATEcondition:"resource.network=='allowlisted-network'"actionType:ALLOWdisplayName:allowlistNetworksdescription:Require connectors to use a specific network.
Description
Constraint syntax
Require that Serverless VPC Access connectors have
access to only a specific subnet.
name:organizations/ORGANIZATION_ID/customConstraints/custom.restrictSubnetForProjectresourceTypes:-vpcaccess.googleapis.com/ConnectormethodTypes:-CREATEcondition:"resource.subnet.name=='allocated-subnet'"actionType:ALLOWdisplayName:restrictSubnetForProjectdescription:This project is only allowed to use the subnet "allocated-subnet".
Configure your Cloud Run environment to use Direct VPC instead of a connector
You can enable your Cloud Run service
to send egress (outbound) traffic directly to a VPC network,
allowing access to Compute Engine VM instances, Memorystore
instances, and any other resources with an internal IP address.
Configure your service to use Direct VPC
Direct VPC egress allows your Cloud Run service to send traffic
to a VPC network without a Serverless VPC Access
connector. Network costs scale to zero just like the service itself. You can
also add network tags directly on
Cloud Run service revisions for more granular network security, such as
applying VPC firewall rules.
You can configure Direct VPC egress with a service by using the
Google Cloud console, Google Cloud CLI, YAML, or Terraform.
Optionally, make your service public if you
want to allow unauthenticated access to the service.
Configure your job to use Direct VPC
Direct VPC egress allows your Cloud Run job to send traffic to a
VPC network without a Serverless VPC Access
connector. You can also add network tags
directly on Cloud Run jobs for more granular network security, such as
applying VPC firewall rules.
You can configure Direct VPC egress with a job by using the
Google Cloud console, Google Cloud CLI, or YAML.
To perform operations in your Google Cloud project,
Serverless VPC Access uses the
Serverless VPC Access Service Agent service account. This service
account's email address has the following form:
By default, this service account has the
Serverless VPC Access Service Agent role
(roles/vpcaccess.serviceAgent). Serverless VPC Access
operations may fail if you change this account's permissions.
Google APIs Service Agent
The Serverless VPC Access API depends on Deployment Manager to provision the underlying resources
that implement the connector. To perform operations in your Google Cloud project,
Deployment Manager uses the Google APIs Service Agent. This service account's email address has the following form:
PROJECT_NUMBER@cloudservices.gserviceaccount.com
By default, this service account has the Editor role
(roles/project.editor) / Editor role permissions. If you want to grant the Google APIs Service Agent
more limited permissions, without affecting Serverless VPC Access connector functionality,
you can grant this service account the
Serverless VPC Access Service Agent role
(roles/vpcaccess.serviceAgent) instead.
Certain services other than Deployment Manager also rely on the default
Editor role permissions of the Google APIs Service Agent. Removing this role
might affect other services and resources besides the Serverless VPC Access API. For more
information on the implications of removing the Editor role from the Google
APIs Service Agent, see Google APIs Service Agent.
Poor network performance or high idle CPU utilization
Using a single connector for thousands of instances can cause performance
degradation and elevated idle CPU utilization. To fix this, shard your services
between multiple connectors.
If you use the Restrict Resource Service Usageorganization policy constraint
to block Cloud Deployment Manager (deploymentmanager.googleapis.com), you
might see the following error message:
Serverless VPC Access service account (service-<PROJECT_NUMBER>@gcp-sa-vpcaccess.iam.gserviceaccount.com) needs Serverless VPC Access Service Agent role in the project.
Set the organization policy
to either remove Deployment Manager from the denylist or add it
to the allowlist.
Connector creation error
If creating a connector results in an error, try the following:
Specify an RFC 1918
internal IP range that does not overlap with any existing IP address
reservations in the VPC network.
Grant your project permission to use Compute Engine VM images from the
project with ID serverless-vpc-access-images. For more information about
how to update your organization policy accordingly, see
Set image access constraints.
Unable to access resources
If you specified a connector but still cannot access resources in your
VPC network, make sure that there are no firewall rules on your
VPC network with a priority lower than 1000 that deny ingress
from your connector's IP address range.
If you receive connection refused or connection timeout errors that degrade
network performance, your connections could be growing without limit across
invocations of your serverless application. To limit the maximum number of
connections used per instance, use a client library that supports connection
pools. For detailed examples of how to use connection pools, see
Manage database connections.
Resource not found error
When deleting a VPC network or a firewall rule, you might see a
message that is similar to the following: The resource
"aet-uscentral1-subnet--1-egrfw" was not found.
For information about this error and its solution, see
Resource not found error in the
VPC firewall rules documentation.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2026-07-22 UTC."],[],[]]
