Connecting to a VPC network

This page shows how to use Serverless VPC Access to connect a Cloud Run (fully managed) service directly to your VPC network, allowing access to Compute Engine VM instances, Memorystore instances, and any other resources with an internal IP address.

To use Serverless VPC Access, you must first create a Serverless VPC Access connector to handle communication to your VPC network. After you create a connector, set your Cloud Run (fully managed) service configuration to use the connector.

Creating a Serverless VPC Access connector

For detailed instructions on creating Serverless VPC Access connectors, refer to Creating a connector.

Configuring a service to use a connector

You can configure a service to use a connector from the Cloud Console, command line, or YAML file when you create a new service or deploy a new revision:

Console

  1. Go to Cloud Run

  2. Click Create Service if you are configuring a new service you are deploying to. If you are configuring an existing service, click on the service, then click Edit and Deploy New Revision.

  3. Under Advanced Settings, click Connections.

    image

  4. In the VPC Connector field, select a connector to use or select None to disconnect your service from a VPC network.

  5. Click Create or Deploy.

Command line

To specify a connector during deployment, use the --vpc-connector flag:

gcloud run deploy SERVICE --image IMAGE_URL --vpc-connector CONNECTOR_NAME
  • Replace SERVICE with the name of your service.
  • Replace IMAGE_URL with a reference to the container image, for example, gcr.io/myproject/my-image:latest.
  • Replace CONNECTOR_NAME with 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:

For example to attach or update a connector:

gcloud run services update SERVICE --vpc-connector CONNECTOR_NAME
  • Replace SERVICE with the name of your service.
  • Replace CONNECTOR_NAME with the name of your connector.

YAML

You can download and view existing service configuration using the gcloud run services describe --format export command, which yields cleaned results in YAML format. You can then modify the fields described below and upload the modified YAML using the gcloud beta run services replace command. Make sure you only modify fields as documented.

  1. To view and download the configuration:

    gcloud run services describe SERVICE --format export > service.yaml
  2. Add or update the run.googleapis.com/vpc-access-connector attribute under the annotations attribute under the top-level spec attribute:

    apiVersion: serving.knative.dev/v1
    kind: Service
    metadata:
      name: SERVICE
    spec:
      template:
        metadata:
          annotations:
            run.googleapis.com/vpc-access-connector: CONNECTOR_NAME
    • Replace SERVICE with the name of your Cloud Run (fully managed) service.
    • Replace CONNECTOR_NAME with the name of your connector.
  3. Replace the service with its new configuration using the following command:

    gcloud beta run services replace service.yaml

Connecting to a Shared VPC network

If your organization uses Shared VPC, a Cloud Run (fully managed) service in a Shared VPC service project can connect to a Shared VPC network after some configuration in the Shared VPC host project.

  1. Make sure an administrator of the host project completes the setup described at Using a Shared VPC network. This setup includes creating a Serverless VPC Access connector in the host project and attaching it to the Shared VPC network.
  2. Enable the Serverless VPC Access API in your service project:

    Enable API

  3. After the host project setup is complete, when you deploy or update a Cloud Run (fully managed) service in your service project, you can specify the host project's connector using the connector's fully-qualified name. For example:

    gcloud run deploy SERVICE --image IMAGE_URL \
    --vpc-connector projects/HOST_PROJECT_ID/locations/CONNECTOR_REGION/connectors/CONNECTOR_NAME

    This connects your service to the Shared VPC network.

Controlling egress traffic from a service

By default, only requests to internal IP addresses and internal DNS names are routed through a Serverless VPC Access connector. In some cases, however, you might want all outbound requests from your service to be routed to your VPC network, for example to prevent outbound traffic to dangerous or unwanted hosts with your network's firewall rules.

For control over routing outbound requests from your service, you can set the VPC egress to one of the following options:

  • Route only requests to private IPs through the VPC connector: Default. Only requests to RFC 1918 and RFC 6598 IP address ranges or internal DNS names are routed to your VPC network. All other requests are routed directly to the internet.
  • Route all traffic through the VPC connector: All outbound requests from the service are routed to your VPC network. Requests will adhere to the network's firewall, DNS, and routing rules.

You can specify a VPC egress setting from the Cloud Console, command line, or YAML file when you create a new service or deploy a new revision:

Console

  1. Go to Cloud Run

  2. Click Create Service if you are configuring a new service you are deploying to. If you are configuring an existing service, click on the service, then click Edit and Deploy New Revision.

  3. Under Advanced Settings, click Connections.

    image

  4. After you select a VPC connector, select Route only requests to private IPs through the VPC connector or Route all traffic through the VPC connector.

  5. Click Create or Deploy.

Command line

To specify an egress setting, use the --vpc-egress flag. You can specify an egress setting during deployment:

gcloud beta run deploy SERVICE \
--image IMAGE_URL \
--vpc-connector CONNECTOR_NAME \
--vpc-egress EGRESS_SETTING
  • Replace SERVICE with the name of your service.
  • Replace IMAGE_URL with a reference to the container image, for example, gcr.io/myproject/my-image:latest.
  • Replace CONNECTOR_NAME with the name of your connector.
  • Replace EGRESS_SETTING with an egress setting value:
    • all: Sends all outbound traffic through the connector.
    • private-ranges-only: Sends only traffic to internal addresses through the VPC connector.

You can also update an existing service and change the egress setting:

gcloud beta run services update SERVICE --vpc-egress EGRESS_SETTING
  • Replace SERVICE with the name of your service.
  • Replace EGRESS_SETTING with an egress setting value as listed above.

YAML

You can download and view existing service configuration using the gcloud run services describe --format export command, which yields cleaned results in YAML format. You can then modify the fields described below and upload the modified YAML using the gcloud beta run services replace command. Make sure you only modify fields as documented.

  1. To view and download the configuration:

    gcloud run services describe SERVICE --format export > service.yaml
  2. Add or update the run.googleapis.com/vpc-access-egress attribute under the annotations attribute under the top-level spec attribute:

    apiVersion: serving.knative.dev/v1
    kind: Service
    metadata:
      name: SERVICE
    spec:
      template:
        metadata:
          annotations:
            run.googleapis.com/vpc-access-connector: CONNECTOR_NAME
            run.googleapis.com/vpc-access-egress: EGRESS_SETTING
    • Replace SERVICE with the name of your Cloud Run (fully managed) service.
    • Replace CONNECTOR_NAME with the name of your connector. The run.googleapis.com/vpc-access-connector attribute is required when specifying an egress setting.
    • Replace EGRESS_SETTING with one of the following:
      • all: Sends all outbound traffic through the connector.
      • private-ranges-only: Sends only traffic to internal addresses through the VPC connector.
  3. Replace the service with its new configuration using the following command:

    gcloud beta run services replace service.yaml

Next steps