Manifest reference

The complete schema for the YAML / JSON files you pass to ring apply -f. Every field, what Ring expects in it, and what happens if you omit it.

A manifest has three top-level keys: namespaces: (optional), configs: (optional) and deployments: (required).

Runtime parity. Most fields below are honored by both runtimes. A handful are Docker-only: they are declared in the manifest, accepted by the API, and either silently ignored or rejected by the Cloud Hypervisor runtime. Each affected section flags this inline; the cross-cutting list lives on Cloud Hypervisor → Limitations.

YAMLJSON
namespaces:
  production:
    name: production

deployments:
  api:
    name: api
    namespace: production
    runtime: docker
    image: "myapp:v1.2.3"
    replicas: 3

Top level

namespaces: (optional)

A map of namespace declarations. When present, Ring creates them before processing deployments. Already-existing namespaces are silently skipped. Namespaces are also auto-created the first time a deployment lands in them, so this section is purely cosmetic, useful when you want all namespaces in a manifest to be self-documenting.

YAMLJSON
namespaces:
  production:
    name: production
  staging:
    name: staging

configs: (optional)

A map of config declarations. When present, Ring creates them after namespaces and before deployments, so a deployment that mounts one via a type: config volume can resolve it on first apply. Already-existing configs (same name + namespace) are reported as "already exists, skipping": re-applying an unchanged manifest is idempotent and never errors. The map key is internal; Ring keys the config by its name + namespace.

YAMLJSON
configs:
  nginx-config:
    namespace: production
    name: "nginx-config"
    data: '{"site.conf":"server { listen 80; }"}'
    # labels: "tier=frontend"   # optional

At least one of data or files must be present; a config with neither is rejected.

files: for keeping large payloads in their own file

Inlining a big config (an Nginx site, a full config.yaml, an HTML error page) into data means hand-escaping a string-of-JSON-inside-YAML, where newlines become \n, quotes get doubled, and the manifest becomes unreadable. files: avoids that: keep the payload as a normal file next to the manifest and reference it.

YAMLJSON
configs:
  sozune-config:
    namespace: proxy
    name: "sozune-config"
    files:
      config.yaml: ./sozune/config.yaml   # relative to this manifest

At apply time Ring reads ./sozune/config.yaml verbatim and builds data = {"config.yaml": "<file contents>"}. The file stays a real, editable YAML file, with no escaping.

data and files can be combined to merge an inline entry with file-backed ones:

YAMLJSON
configs:
  app-config:
    namespace: production
    name: "app-config"
    data: '{"feature.flag":"on"}'   # small inline entry
    files:
      config.yaml: ./config.yaml     # large file-backed entry

