---
title: "workloads"
summary: "The containers that are yours: their role, source, health, routing, prerequisites and container controls."
status: shipped
generated: true
read_when:
  - "Declaring an application, worker, daemon or job"
  - "Choosing between image, build and compose as a workload source"
  - "Setting replicas, resources, volumes, published ports or drain behaviour"
---

This page is generated from the same Go declarations the loader enforces, so it
cannot drift from what `ob validate` accepts.

## Fields on this page

`args` · `bind` · `build` · `command` · `compose` · `condition` · `container` · `context` · `cpus` · `cron` · `data_effect` · `dockerfile` · `domain` · `drain` · `driver` · `entrypoint` · `env` · `env_files` · `exec` · `extra_hosts` · `file` · `grace` · `health` · `host` · `hostname` · `http` · `image` · `init` · `interval` · `labels` · `logging` · `memory` · `middlewares` · `mode` · `name` · `needs` · `options` · `path` · `persistence` · `platform` · `port` · `protocol` · `provider` · `published_ports` · `pull` · `reference` · `registry` · `replicas` · `resources` · `retries` · `role` · `routes` · `schedule` · `scheme` · `signal` · `source` · `start_period` · `stdin_open` · `strategy` · `target` · `tcp` · `timezone` · `tls` · `tty` · `user` · `volumes` · `wait` · `when` · `within` · `working_dir`

## Reference

