# Cloud Run deployment decisions

Use this card for deployment mechanics. Verify every current flag and quota in
the official `gcloud` reference before applying it to a real service.

## Build and deploy

- Build from source or push an immutable image through Artifact Registry using
  the current documented Cloud Build and Cloud Run path.
- Record the deployed digest, region, service account, port, CPU, memory,
  concurrency, request timeout, minimum and maximum instances, and billing
  mode.
- Keep `min-instances` at zero unless a warm floor has an explicit owner and
  budget.
- Map resource values to observed workload behavior. Robium's Gazebo and Nav2
  trial used 8 vCPU and 8 GiB to obtain roughly 0.9 to 1.2 real-time factor on
  2026-07-12/13; this is not a general sizing recommendation.

Official starting points:

- [Cloud Run deployment](https://cloud.google.com/run/docs/deploying)
- [`gcloud run deploy`](https://cloud.google.com/sdk/gcloud/reference/run/deploy)
- [Cloud Build](https://cloud.google.com/build/docs)
- [Artifact Registry](https://cloud.google.com/artifact-registry/docs)

## Choose the billing mode

- Request-based CPU works when a request or WebSocket remains open throughout
  boot and active work. It can reach zero CPU between requests.
- Instance-based CPU is appropriate when a start action launches background
  boot before the viewer connects. It continues billing while the instance is
  retained.
- Robium observed roughly $0.20 to $0.40 of retained-idle cost after a session
  at 8 vCPU and 8 GiB in July 2026. Treat this as a dated observation and use
  current pricing for any decision.

## Concurrency and affinity

- Concurrency of one can isolate one long-lived connection but leaves no room
  for separate status or stop requests on the same instance.
- A higher concurrency with session affinity can support the viewer and
  lifecycle requests, but affinity is routing rather than authorization.
- In Robium's deployment, the affinity cookie was SameSite-Lax. Cross-site
  requests to a `run.app` host did not carry it; a same-site subdomain plus
  credentialed, exact-origin CORS did. Re-check current behavior before relying
  on this shape.
- If the demo requires access control, validate a host-issued signed or
  high-entropy capability in the gateway even when affinity works. A
  browser-chosen first-claim key coordinates visitors but is not authorization.

## WebSockets and probes

- A WebSocket is a long request and is bounded by the configured request
  timeout. Match it to the advertised session length.
- Validate the actual upgrade protocol through the Cloud Run URL using HTTP/1.1
  when the selected bridge requires it.
- Under request-based CPU, hold the probe through boot. A short health request
  can disappear while the background process is still starting and leave the
  instance frozen.
- Declare `Connection: close` when a hand-written server closes an HTTP
  response. Robium observed malformed-response edge 503s without it in the
  July 2026 gateway.

## Deployment authentication

- Prefer short-lived workload identity where the delivery environment supports
  it. If a service-account key is explicitly authorized, materialize it only in
  a protected temporary file, activate it non-interactively, and remove the
  file immediately after the deploy.
- Never print the key, put it in a command URL, or commit the materialized
  credential. Current authentication guidance belongs to Google Cloud's
  official documentation.

## Fleet visibility and VPC capacity

- Read fleet count from Cloud Monitoring only while a live session needs it;
  polling a dedicated service on an idle page can cold-start billable capacity.
- The July 2026 deployment queried
  `run.googleapis.com/container/instance_count`, cached it for roughly 30
  seconds, and observed around one minute of lag. Current metric semantics may
  differ; present the count as approximate and verify the runtime service
  account has only the monitoring access it needs.
- Direct VPC egress needs subnet space for the whole possible instance pool.
  Robium observed a `/28` fail at five 8-vCPU instances and a `/24` work on
  2026-07-12/13. Preserve this as evidence of the sizing relationship, not a
  universal prefix recommendation.

## Final verification

- Confirm the deployed digest and service configuration.
- Compare the latest-created revision, latest-ready revision, and traffic map.
  A successful deploy can leave an older tagged revision serving all traffic;
  route to the intended revision explicitly when needed, then probe the public
  path rather than trusting the deploy summary.
- Exercise readiness and the real HTTP or WebSocket path through Cloud Run.
- Verify idle scale-down, timeout, session isolation, and teardown.
- Record the measured cold start and cost conditions in the application rather
  than copying this card's observations.

# Cloud Run failure router

Start with the first boundary whose evidence is wrong.

- **Build or deploy is rejected**
  - Compare the current `gcloud` command, quota, region, resource request,
    service account, and VPC capacity with official documentation.
  - An image build failure is different from a service revision that cannot be
    scheduled or routed.

- **Container starts locally but boot stalls on Cloud Run**
  - Check whether a request remains open and whether the service uses
    request-based CPU.
  - Continuing logs while a request is open, then silence after it closes,
    points to CPU allocation rather than application deadlock.

- **Gazebo or ROS processes run but topics/world data are absent**
  - Inspect discovery configuration and the first real simulator and DDS data,
    not only process presence.
  - A permanent world-name request loop in the tested Gazebo topology indicates
    the sticky relay race described in `GAZEBO-ROS2.md`.

- **Viewer connects but status or stop reaches another instance**
  - Check affinity-cookie delivery, origin, credentialed requests, and the
    gateway's session-routing or first-claim state.
  - Repeated 409 or 403 responses with otherwise healthy instances distinguish
    routing/claim mismatch from readiness failure.

- **WebSocket drops at a repeatable duration**
  - Compare the elapsed time with the configured Cloud Run request timeout and
    application session cap.
  - Test the real upgrade protocol through the public route; local bridge
    success does not prove proxy compatibility.

- **First boot is much slower than later boots**
  - Separate image pull time from application readiness using revision logs and
    app timestamps.
  - Record the measured cold-start range instead of hiding it behind fake
    progress.

- **Edge returns a malformed-response 503**
  - For a hand-written HTTP server, verify status line, content length, and an
    explicit connection-close header when the socket is closed.

- **VPC deployment reports insufficient addresses**
  - Size the subnet for maximum concurrent instances, not for one container.
  - Inspect current allocation rules before changing the service or network.

- **Public shell is reachable**
  - Treat that as a security review boundary: inspect runtime credentials,
    network egress, filesystem persistence, authentication, and authorization.
  - Do not rely on container isolation or an unauthenticated Cloud Run setting
    as the threat model.

# Gazebo and ROS 2 on Cloud Run

This compatibility card records Robium's Gazebo Harmonic, ROS 2, and Nav2
deployment observations from 2026-07-12/13. It does not define defaults for
other simulator, middleware, or bridge versions.

## Discovery boundary

- Cloud Run provided no usable UDP multicast for Gazebo transport or DDS
  discovery.
- The tested single-container stack used `GZ_RELAY=127.0.0.1` and
  `GZ_IP=127.0.0.1` for Gazebo transport, and
  `FASTDDS_BUILTIN_TRANSPORTS=UDPv4` to avoid Fast DDS shared-memory errors.
- Verify current environment-variable behavior against the
  [Gazebo transport relay documentation](https://gazebosim.org/api/transport/14/relay.html)
  and the middleware version actually installed.

## Sticky Gazebo boot failures

- With more than two Gazebo processes, Robium observed a per-boot unicast relay
  race: a boot either discovered the world or never recovered.
- The failure signature was repeated `Requesting list of world names.` with no
  Gazebo output, odometry, or scan data.
- A status node watched for first simulator data and terminated PID 1 after
  roughly 120 seconds without it. A fresh instance could then boot on reconnect.
- The trial lost roughly half of affected boots. Preserve the watchdog as a
  bounded recovery for this tested topology, then re-measure it for another
  Gazebo process layout.

## Process and readiness behavior

- The tested `ros2 launch` process running as PID 1 shut down correctly on
  `SIGINT`; assuming `SIGTERM` caused the container to remain alive. Verify the
  actual entrypoint rather than generalizing this signal choice.
- Readiness meant simulator data, required ROS nodes, and an application metric
  such as real-time factor, not merely an open HTTP port.
- A 2.5 GB ROS image added about 30 to 90 seconds on a fresh node during the
  measured deployment. State a measured cold-start window on the public page.

## Session isolation

- Concurrent ROS stacks on a shared host need distinct discovery domains.
  Robium's local orchestrator assigned a free `ROS_DOMAIN_ID` for each
  instance; a fixed domain merged graphs and produced backward-time transform
  warnings.
- Cloud Run instance isolation does not replace application-level access
  control when the demo requires it. Keep first-claim coordination and real
  authorization distinct.

---
name: cloud-run
description: Deploy and debug headless robotics containers on Google Cloud Run.
---

# Cloud Run

Treat Cloud Run as a request-driven web runtime, not a conventional robot
host.

## Shape the workload for Cloud Run

- Expose one HTTP port and keep durable state outside the instance.
- Decide whether startup is covered by a held request. Under request-based
  billing, background robot or simulator boot can lose CPU when no request is
  open; instance-based CPU changes the cost model.
- Expect WebSocket sessions to inherit the request timeout and instance
  lifecycle. Size the timeout to the intended session, not to an assumed
  default.
- Scale to zero unless a paid warm floor is explicitly justified. State the
  session cost, fleet ceiling, and cold-start expectation.
- General container composition belongs to `integration`; the session gateway
  and visitor lifecycle belong to `live-demo`.

## Verify before deploying

- Check current commands, flags, quotas, WebSocket behavior, and pricing in
  [official Cloud Run documentation](https://cloud.google.com/run/docs) and the
  [`gcloud run deploy` reference](https://cloud.google.com/sdk/gcloud/reference/run/deploy).
- Read [DEPLOYMENT.md](DEPLOYMENT.md) when building, choosing billing and
  concurrency, configuring affinity, authenticating CI, or validating the
  deployed route.
- Treat Robium's measured values as compatibility evidence tied to their
  workload and date. Re-measure CPU, memory, timeouts, and fleet size for the
  application being deployed.
- Public shells require a separate threat model for credentials and egress;
  unauthenticated reachability is not a security design.

## Account for robotics networking

- Cloud Run does not provide the multicast discovery expected by Gazebo
  transport or DDS. A single-container deployment needs an explicit local
  discovery strategy and evidence that the actual graph communicates.
- For the proven Gazebo Harmonic, ROS 2, and Nav2 deployment conditions, read
  [GAZEBO-ROS2.md](GAZEBO-ROS2.md). Do not copy those values into a different
  stack as defaults.
- Route bridge protocol, layouts, and client behavior to `foxglove`; Cloud Run
  only owns how the HTTP/WebSocket route reaches the container.

## Debug from the boundary inward

- Distinguish image pull, CPU starvation, transport discovery, application
  readiness, proxy behavior, affinity, and VPC capacity before changing the
  application.
- Read [FAILURES.md](FAILURES.md) for the evidence that separates common
  failures.
- A probe under request-based billing must remain open long enough to cover the
  work it is testing; connect-and-drop can create the failure it appears to
  diagnose.

## Done

- The immutable image starts with the selected billing mode and resource
  limits.
- Readiness and the real HTTP or WebSocket path work through Cloud Run.
- Idle capacity, session timeout, fleet ceiling, authentication, and cleanup
  behavior match the stated cost and security boundaries.