The two are merged into a single JSON object. Defining the same key in both data and files is an error, and when files is used a non-object data (anything that isn't a {...} JSON object) is rejected.

$VAR interpolation and file contents

By default, $VAR interpolation runs on inline data (it's a template you write by hand) but not on files contents. This matters: an Nginx site, a Prometheus rule, or a Grafana dashboard is full of literal $host, $labels, $remote_addr, and interpolating them would silently mangle the file (or worse, splice a host env var's value into the payload). So a referenced file ships verbatim.

The interpolate field overrides this per config:

YAMLJSON
configs:
  nginx:
    namespace: proxy
    name: "nginx"
    files:
      site.conf: ./site.conf      # $host etc. kept verbatim

  templated:
    namespace: proxy
    name: "templated"
    interpolate: true             # opt in: $VAR substituted in the file too
    files:
      app.conf: ./app.conf

A manifest carrying its own configs: is self-sufficient: ring apply -f manifest.yaml creates the configs and the deployments that reference them in one pass, with no out-of-band ring config create needed.

deployments: (required)

A map of deployment declarations. The map key is internal; Ring keys the deployment by its name + namespace fields, not by the YAML key. By convention the YAML key matches the name.

Deployment fields

Required

Optional

environment

Map of environment variables passed to the container. Values come in two forms:

• Plain string: passed verbatim.
• Secret reference: an object { secretRef: <name> } that resolves to an encrypted secret in the same namespace at deployment time.

YAMLJSON
environment:
  LOG_LEVEL: "info"                  # plain
  DATABASE_PORT: "5432"              # plain (must be a string in YAML)
  DATABASE_PASSWORD:
    secretRef: "database-password"   # encrypted
  JWT_SECRET:
    secretRef: "jwt-secret"

If a secretRef cannot be resolved, the deployment is marked failed and an error event is emitted (reason: SecretResolutionError). See how-to: deploy with secrets.

Variable interpolation

ring apply interpolates $VAR references in string values from your shell environment, or from a file passed with --env-file. This happens client-side, before the manifest is sent to the API:

YAMLJSON
environment:
  IMAGE_TAG: "$IMAGE_TAG"
  DEPLOY_USER: "$USER"

export IMAGE_TAG="v1.2.3"
ring apply -f deployment.yaml

Interpolation also applies to image, name, namespace, and command arguments, anywhere a string lives in the manifest.

volumes

A list of volume objects. Four types are supported:

Schema

YAMLJSON
volumes:
  - type: bind
    source: /var/lib/ring/postgres
    destination: /var/lib/postgresql/data
    driver: local
    permission: rw

  - type: volume
    source: app-data
    destination: /data
    driver: local
    permission: rw

  - type: config
    source: nginx-config            # name of an existing `ring config`
    key: site.conf                  # which entry inside the config to mount
    destination: /etc/nginx/conf.d/site.conf
    driver: local
    permission: ro

  - type: secret
    source: api-bearer-token        # name of an existing `ring secret`
    destination: /run/secrets/api-token
    driver: local
    permission: ro

For config and secret volumes, the source is the config's or secret's name (not its UUID), and the resource must live in the same namespace as the deployment. See Cloud Hypervisor → Volumes for runtime-specific lifecycle details.

For secret volumes specifically:

• The whole decrypted value becomes the file contents (no key: field).
• Containers should treat the path as read-only, since Ring forces ro.
• If you update the underlying ring secret, the running container keeps the old value until it is restarted. Trigger a redeploy to pick up the new value.

Wire-format vs ring apply. The API DTO requires driver and permission to be present (no defaults at deserialization time). The ring apply CLI fills them in client-side before posting (local and rw respectively, except for config which becomes ro). If you POST /deployments directly with raw JSON, include both fields explicitly.

A writable named volume cannot be shared across replicas. A type: volume mount with permission: rw and replicas > 1 is rejected at validation (deployment.volumes.shared_rw_replicas): every replica would mount the same volume read-write with no cross-writer coordination, which silently corrupts data (e.g. a database). Either drop replicas to 1, or mount the volume ro, since read-only sharing is allowed.

Named volumes a deployment mounts are auto-registered as first-class volumes, so they are traceable and can be managed via the /volumes API. Anonymous volumes (from an image's VOLUME directive) are removed with their container; named volumes are never deleted by a deployment's deletion.

ports

Host-port publishings. Each entry maps a host port to a container port:

YAMLJSON
ports:
  - { published: 8080, target: 80 }
  - { published: 3000, target: 3000 }
  - { published: 5432, target: 5432, host_ip: 127.0.0.1 }

Ring forwards these to Docker's HostConfig.PortBindings (Docker runtime) or to a socat forwarder (Cloud Hypervisor runtime); host_ip and protocol are honored by both runtimes. If published is already in use on the host, the start fails, and the conflict is surfaced as an error event on the deployment, not at ring apply time. Note that the same published port number is a valid, non-conflicting pair across two different host_ip values (e.g. 0.0.0.0:8080 and 127.0.0.1:8080) or across the two protocols (8080/tcp and 8080/udp), since both are distinct bindings to the kernel.

If you do not publish a port, the container is reachable only from inside its namespace. See how-to: isolate namespaces and route traffic.

network

Selects the container's network namespace.

YAMLJSON
network:
  mode: host

bridge: the deployment is attached to a per-namespace bridge network (ring_{namespace}). This is the standard Docker behavior and matches what Ring did before this field existed.

host: the container shares the host's network namespace directly. It can bind to host ports without ports: mapping, sees real client IPs, and can use multicast / broadcast. Useful for L4/L7 reverse proxies (HAProxy, Nginx as edge), packet-capture sidecars, VPN gateways (WireGuard, Tailscale), and service-discovery agents (mDNS, Consul gossip).

When mode: host, the API rejects the deployment if:

• ports: is non-empty, because host networking bypasses Docker's port bindings, so the mapping would be silently ignored. Remove ports: and let the container bind directly.
• replicas: > 1, because all replicas would compete for the same host ports.
• runtime: cloud-hypervisor, because host mode is Docker-only. The CH runtime has its own network model.

See how-to: use host network mode for the full walk-through.

labels

A free-form key/value map forwarded to Docker container labels. Useful for service discovery (Traefik), monitoring (Prometheus relabel rules), or filtering (docker ps --filter "label=key=value").

Cloud Hypervisor: the field is parsed but silently ignored, since there is no equivalent of Docker container labels in the VM model.

YAMLJSON
labels:
  app: api
  tier: backend
  version: v1.2.3
  "traefik.enable": "true"
  "traefik.http.routers.api.rule": "Host(`api.example.com`)"

Quote keys that contain dots, since YAML treats them as strings only when quoted.

In addition to user-supplied labels, Ring adds ring_deployment=<deployment-id> to every container. Do not remove this label: Ring uses it to discover the containers it owns.

resources

CPU and memory limits and requests:

YAMLJSON
resources:
  limits:
    cpu: "500m"        # 500 millicores = 0.5 CPU
    memory: "512Mi"
  requests:
    cpu: "100m"
    memory: "128Mi"

Both limits and requests are optional. Within each, cpu and memory are also optional.

Memory admission control. Before creating a container or booting a VM, Ring checks the deployment's requested memory against the host's currently-available memory. The figure it admits against is requests.memory if set, otherwise limits.memory (and, on Cloud Hypervisor, the 256 MiB default when neither is set). If the host can't hold it, the deployment goes to the terminal status insufficient_resources with an event naming the gap (needs X MiB but only Y MiB is available), instead of starting and getting OOM-killed (Docker) or failing the VM spawn opaquely (CH). The check is best-effort and point-in-time (it catches gross over-asks, not fine-grained contention), and it is not applied to CPU, since CPU overcommit is non-fatal. A deployment that declares no memory request or limit is not gated.

Cloud Hypervisor sizing. When resources is not set on a CH deployment, the VM defaults to 1 vCPU and 256 MiB of RAM. Resizing is at-boot only; Ring does not use Cloud Hypervisor's vm.resize API to live-resize a running VM, so changing resources requires a redeploy.

Firecracker sizing. Reads limits (falling back to requests): the memory becomes the microVM's RAM and the CPU becomes its vCPU count, rounded up to whole vCPUs (Firecracker can't allocate fractional cores) with a floor of 1. When neither is set, a microVM defaults to 1 vCPU and 512 MiB, enough headroom to boot systemd plus a real service rather than OOMing at boot. Sizing is at-boot only; changing resources requires a redeploy.

CPU values

• Millicores: "500m" (= 0.5 cores), "1500m" (= 1.5 cores)
• Whole or fractional cores: "1", "0.5", "2"

Memory values

• Raw bytes: "536870912"
• IEC suffixes: "512Mi", "1Gi", "2Gi"

Cloud Hypervisor: resources.limits.cpu becomes the VM's vCPU count (minimum 1) and resources.limits.memory becomes the VM's RAM (minimum 128 MiB). requests is ignored on the CH runtime.

health_checks

A list of probe definitions. Each probe runs independently with its own counter and its own failure action. Three types: tcp, http, command.

YAMLJSON
health_checks:
  - type: http
    url: "http://localhost:8080/health"
    interval: "30s"
    timeout: "5s"
    threshold: 3
    on_failure: restart

  - type: tcp
    port: 5432
    interval: "10s"
    timeout: "2s"
    on_failure: alert

  - type: command
    command: "pg_isready -U postgres"
    interval: "15s"
    timeout: "3s"
    on_failure: restart

Common fields

Type-specific fields

Cloud Hypervisor caveat: tcp and http are supported (probes run from the host against the VM's deterministic guest IP). command is supported via the in-guest ring-agent daemon. See Cloud Hypervisor → Health checks.

See how-to: configure health checks for tuning and recipes, and health checks (design) for the rolling-update interaction.

config

Runtime-level configuration: image pull policy, registry credentials.

Container runtimes only. Every field of config is consumed by the container runtimes (Docker, Podman, containerd). On Cloud Hypervisor, the entire block is silently ignored: there is no image to pull, and the disk image at image: is read from the local filesystem.

YAMLJSON
config:
  image_pull_policy: "Always"        # "Always" or "IfNotPresent"
  server: "registry.company.com"     # private-registry hostname
  username: "registry-user"
  password: "$REGISTRY_PASSWORD"     # interpolated from shell env

The password field is not an encrypted secret; it lives in the deployment row in the database. To avoid committing credentials, interpolate from the shell with $VAR and pass them via ring apply --env-file, or use use_host_auth to keep the secret on the host entirely.

use_host_auth: credentials from the host

Instead of inlining server/username/password, a deployment can pull using the credentials the operator already configured on the host (e.g. via docker login). The secret then never reaches the deployment manifest, the database, or the API.

YAMLJSON
config:
  image_pull_policy: "Always"
  use_host_auth: true        # read ~/.docker/config.json on the host

It is a two-flag handshake:

1. The server must authorize it by setting use_host_registry_auth = true under the runtime's [server.runtime.*] section (see config-toml).
2. The deployment activates it with use_host_auth: true.

If a deployment sets use_host_auth on a runtime that did not authorize it, the deployment fails fast with an actionable error (no silent fallback to an anonymous pull). Combining use_host_auth with inline server/username/password is rejected at apply time.

Supported on Docker, Podman and containerd. The host config follows the standard Docker resolution ($DOCKER_CONFIG, then ~/.docker/config.json), honoring credHelpers/credsStore. When the Ring daemon runs as a different user than the one who logged in (or for a Podman containers/auth.json), pin the file explicitly with host_registry_config in the server config.

image_pull_secret: credentials from an encrypted Secret

The portable, declarative alternative to use_host_auth: store the registry credentials in an encrypted Secret (AES-256-GCM at rest) and reference it by name. The credentials never appear in the manifest, the database row, or the API response; only the secret's name does.

The Secret's value is a Docker config.json payload (dockerconfigjson), the exact format docker login writes. The simplest way to create it is to log in once and store the resulting file:

docker login rg.fr-par.scw.cloud
ring secret create scaleway-registry -n production \
  --value "$(cat ~/.docker/config.json)"

YAMLJSON
# deployment: references the Secret by name, no credentials inline
config:
  image_pull_policy: "Always"
  image_pull_secret: "scaleway-registry"

Credential helpers. This works when docker login stores the credential inline in config.json (an "auth": "..." entry, the common case on Linux servers). If Docker is configured with a credential helper (credsStore/credHelpers, e.g. Docker Desktop), the file holds no usable credential, because it's in the OS keychain instead. In that case either write the auths entry by hand, or use use_host_auth, which resolves helpers on the host.

At deploy time the scheduler decrypts the Secret, picks the auths entry matching the image's registry host, and pulls with it. If the Secret is missing or has no entry for the registry, the deployment fails fast with an image_pull_secret_resolution_error event (the value is never logged). It must reference a Secret in the same namespace as the deployment, and is mutually exclusive with inline server/username/password and with use_host_auth.

Supported on Docker, Podman and containerd.

Full example

YAMLJSON
namespaces:
  production:
    name: production

deployments:
  api:
    name: api
    namespace: production
    runtime: docker
    kind: worker
    image: "registry.company.com/myapp:v1.2.3"
    replicas: 3

    command:
      - "node"
      - "server.js"

    environment:
      NODE_ENV: "production"
      PORT: "8080"
      LOG_LEVEL: "info"
      DATABASE_URL:
        secretRef: "database-url"
      JWT_SECRET:
        secretRef: "jwt-secret"

    volumes:
      - type: bind
        source: /var/log/api
        destination: /var/log/app
        driver: local
        permission: rw

      - type: config
        source: api-config
        destination: /etc/app/config.json
        driver: local
        permission: ro

    ports:
      - { published: 8080, target: 8080 }

    labels:
      app: api
      tier: backend
      version: "v1.2.3"
      "traefik.enable": "true"
      "traefik.http.routers.api.rule": "Host(`api.example.com`)"

    resources:
      limits:
        cpu: "1"
        memory: "1Gi"
      requests:
        cpu: "200m"
        memory: "256Mi"

    health_checks:
      - type: http
        url: "http://localhost:8080/health"
        interval: "10s"
        timeout: "5s"
        threshold: 3
        on_failure: restart

    config:
      image_pull_policy: "Always"
      server: "registry.company.com"
      username: "registry-user"
      password: "$REGISTRY_PASSWORD"

JSON form

The same shape, sent directly to the API:

{
  "name": "api",
  "namespace": "production",
  "runtime": "docker",
  "kind": "worker",
  "image": "registry.company.com/myapp:v1.2.3",
  "replicas": 3,
  "command": ["node", "server.js"],
  "environment": {
    "NODE_ENV": "production",
    "DATABASE_URL": { "secretRef": "database-url" }
  },
  "volumes": [
    {
      "type": "bind",
      "source": "/var/log/api",
      "destination": "/var/log/app",
      "driver": "local",
      "permission": "rw"
    }
  ],
  "ports": [
    { "published": 8080, "target": 8080 }
  ],
  "labels": { "app": "api" },
  "resources": {
    "limits": { "cpu": "1", "memory": "1Gi" },
    "requests": { "cpu": "200m", "memory": "256Mi" }
  },
  "health_checks": [
    {
      "type": "http",
      "url": "http://localhost:8080/health",
      "interval": "10s",
      "timeout": "5s",
      "threshold": 3,
      "on_failure": "restart"
    }
  ],
  "config": {
    "image_pull_policy": "Always"
  }
}

See also

• CLI → ring apply
• REST API → POST /deployments
• How-to: configure health checks
• How-to: deploy with secrets
• Health checks (design)