Sidecars

Overview

Runway lets you define arbitrary sidecar containers that run alongside the main ingress container within the same Cloud Run service. This is useful for running supporting processes such as auth proxies, log shippers, or agents that need to share the service’s lifecycle and network namespace.

This is separate from the sidecars Runway manages for you (such as the OpenTelemetry collector and the Cloud SQL auth proxy). Those are configured elsewhere and do not need to be declared here.

Minimal example

Each sidecar requires only a name and an image:

spec:
  sidecars:
    - name: my-sidecar
      image: registry.gitlab.com/my-group/my-project/my-sidecar:latest

Configuration reference

Each entry in spec.sidecars supports the following fields. For the full, authoritative list of parameters, refer to the Runway manifest schema, which is the source of truth should this page fall out of sync.

Field	Required	Description
`name`	Yes	Name of the sidecar container. Must be unique within the service.
`image`	Yes	Container image for the sidecar.
`command`	No	Entrypoint command for the sidecar container (list of strings).
`args`	No	Arguments to pass to the sidecar container (list of strings).
`depends_on`	No	List of container names this sidecar depends on, used to control startup ordering.
`resources`	No	Resource management for the sidecar container. See Resources.
`env`	No	Environment variables for the sidecar container. See Environment variables and secrets.
`startup_probe`	No	Health probe that determines when the sidecar has started. See Health probes.
`liveness_probe`	No	Health probe that determines whether to restart the sidecar. See Health probes.

Resources

The resources block controls CPU and memory for the sidecar:

Field	Default	Description
`limits.cpu`	`200m`	CPU limit, measured in CPU units.
`limits.memory`	`128Mi`	Memory limit, measured in bytes.
`startup_cpu_boost`	`false`	Temporarily increases CPU allocation during container instance startup.

spec:
  sidecars:
    - name: my-sidecar
      image: registry.gitlab.com/my-group/my-project/my-sidecar:latest
      resources:
        startup_cpu_boost: true
        limits:
          cpu: "500m"
          memory: "256Mi"

Environment variables and secrets

Each entry in a sidecar’s env list requires a name and exactly one of value (a plain text value) or secret (the key of a Vault secret synced to GSM for this service):

spec:
  sidecars:
    - name: my-sidecar
      image: registry.gitlab.com/my-group/my-project/my-sidecar:latest
      env:
        - name: LOG_LEVEL
          value: "info"
        - name: API_TOKEN
          secret: MY_SIDECAR_API_TOKEN

Secrets referenced via secret follow the same mechanism as the main container. See Secrets Management for how to add a secret to your service.

Health probes

Sidecars support startup_probe and liveness_probe. Both use the same shape. Each probe requires a port and exactly one of path (an HTTP probe) or grpc_service (a gRPC probe); the two are mutually exclusive.

Field	Default	Description
`port`	—	Port to probe on the sidecar container. Required.
`path`	—	Path to access on the HTTP server. Mutually exclusive with `grpc_service`.
`grpc_service`	—	Name of the gRPC health status service. Mutually exclusive with `path`.
`initial_delay_seconds`	`0`	Number of seconds after the container has started before the probe is initiated (max `240`).
`timeout_seconds`	`1`	Number of seconds after which the probe times out (max `3600`).
`period_seconds`	`10`	How often (in seconds) to perform the probe (max `240`).
`failure_threshold`	`3`	Minimum consecutive failures for the probe to be considered failed after having succeeded.

spec:
  sidecars:
    - name: my-sidecar
      image: registry.gitlab.com/my-group/my-project/my-sidecar:latest
      startup_probe:
        path: /healthz
        port: 8080
      liveness_probe:
        grpc_service: my.health.Service
        port: 8080

Full example

spec:
  sidecars:
    - name: auth-proxy
      image: registry.gitlab.com/my-group/my-project/auth-proxy:v1.2.3
      command: ["/bin/auth-proxy"]
      args: ["--listen=:8080"]
      depends_on: ["my-service"]
      env:
        - name: LOG_LEVEL
          value: "info"
        - name: API_TOKEN
          secret: AUTH_PROXY_API_TOKEN
      startup_probe:
        path: /healthz
        port: 8080
      resources:
        startup_cpu_boost: true
        limits:
          cpu: "500m"
          memory: "256Mi"