Container labels

Reference of every kowan.* Docker label: configure auto-updates, scan gates, alerts, schedules and backups from a Compose file, and read the labels Kowan sets.

Kowan reads a few kowan.* labels from your containers, so you can configure updates, alerts, schedules and backups in a Compose file or a docker run command, without touching the UI. It also sets labels of its own on the containers and volumes it creates. This page lists both.

Labels you set

Put them on a service in a Compose file, or pass them with docker run --label. Kowan reads them from the running container, so recreate the container after changing a label.

services:
  web:
    image: nginx:1.27
    labels:
      kowan.update: apply
      kowan.update.window: "02:00-05:00 sat,sun"
      kowan.update.min-age: 2d
      kowan.scan.block: critical
  worker:
    image: ghcr.io/acme/worker:3.2
    labels:
      kowan.schedule.stop: "0 22 * * 1-5"
      kowan.schedule.start: "0 8 * * 1-5"
      kowan.schedule.timezone: Europe/Rome
      kowan.backup: "true"
  debug-tools:
    image: nicolaka/netshoot
    labels:
      kowan.notify: "off"

Quote values that YAML would otherwise read as a boolean or a number, such as "off" and "true".

Updates and alerts

A label wins over the policy set in the UI or the API, field by field: label, then stored policy, then global default. In the UI, a field set by a label shows a label badge and is read-only.

An invalid value is ignored and reported on the container's auto-update panel. An invalid kowan.update falls back to off, never to a more aggressive mode stored in the UI.

The containers of a deployment that has its own auto-update policy follow that policy, unless the container sets kowan.update itself.

Update modes

off

Nothing happens on its own. The Update badge and button keep working.

notify

When the registry has a newer image for the container's tag, Kowan raises an alert (the bell and your notification channels) once per new image.

pull

Kowan pulls the new image in advance, once per new image, and does not switch to it.

apply

Shown as Auto in the UI. Inside the window, and once the image is old enough, Kowan pulls it, runs the scan gate, recreates the container with the same configuration, checks that it stays healthy, and rolls back automatically if it does not. See Image updates.

Maintenance windows

Windows use the Kowan server's local time.

Scan gate

When the new image cannot be scanned, every value except never blocks the update.

Schedules

Kowan looks for these labels on every host every 5 minutes. They appear on the Schedules page as read-only schedules. An invalid cron expression or time zone shows the schedule with its error, and it never runs. A schedule you create in Kowan for the same host, container and action overrides the label, even when it is disabled: disabling it is how you silence a label without touching the container. See Schedules.

Runbooks

They appear in the workload's Runbooks tab, read-only. See Runbooks.

Crash snapshots and group schedules

Backups

Set it on a container or directly on a volume. The volumes are resolved again at each run. See Volume backups.

Labels Kowan sets

Kowan writes these labels on what it creates, and uses them to find its own resources. Do not set or change them by hand.

Compose deployments are recognized by their Compose project name (the com.docker.compose.project label), not by kowan.deployment.id. See Importing stacks.

Containers labeled kowan.support=true, kowan.role or kowan.volbackup.helper, like the Kowan server and agents themselves, are hidden from Workloads, the dashboard, Logs and search unless an admin turns on Kowan's own containers in Settings.

Kowan also reads one label it never sets: kowan.component=agent helps it find a host's agent container when it updates the agent, if that container has neither the usual name nor the official agent image.