Designing Cloud Run with VPC Connectors: Minimal Architecture, Trust Boundaries, and Operational Checks

Problem Statement

You want a Cloud Run service to talk to a private Google Cloud resource—such as Cloud SQL or a VPC‑only API—without exposing that resource to the public internet. The solution is to attach the service to a VPC connector that routes egress traffic into a private subnet.

Functional Requirements

• Cloud Run service and VPC connector must reside in the same region.
• The connector must target a subnet that contains the private resource.
• Connector egress can be PRIVATE_RANGES_ONLY (default) or ALL_TRAFFIC if you need to block all external traffic.
• The Cloud Run service’s service account needs roles/vpcaccess.user and IAM roles for the private resource (e.g., roles/cloudsql.client).
• Health checks and metrics should confirm that egress is functioning.

Smallest Viable Design

The core pattern consists of three components:

1. Cloud Run container – the application that performs the business logic.
2. VPC connector – a regional resource that creates a VPN‑like tunnel into the subnet.
3. Private subnet – the network segment that hosts the private resource (e.g., Cloud SQL).

Adding more services (another Cloud SQL instance, a Pub/Sub trigger, etc.) does not alter the pattern; you only need to grant the service account access to each new resource.

Trust and Data Boundaries

Three distinct boundaries exist:

• Service account boundary – limits what the Cloud Run code can do. Grant only the minimal IAM roles required.
• Connector boundary – isolates the Cloud Run traffic from the rest of the VPC. The connector’s subnet CIDR must not overlap with other services.
• Private subnet boundary – protects the resource itself. Only the connector’s subnet and the Cloud Run service’s IP range (via the connector) should be allowed in the resource’s firewall.

Operational Monitoring

Health Checks

Enable Cloud Run’s built‑in readiness and liveness probes. For VPC connector health, use gcloud beta monitoring metrics list --filter="metric.type:..." to find the vpcaccess.googleapis.com/connector/connection_error_count metric.

Metrics Dashboard

Typical metrics to watch:

• vpcaccess.googleapis.com/connector/connection_count – active connections.
• vpcaccess.googleapis.com/connector/connection_error_count – failed attempts.
• Cloud Run request latency and error rate.

Logging

Route Cloud Run logs and VPC connector logs to Cloud Logging. Search for entries containing VPCConnectorError or CONNECTOR_FAILURE to spot misrouting.

Failure Modes and Redesign Criteria

• Connector down – connection_error_count spikes. Redesign: add a second connector in a different subnet or region for high availability.
• Egress blocked – requests to the private resource fail. Verify that the subnet’s firewall allows traffic from the connector’s CIDR.
• Misconfigured CIDR – overlapping ranges cause routing loops. Redesign: adjust subnet ranges and redeploy the connector.
• All traffic egress – if the connector is set to ALL_TRAFFIC and the service needs external APIs, you must create a separate egress path (e.g., a Cloud NAT).

Practical Example

1️⃣ Create a private subnet

# Run in the project’s default VPC or a custom VPC
# Replace PROJECT_ID and REGION with your values
gcloud compute networks subnets create my-private-subnet \
  --network=default \
  --range=10.0.0.0/24 \
  --region=REGION \
  --project=PROJECT_ID

2️⃣ Create the VPC connector

gcloud compute networks vpc-access connectors create my-connector \
  --region=REGION \
  --subnet=my-private-subnet \
  --project=PROJECT_ID \
  --max-ports=64

3️⃣ Grant IAM roles

Role	Description
roles/vpcaccess.user	Allows the service account to attach to the connector.
roles/cloudsql.client	Allows connection to Cloud SQL instances.

Assign these roles to the Cloud Run service account:

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:YOUR_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/vpcaccess.user \
  --role=roles/cloudsql.client

4️⃣ Deploy Cloud Run with the connector

gcloud run deploy my-service \
  --image gcr.io/PROJECT_ID/my-image \
  --region=REGION \
  --platform=managed \
  --vpc-connector=my-connector \
  --allow-unauthenticated \
  --project=PROJECT_ID

5️⃣ Test connectivity to Cloud SQL

Inside the container, run a simple client (e.g., mysql or psql) pointing at the instance’s private IP. You can also use a lightweight Go/Python script that performs a query and returns the result. A successful query indicates that the connector routes traffic correctly.

6️⃣ Verify operational metrics

# Check connector health
gcloud beta monitoring metrics list \
  --filter="metric.type='vpcaccess.googleapis.com/connector/connection_error_count'" \
  --project=PROJECT_ID

# View Cloud Run latency
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=my-service" \
  --limit=10 --project=PROJECT_ID

Rollback Considerations

If you need to revert the connector, you can delete it. However, this will break all egress from the Cloud Run service until the connector is recreated. Use:

gcloud compute networks vpc-access connectors delete my-connector \
  --region=REGION \
  --project=PROJECT_ID

Only perform this during a maintenance window and after confirming that the service can still reach the private resource via an alternative path.

Limitations & Verification Checklist

• Connector ALL_TRAFFIC blocks internet access. Verify that the service does not need external APIs or add a Cloud NAT.
• Subnet CIDR must not overlap with the connector’s own IP range. Use gcloud compute networks subnets describe to confirm.
• IAM binding propagation can take a few minutes. Wait before testing connectivity.
• Always check Cloud Logging for ERROR entries after deployment.

When to Redesign

Consider redesigning the architecture if:

• Latency to the private resource consistently exceeds the SLA.
• You need to expose the service to multiple VPCs or regions.
• The service requires both private and public egress simultaneously.
• Security audits demand stricter isolation (e.g., separate connector per environment).

Typical redesigns involve adding a second connector, moving to a dedicated VPC, or implementing a service mesh for finer‑grained traffic control.