Configuring Cloud Run Startup and Liveness Probes for Safe Deployments

The Problem: Traffic Arriving Before Your Container Is Ready

Deploying a new Cloud Run revision that needs time to initialize—JVM warm-up, database migrations, or cache priming—can produce request failures if traffic arrives before the container finishes starting. A running instance can also deadlock or corrupt its in-memory state and stop serving requests. Cloud Run startup and liveness probes address both problems: the startup probe withholds traffic until the container signals readiness, and the liveness probe restarts an instance when it becomes unhealthy.

The key engineering decision is not whether to use probes, but how to configure their thresholds so that slow starts do not block deployments indefinitely and liveness failures do not trigger restart loops.

Desired Outcome

• New revisions receive traffic only after initialization completes.
• Unhealthy instances are restarted automatically without manual intervention.
• A failed probe configuration can be reverted quickly by rolling back to the previous revision.

Prerequisites

• A Cloud Run service whose container image exposes a health endpoint suitable for HTTP, TCP, or gRPC checks.
• The gcloud CLI installed and authenticated, or access to the Cloud Console.
• An account with permissions to deploy Cloud Run revisions and update traffic splitting.
• A non-production service or revision for testing probe behavior before promoting to production.

Probe behavior and supported fields can vary by execution environment and region. Confirm the exact field names and parameters in the current Cloud Run documentation for your project before deploying.

How Cloud Run Probes Work

Probes are configured per container inside the revision template. They are evaluated per instance, not per service.

• Startup probe: Until this probe succeeds, the instance does not receive traffic. Use it for applications with slow initialization, such as JVM warm-up or database migrations.
• Liveness probe: After startup, repeated failure causes Cloud Run to restart the container instance. Use it to recover from deadlocks or corrupted in-memory state.

Both probes are part of the immutable revision specification. Changing a probe requires deploying a new revision. If a startup probe never succeeds, the revision never becomes ready and traffic remains on the previous revision.

Configuring Startup and Liveness Probes

Define the probes in your service YAML under the container specification. The following example illustrates a representative structure using HTTP checks. Verify the exact field names and supported values against current Cloud Run documentation.

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: my-service
spec:
  template:
    spec:
      containers:
      - image: us-docker.pkg.dev/my-project/my-repo/my-service:latest
        ports:
        - containerPort: 8080
        startupProbe:
          httpGet:
            path: /healthz
            port: 8080
          periodSeconds: 5
          timeoutSeconds: 3
          failureThreshold: 30
        livenessProbe:
          httpGet:
            path: /livez
            port: 8080
          periodSeconds: 10
          timeoutSeconds: 2
          failureThreshold: 3

In this example, the startup probe checks /healthz every 5 seconds and allows up to 30 failures, giving the container up to 150 seconds to initialize before the revision is considered failed. The liveness probe checks /livez every 10 seconds and restarts the instance after 3 consecutive failures. Adjust these values to match your application's worst-case startup time and tolerance for transient errors.

Deploying and Verifying the Revision

Run the following command in Cloud Shell or a local terminal where gcloud is authenticated. Replace REGION with your Cloud Run region.

gcloud run services replace service.yaml --region=REGION

Expected check: A new revision appears in the output of gcloud run revisions list --service=my-service --region=REGION. If the startup probe path is incorrect or the application never returns HTTP 200, the revision will not become ready.

To inspect the active revision's probe configuration and readiness, run:

gcloud run services describe my-service --region=REGION

Look for the revision's Ready condition. It should remain false until the startup probe succeeds. You can also view the same information in the Cloud Console under the service's Revisions tab.

Expected Checks

Check	How to verify	What to look for
Startup gating	Describe the service or view the console	New revision Ready condition is false until /healthz returns 200
Liveness restart	Temporarily make /livez return an error, then watch Cloud Monitoring	Instance restarts and request error rate changes; revert the endpoint change afterward
Traffic allocation	Describe the service	Traffic remains on the previous revision while the new one is unready

Recovery: Rolling Back a Faulty Revision

Because probes are immutable, the fastest way to recover from a revision that blocks traffic or causes restart loops is to shift traffic back to the previous revision.

Run the following command, replacing SERVICE_NAME, REGION, and PREVIOUS_REVISION with your values:

gcloud run services update-traffic SERVICE_NAME --region=REGION --to-revisions=PREVIOUS_REVISION=100

Expected check: Traffic shifts immediately. Confirm with gcloud run services describe SERVICE_NAME --region=REGION that the previous revision is receiving 100 percent of requests. To fix the probe itself, deploy a new revision with corrected settings.

Risk: Liveness probe restarts do not drain in-flight requests. Clients should implement retries for idempotent operations to handle abrupt instance termination.

Limitations and Safe Rollout Practices

• Cold-start latency: Startup probes add latency because instances must pass the probe before serving traffic. Set the failure threshold high enough to cover the application's worst-case initialization time.
• Restart loops: A misconfigured liveness probe can cause restart loops that amplify load and reduce capacity. Use conservative failure thresholds and longer periods during initial rollout.
• Environment variance: Probe behavior may vary by execution environment and region. Test in a staging project that mirrors your production configuration.
• Practical verification: Deploy to a test service, confirm the Ready condition gates traffic, simulate a liveness failure, and verify rollback before promoting the revision to production.