Static outbound IP address

By default, a Cloud Run service connects to external endpoints on the internet using a dynamic IP address pool. This default is not suitable if the Cloud Run service connects to an external endpoint that requires connections originating from a static IP address, such as a database or API using an IP address-based firewall. For those connections, you must configure your Cloud Run service to route requests through a static IP address.

This guide describes how to enable a Cloud Run service to send requests using a static IP address.

Task overview

To enable a Cloud Run service to route requests through a static IP address, you need to configure the Cloud Run service's VPC egress to route all outbound traffic through a VPC network that has a Cloud NAT gateway configured with the static IP address.

Routing your traffic through Cloud NAT does not cause an additional hop in your networking stack since the Cloud NAT gateway and the Cloud Router provide only a control plane and the packets do not pass through the NAT gateway or the Cloud Router.

Note that all Cloud Run services connected to the same VPC network will share the same egress IP address. To use different egress IP addresses for separate Cloud Run services, follow this guide to create separate subnetworks and Serverless VPC Access connectors.

Creating a subnetwork

Creating a subnetwork for the Serverless VPC Access connector to reside in ensures that other compute resources in your VPC, such as Compute Engine VMs or Google Kubernetes Engine clusters, do not accidentally use the static IP you configure to access the internet.

Command line

  1. Find the name of your VPC network:

    gcloud compute networks list

    You should see output like the following:

    NAME     SUBNET_MODE  BGP_ROUTING_MODE
    default  AUTO         REGIONAL

    Identify the network you attached to your Serverless VPC Access connector.

  2. Create a subnetwork in the VPC for the Serverless VPC Access connector.

    gcloud compute networks subnets create SUBNET_NAME \
    --range=RANGE --network=NETWORK_NAME --region=REGION

    In the command above, replace:

    • SUBNET_NAME with a name you want to give to the subnetwork.
    • RANGE with the IP range in CIDR format you want to assign to this subnetwork (e.g. 10.124.0.0/28)
    • NETWORK_NAME with the name of the VPC network.
    • REGION with the region in which you want to create a Serverless VPC Access connector.

Creating a Serverless VPC Access connector

To route your Cloud Run service's outbound traffic to a VPC network, you need a Serverless VPC Access connector.

To create a Serverless VPC Access connector:

Command line

  1. Create a Serverless VPC Access connector with a pre-created subnetwork.

    gcloud compute networks vpc-access connectors create CONNECTOR_NAME \
      --region=REGION \
      --subnet-project=PROJECT_ID \
      --subnet=SUBNET_NAME
    

    In the command above, replace:

    • CONNECTOR with a name you want to give to this resource.
    • PROJECT_ID with a name that hosts the subnetwork.
    • SUBNET_NAME with the name of the subnetwork you created.
    • REGION with the region in which you want to create a NAT gateway.

Configuring network address translation (NAT)

If you use a Serverless VPC Access connector, requests from your Cloud Run service arrive at your VPC network. To route outbound requests to external endpoints through a static IP, you must configure a Cloud NAT gateway.

Command line

  1. Create a new Cloud Router to program a NAT gateway:

    gcloud compute routers create ROUTER_NAME \
      --network=NETWORK_NAME \
      --region=REGION

    In the command above, replace:

    • ROUTER_NAME with a name for the Cloud Router resource you want to create.
    • NETWORK_NAME with the name of the VPC network you found earlier.
    • REGION with the region in which you want to create a NAT gateway.
  2. Reserve a static IP address. A reserved IP address resource retains the underlying IP address when the resource it is associated with is deleted and re-created:

    gcloud compute addresses create ORIGIN_IP_NAME --region=REGION

    In the command above, replace:

    • ORIGIN_IP_NAME with the name you want to assign to the IP address resource.
    • REGION with the region that will run the Cloud NAT router. Ideally the same region as your Cloud Run service to minimize latency and network costs.
  3. Create a Cloud NAT gateway configuration on this router to route the traffic originating from the VPC network using the static IP address you created:

    gcloud compute routers nats create NAT_NAME \
      --router=ROUTER_NAME \
      --region=REGION \
      --nat-custom-subnet-ip-ranges=SUBNET_NAME \
      --nat-external-ip-pool=ORIGIN_IP_NAME
    

    In the command above, replace:

    • NAT_NAME with a name for the Cloud NAT gateway resource you want to create.
    • ROUTER_NAME with the name of your Cloud Router.
    • REGION with the region in which you want to create a NAT gateway.
    • ORIGIN_IP_NAME with the name of the reserved IP address resource you created in the previous step.

Routing Cloud Run traffic through the VPC network

After NAT is configured, you just need to deploy your Cloud Run service with the Serverless VPC Access connector and set the VPC egress to route all traffic through the VPC network:

Command line

Deploy or update your Cloud Run service to use the VPC connector and route all egress traffic through it:

gcloud run deploy SERVICE_NAME \
   --image=IMAGE_URL \
   --vpc-connector=CONNECTOR_NAME \
   --vpc-egress=all-traffic

In the command above, replace:

  • SERVICE_NAME with the name of the Cloud Run service you want to deploy.
  • IMAGE_URL with a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest.
  • CONNECTOR_NAME with the name of your Serverless VPC Access connector.

Verifying the static external IP

After completing the above steps, you have set up Cloud NAT on your VPC network with a predefined static IP address, and you have routed all of your Cloud Run service's outbound traffic into your VPC network. Requests from your Cloud Run service travel through your VPC network and reach external endpoints using the static IP address.

To verify this behavior and confirm the origin IP address your service uses, you can make a request to a website or API that shows the origin IP address, such as curlmyip.org.