Static outbound IP address

By default, a Cloud Run service connects to external endpoints on the internet using a dynamic IP address pool. If the Cloud Run service connects to an external endpoint that requires a static IP address such as a database or API using an IP address-based firewall, you must configure your Cloud Run service to route requests using a static IP address.

This page 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 using a static IP address, 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 don't pass through the NAT gateway or the Cloud Router.

All Cloud Run services connected to the same VPC network share the same egress IP address. To use different egress IP addresses for separate Cloud Run services, follow this page to create separate subnets and, optionally, Serverless VPC Access connectors.

Create a subnet

You must create a dedicated /28 subnet to host a connector. If you're using Direct VPC egress, use an existing subnet or create another one. If you use a connector, the dedicated subnet prevents other compute resources in your VPC network, such as Compute Engine VMs or Google Kubernetes Engine clusters, from accidentally using the static IP address if you have configured Serverless VPC Access to access the internet.

gcloud

  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 that you'll attach to your Serverless VPC Access connector.

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

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

    Replace the following values in this command:

    • SUBNET_NAME with a name you want to give to the subnet.
    • RANGE with the IP range in CIDR format you want to assign to this subnet (for example, 10.124.0.0/28).
    • NETWORK_NAME with the name of the VPC network.
    • REGION with the region that you want to create a Serverless VPC Access connector in.

Terraform

  1. Create the VPC network to use.

    resource "google_compute_network" "default" {
  name = "cr-static-ip-network"
}

    Replace cr-static-ip-network with the subnet name.

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

    resource "google_compute_subnetwork" "default" {
  name          = "cr-static-ip"
  ip_cidr_range = "10.124.0.0/28"
  network       = google_compute_network.default.id
  region        = "us-central1"
}

    Replace the following:

    • cr-static-ip with your subnet name.
    • 10.124.0.0/28 with your CIDR range.
    • us-central1 with your Google Cloud region.

Create a Serverless VPC Access connector

You don't need to create a connector if you use Direct VPC egress. If you don't use Direct VPC egress, you need a Serverless VPC Access connector to route your Cloud Run service outbound traffic to a VPC network.

To create a Serverless VPC Access connector:

gcloud

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

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

    Replace the following values in this command:

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

Terraform

  1. Create a Serverless VPC Access connector.

    resource "google_project_service" "vpc" {
  service            = "vpcaccess.googleapis.com"
  disable_on_destroy = false
}

resource "google_vpc_access_connector" "default" {
  name          = "cr-conn"
  region        = "us-central1"
  min_instances = 2
  max_instances = 3

  subnet {
    name = google_compute_subnetwork.default.name
  }

  # Wait for VPC API enablement
  # before creating this resource
  depends_on = [
    google_project_service.vpc
  ]
}

    Replace cr-conn with the name of your Serverless VPC Access connector.

Configure network address translation (NAT)

If you use Direct VPC egress or a Serverless VPC Access connector, requests from your Cloud Run service arrive at your VPC network. If you want to route outbound requests to external endpoints using a static IP, configure a Cloud NAT gateway.

gcloud

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

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

    Replace the following values in this command:

    • ROUTER_NAME with a name for the Cloud Router resource that you want to create.
    • NETWORK_NAME with the name of the VPC network that you found earlier.
    • REGION with the region that you want to create a Cloud NAT gateway in.

  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

    Replace the following values in this command:

    • ORIGIN_IP_NAME with the name that you want to assign to the IP address resource.
    • REGION with the region that will run the Cloud NAT router. Use 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 that 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

    Replace the following values in this command:

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

Terraform

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

    resource "google_compute_router" "default" {
  name    = "cr-static-ip-router"
  network = google_compute_network.default.name
  region  = google_compute_subnetwork.default.region
}

    Replace cr-static-ip-router with your subnet name.

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

    resource "google_compute_address" "default" {
  name   = "cr-static-ip-addr"
  region = google_compute_subnetwork.default.region
}

    Replace cr-static-ip-addr with your subnet name.

  3. Create a Cloud NAT gateway configuration on this router to route the traffic originating from the VPC network using the static IP address that you created:

    resource "google_compute_router_nat" "default" {
  name   = "cr-static-nat"
  router = google_compute_router.default.name
  region = google_compute_subnetwork.default.region

  nat_ip_allocate_option = "MANUAL_ONLY"
  nat_ips                = [google_compute_address.default.self_link]

  source_subnetwork_ip_ranges_to_nat = "LIST_OF_SUBNETWORKS"
  subnetwork {
    name                    = google_compute_subnetwork.default.id
    source_ip_ranges_to_nat = ["ALL_IP_RANGES"]
  }
}

    Replace cr-static-nat with your Cloud NAT gateway name.

Route Cloud Run traffic through the VPC network

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

gcloud

  • Direct VPC egress

    To deploy or update your Cloud Run service to use Direct VPC egress and route all egress traffic through it, run the following command:

    gcloud run deploy SERVICE_NAME \
--image=IMAGE_URL \
--network=NETWORK \
--subnet=SUBNET \
--region=REGION \
--vpc-egress=all-traffic

    Replace the following values in this command:

    • SERVICE_NAME with the name of the Cloud Run service that you want to deploy.
    • IMAGE_URL with a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL has the shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .
    • NETWORK with the name of your VPC network.
    • SUBNET with the name of your subnet.
    • REGION with a region for your service.

  • Serverless VPC Access connector

    To deploy or update your Cloud Run service to use a Serverless VPC Access connector and route all egress traffic through it, run the following command:

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

    Replace the following values in this command:

    • SERVICE_NAME with the name of the Cloud Run service that you want to deploy.
    • IMAGE_URL with a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL has the shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .
    • CONNECTOR_NAME with the name of your Serverless VPC Access connector.
    • REGION with a region for your service.

Terraform

This Cloud Run service uses a VPC connector and routes all egress traffic through it:

resource "google_cloud_run_v2_service" "default" {
  name     = "cr-static-ip-service"
  location = google_compute_subnetwork.default.region

  deletion_protection = false # set to "true" in production

  template {
    containers {
      # Replace with the URL of your container
      #   gcr.io/<YOUR_GCP_PROJECT_ID>/<YOUR_CONTAINER_NAME>
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    scaling {
      max_instance_count = 5
    }
    vpc_access {
      connector = google_vpc_access_connector.default.id
      egress    = "ALL_TRAFFIC"
    }
  }
  ingress = "INGRESS_TRAFFIC_ALL"

}

Replace us-docker.pkg.dev/cloudrun/container/hello with a reference to your container image.

Verify the static external IP address

After completing the previous 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 that your service uses, you can make a request to an API or a website such as curlmyip.org that shows the originating IP address.

Deleting the static external IP address

If you no longer need a static external IP address, see Release a static external IP address.