Each Serverless VPC Access connector requires its own dedicated
/28 subnet, which cannot be changed after creation. If you don't use Shared VPC,
you can either create a subnet for the connector to use, or specify an unused
custom IP range for the connector to create a subnet for its use. If you choose
the custom IP range, the subnet that is created is hidden and cannot be used in
firewall rules and NAT configurations.
Serverless VPC Access connectors scale up automatically to meet
traffic demand, but don't scale down. Once scaled, resources and associated
costs remain allocated.
Limitation
High packet rates can exhaust shared CPU credits and connection tracking
memory on f1 and e2-micro instances, causing timeouts even when bandwidth
limits aren't reached. We recommend e2-standard-4 instances for production
environments that involve high concurrency or frequent small requests to ensure
sufficient dedicated resources.
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.
You can configure your Cloud Run service to use a Serverless VPC Access
connector for sending egress traffic. You can do this by using the Google Cloud console,
Google Cloud CLI, or YAML file when you create a new service
or deploy a new revision:
IMAGE_URL: a reference to the container image, for
example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry,
the repositoryREPO_NAME must
already be created. The URL follows the format of LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
.
CONNECTOR_NAME: the name of 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:
REVISION with a new revision name or delete it (if present). If you supply a new revision name, it must meet the following criteria:
Starts with SERVICE-
Contains only lowercase letters, numbers and -
Does not end with a -
Does not exceed 63 characters
Create or update the service using the following command:
gcloudrunservicesreplaceservice.yaml
The gcloud run services replace command defaults to using service.yaml file if present.
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 your job
After you have created a Serverless VPC Access connector,
you can configure your Cloud Run job to use the connector. You can
do this by using the Google Cloud console, Google Cloud CLI, or YAML when you
create a new job:
IMAGE_URL: a reference to the container image, for
example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry,
the repositoryREPO_NAME must
already be created. The URL follows the format of LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
.
CONNECTOR_NAME: the name of your
connector.
To attach, update, or remove a connector for an existing service, use the
gcloud run jobs update
command with either of the following flags as needed:
You can download and view an existing job configuration by using the
gcloud run jobs describe --format export command, which yields cleaned
results in YAML format. You can then modify the fields described below and
upload the modified YAML by using the gcloud run jobs replace command.
Make sure you only modify fields as documented.
To view and download the configuration:
gcloudrunjobsdescribeJOB--formatexport>job.yaml
Add or update the run.googleapis.com/vpc-access-connector attribute under
the annotations attribute under the top-level spec attribute:
CONNECTOR_NAME: the name of your connector.
The run.googleapis.com/vpc-access-connector attribute is
required when specifying an egress setting.
Replace the job with its new configuration by using the following command:
gcloudrunjobsreplacejob.yaml
Configure your worker pool
Serverless VPC Access connectors support only egress to VPC
networks. If you need ingress, you must use Direct VPC because it supports L4
ingress when using worker pools.
After you have created a connector, configure your Cloud Run worker
pool to use the connector. To deploy a new worker pool
using Terraform, do the following:
You can restrict access from your connector by using firewall rules and
policies, and you can add additional restrictions by configuring egress and
ingress settings.
Firewall rules and policy settings
Required firewall rules for connectors in service projects
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.
By default, only requests to certain internal IPv4 addresses destinations
(including internal IPv4 destinations resolved by DNS responses) are routed
through a Serverless VPC Access connector. In some cases,
however, you might want all outbound requests from your Cloud Run
resource to be routed to your VPC network.
Serverless VPC Access only supports routing IPv4 traffic. IPv6 traffic
is not supported, even if you have IPv6 routes in your VPC
network.
For control over routing outbound requests from your Cloud Run
resource, you can set the VPC egress to one of the following
options:
Route only requests to private IPs to the VPC: Default.
Traffic is routed through the VPC network only if the packets
carrying the traffic have destinations that match the following:
Packets to any other destination are routed from Cloud Run to
the internet (not through any VPC network).
Route all traffic to the VPC: Traffic is always routed
through the VPC network associated with the connector, for all
packet destinations. You must use this option in these circumstances:
If you need to send traffic to VPC subnet ranges with
privately used external IP address ranges. For more information about
VPC subnet ranges, see Valid IPv4
ranges in the Subnets overview.
If you need to send traffic to a Private Service Connect
endpoint for Google APIs whose address is a privately used external IP
address. For more information about Private Service Connect
endpoints for Google APIs, see Access Google APIs through
endpoints.
If you need to send traffic to any other privately used external IP
address destination that's routable within the connector's VPC
network. Examples of other destinations covering privately used external
IP address could include peering subnet ranges (and peering subnet ranges
created from Allocated IP address ranges for
services)
and those destinations that are accessible using custom routes in the
VPC short.
If your VPC network includes a default route, packets can still
be routed to the internet after being processed by the connector if you
configure a Cloud NAT gateway to provide NAT services
to the subnet used by the connector. These packets are subject to the routes
in your VPC network and the firewall rules that apply to your
VPC network. You can use route and firewall configuration to
control internet egress for all outbound requests sent by your function
through a Serverless VPC Access connector.
Control egress service traffic
You can specify a VPC egress setting by using the
Google Cloud console, Google Cloud CLI, or YAML file when you create
a new service or deploy a new revision:
You can view the current Serverless VPC Access connector settings
for your Cloud Run resource by using the Google Cloud console
or the gcloud command-line tool:
Connectors continue to incur charges even if they have no traffic and are
disconnected. For details, see pricing.
If you no longer need your connector, be sure to delete it to avoid
continued billing.
Disconnect a job
You can disconnect a job from your VPC network by
using the Google Cloud console or the Google Cloud CLI:
Connectors continue to incur charges even if they have no traffic and are
disconnected. For details, see pricing.
If you no longer need your connector, be sure to delete it to avoid
continued billing.
Update a connector
You can update and monitor the following attributes of your connector by using
the Google Cloud console, Google Cloud CLI, or the API:
Machine (instance) type
Minimum and maximum number of instances
Recent throughput, number of instances, and CPU utilization
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".
Troubleshooting
Service account permissions
Serverless VPC Access Service Agent
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."],[],[]]