| Field | Type | Default | What it does |
| --- | --- | --- | --- |
| `<name>.build` | object | — | Build metadata for development. Production requires a resolved image supplied with --image. Also accepts a build context path. |
| `<name>.build.args` | map | — | Build arguments supplied by the external build system. |
| `<name>.build.context` | string | — | Repository-relative build context. Expects a path inside the repository, with no control character or shell metacharacter. |
| `<name>.build.dockerfile` | string | — | Repository-relative Dockerfile path. Expects a path inside the repository, with no control character or shell metacharacter. |
| `<name>.build.platform` | string | — | Target image platform for the external build. |
| `<name>.build.target` | string | — | Named Dockerfile stage to build. |
| `<name>.command` | list | — | Container command as a shell string or argument list. Also accepts a command line or argument list. |
| `<name>.compose` | string | — | Existing Compose service to adopt, as repository path#service. Expects a reference of the form path/to/compose.yaml#service. |
| `<name>.data_effect` | `none` · `migration` · `destructive` · `unknown` | — | Job data impact used by rollback and abort gates. |
| `<name>.domain` | string | — | Domain shorthand for one HTTPS route; requires port and cannot be combined with routes. |
| `<name>.drain` | object | — | Signal and timing used to remove a container from traffic before stopping it. |
| `<name>.drain.grace` | string | — | Maximum graceful-shutdown time before forced termination. Expects a duration such as 30s, 5m, 1h30m or 14d. |
| `<name>.drain.signal` | string | `TERM` | Signal sent to begin graceful shutdown. Expects a signal name such as TERM or QUIT. |
| `<name>.drain.wait` | string | — | Time allowed for the proxy to stop routing before shutdown begins. Expects a duration such as 30s, 5m, 1h30m or 14d. |
| `<name>.entrypoint` | list | — | Container entrypoint as a string or argument list. Also accepts an entrypoint or argument list. |
| `<name>.env` | map | — | Literal container environment values. Managed-service credential variables cannot be overridden. |
| `<name>.env_files` | list | — | Workload-specific ordered environment-file list. Replaces broader defaults when present. |
| `<name>.env_files[].file` `*` | string | — | Repository-relative environment file path. Expects a path inside the repository, with no control character or shell metacharacter. |
| `<name>.env_files[].provider` | `sops` | — | Decryptor used before staging the file. The supported encrypted provider is sops. |
| `<name>.extra_hosts` | list | — | Additional host-to-address entries added to the container. |
| `<name>.health` | object | — | Readiness check used to gate rolling replacement. Also accepts an HTTP health path. |
| `<name>.health.exec` | — | — | Health command as a shell string or direct argument list. |
| `<name>.health.http` | string | — | HTTP path probed inside the container. Expects a path beginning with /. |
| `<name>.health.interval` | string | — | Delay between container health probes. Expects a duration such as 30s, 5m, 1h30m or 14d. |
| `<name>.health.port` | integer | — | Container port probed by HTTP or TCP health checks. |
| `<name>.health.retries` | integer | — | Consecutive failed probes before the container is unhealthy. |
| `<name>.health.start_period` | string | — | Startup grace period before failed probes count. Expects a duration such as 30s, 5m, 1h30m or 14d. |
| `<name>.health.tcp` | boolean | `false` | Probe the configured port by opening a TCP connection. |
| `<name>.health.within` | string | — | Maximum time a rollout waits for readiness. Expects a duration such as 30s, 5m, 1h30m or 14d. |
| `<name>.hostname` | string | — | Hostname assigned inside the workload container. |
| `<name>.image` | object | — | Container image source, written as a reference string or an object. Also accepts an image reference. |
| `<name>.image.platform` | string | — | Platform selected when the image is multi-platform. |
| `<name>.image.pull` | `always` · `missing` · `never` | `missing` | Image pull policy: missing, always, or never. |
| `<name>.image.reference` | string | — | Complete container image reference, optionally tagged or digest-pinned. Expects a registry reference such as nginx:1.27 or ghcr.io/acme/app@sha256:…. |
| `<name>.image.registry` | string | — | Optional registry label retained in canonical configuration. Current authentication uses every top-level registries entry; this field does not select a login. |
| `<name>.init` | boolean | — | Run a minimal init process as PID 1 inside the container. |
| `<name>.labels` | map | — | Additional container labels outside namespaces reserved by Onebox and the proxy. |
| `<name>.logging` | object | — | Container logging driver and driver-specific options. |
| `<name>.logging.driver` | string | — | Container runtime logging driver. Expects a log driver name such as local, json-file or an org/plugin:tag. |
| `<name>.logging.options` | map | — | Driver-specific logging options passed to the container runtime. |
| `<name>.needs` | list | — | Workload or supporting-service prerequisites and optional connection-variable mappings. |
| `<name>.needs[].condition` | `started` · `healthy` · `completed` | — | Prerequisite condition: started, healthy, or completed. |
| `<name>.needs[].env` | map | — | Maps application environment-variable names to service connection parts such as host, port, user, password, database, or url. |
| `<name>.needs[].name` | string | — | Name of a workload or supporting service that must start first. Expects lower-case letters, digits and hyphens, starting with a letter, at most 40 characters. |
| `<name>.persistence` | object | — | Declares whether this workload holds data that must outlive releases. |
| `<name>.persistence.mode` | `durable` · `ephemeral` · `external` | `durable` | Data lifetime: durable, ephemeral, or external. |
| `<name>.port` | integer | — | Container port used with domain shorthand and as the default HTTP health port. |
| `<name>.published_ports` | list | — | Host ports published outside the proxy. They bind to loopback by default. A rolling workload cannot publish one, because two replicas cannot hold the same host port during a roll: set strategy: recreate, or route through the proxy instead. |
| `<name>.published_ports[].bind` | string | `127.0.0.1` | Host address on which the published port listens. |
| `<name>.published_ports[].container` | integer | — | Port receiving traffic inside the container. |
| `<name>.published_ports[].host` | integer | — | Port exposed on the host. |
| `<name>.published_ports[].protocol` | `tcp` · `udp` | `tcp` | Published transport protocol: tcp or udp. |
| `<name>.replicas` | integer | `1` | Desired number of long-running workload containers. |
| `<name>.resources` | object | — | Container memory and CPU limits. |
| `<name>.resources.cpus` | string | — | Container CPU limit expressed as a positive decimal count. Expects a number of CPUs such as 0.5 or 2. |
| `<name>.resources.memory` | string | — | Container memory limit. Expects a size such as 512MB or 1.5GB. |
| `<name>.role` | `application` · `worker` · `daemon` · `job` | — | Lifecycle role: application, worker, daemon, or job. |
| `<name>.routes` | list | — | Ingress routes exposed by this workload. |
| `<name>.routes[].domain` | string | — | DNS name matched by the proxy. |
| `<name>.routes[].entrypoint` | string | `websecure` | Named proxy listener used for the route. |
| `<name>.routes[].middlewares` | list | — | Ordered provider-qualified middleware references applied to this route. |
| `<name>.routes[].path` | string | `/` | URL path prefix matched by an HTTP route. Expects a path beginning with /. |
| `<name>.routes[].port` | integer | — | Container port receiving routed traffic. |
| `<name>.routes[].protocol` | `http` · `tcp` | `http` | Routing protocol: http, tcp, or udp. |
| `<name>.routes[].scheme` | `http` · `https` · `h2c` | `http` | Backend connection scheme: http, https, h2c, tcp, or udp. |
| `<name>.routes[].tls` | `terminate` · `passthrough` · `none` | `terminate` | TLS handling: terminate, passthrough, or none. |
| `<name>.schedule` | object | — | Host-resident recurring schedule for a job. |
| `<name>.schedule.cron` | string | — | Five-field cron schedule translated to a host timer. Expects five cron fields. |
| `<name>.schedule.timezone` | string | `UTC` | IANA timezone used to interpret the cron schedule. Expects an IANA zone name such as UTC or Europe/Berlin. |
| `<name>.stdin_open` | boolean | — | Keep standard input open for the container. |
| `<name>.strategy` | `rolling` · `recreate` | — | Release strategy. Defaults to rolling only for an application workload with health; all other workloads default to recreate. |
| `<name>.tty` | boolean | — | Allocate a pseudo-TTY for the container. |
| `<name>.user` | string | — | User or UID used to run the container process. |
| `<name>.volumes` | list | — | Managed named volumes or repository bind mounts. |
| `<name>.volumes[].mode` | `rw` · `ro` | `rw` | Mount access mode: rw or ro. |
| `<name>.volumes[].name` | string | — | Stable logical name of a Onebox-managed volume. Expects lower-case letters, digits and hyphens, starting with a letter, at most 40 characters. |
| `<name>.volumes[].path` | string | — | Absolute container path where the volume or bind mount is attached. Expects an absolute path with no control character or shell metacharacter. |
| `<name>.volumes[].source` | string | — | Repository-relative source path of a bind mount. |
| `<name>.when` | `pre_release` · `post_release` · `manual` | `manual` | When a job runs: manual, pre_release, or post_release. |
| `<name>.working_dir` | string | — | Absolute working directory for the container process. Expects an absolute path with no control character or shell metacharacter. |

`*` marks a field that is required within its own object.