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 in your service's project 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. Configure the host project for Shared VPC following the instructions at Configuring the host project if using Shared VPC.

  2. Create the connector for Shared VPC following the instructions at Creating a connector.

  3. When you deploy or update a Cloud Run (fully managed) service in your service project, specify the connector in the console UI using the using the VPC Connector pulldown menu in the Connections tab, or if using the gcloud command line, specify the connector using the --vpc-connector flag.

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 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-traffic: 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 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-traffic: 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

Viewing VPC connections settings

To view the current VPC connections settings for your service:

Console

  1. Go to Cloud Run

  2. Click the service you are interested in to open the Service details page.

  3. Click the Revisions tab.

  4. In the details panel at the right, the VPC connections setting is listed under the Connections tab.

Command line

  1. Use the following command:

    gcloud run services describe SERVICE
  2. Locate the VPC connections setting in the returned configuration.