Deploy with a Go backend

Go services usually ship as a single static binary in a scratch or distroless image — and the sidecar follows the same philosophy: it’s a static binary too, running as its own container or process. There is nothing to embed in your Go binary and no SDK to import; your application code doesn’t change.

This guide assumes you have a config bundle or a hand-written sidecar.yaml + token.

Docker Compose

compose.yaml

services:
  app:
    image: acme/acme-api:latest        # e.g. FROM scratch, your Go binary
    ports:
      - "8080:8080"

  ringzero-sidecar:
    image: ghcr.io/ringzero/sidecar:1
    restart: unless-stopped
    ports:
      - "7301:7301"                    # challenge listener — reachable at every (re)registration
    volumes:
      - ./ringzero-sidecar-config:/etc/ringzero:ro

Keep your scratch image scratch

Because the sidecar is a separate container, your FROM scratch app image stays exactly as minimal as it is today — no shells, no extra layers, no CA-bundle additions. The sidecar image carries its own certificates.

Kubernetes

On Kubernetes, prefer gateway mode

For ClusterIP-only services (the common case) — and any private cluster — use gateway mode: sidecars dial an in-cluster Scan Gateway outbound, no ingress needed. The direct-mode manifests below are for internet-reachable clusters; there, a Service round-robins the challenge to the wrong pod, so for replicated workloads use the DaemonSet per-node pattern — see Kubernetes: direct mode.

The per-pod sidecar (when each pod has its own reachable address):

Kubernetes 1.29+ (native sidecar)

deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: acme-api
spec:
  replicas: 1
  selector:
    matchLabels: { app: acme-api }
  template:
    metadata:
      labels: { app: acme-api }
    spec:
      initContainers:
        - name: ringzero-sidecar
          image: ghcr.io/ringzero/sidecar:1
          restartPolicy: Always          # native sidecar (K8s 1.29+)
          ports:
            - containerPort: 7301
          volumeMounts:
            - name: ringzero-config
              mountPath: /etc/ringzero
              readOnly: true
          resources:
            requests: { cpu: 10m, memory: 16Mi }
            limits: { memory: 64Mi }
      containers:
        - name: app
          image: acme/acme-api:latest
          ports:
            - containerPort: 8080
      volumes:
        - name: ringzero-config
          secret:
            secretName: ringzero-sidecar

Older Kubernetes

deployment.yaml (fragment)

# identical, but the sidecar goes under `containers` instead of
# `initContainers` (drop restartPolicy) — no ordering guarantee relative
# to the app, which is fine: registration is independent of its lifecycle.
containers:
  - name: app
    image: acme/acme-api:latest
  - name: ringzero-sidecar
    image: ghcr.io/ringzero/sidecar:1
    ports:
      - containerPort: 7301
    volumeMounts:
      - name: ringzero-config
        mountPath: /etc/ringzero
        readOnly: true

Create the Secret from your bundle as shown in Automated setup.

Single binary on a VM (systemd)

Go shops deploying a bare binary to VMs run the sidecar the same way — two units side by side. The download steps, checksum verification, and systemd unit are stack-independent; one sidecar per host covers every service on that host.

Verify

Sidecar logs show host registered; Settings → Hosts lists the host as active (see the host lifecycle); the health probe reports "registered": true. Troubleshooting: manual setup.