> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siderolabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ContainerConfig is a container configuration document.
ContainerConfig declares a container to be run by Talos directly, without Kubernetes.

The container is started as soon as the configuration is applied, with no image rebuild
and no reboot. It runs against the CRI containerd instance in the dedicated
`taloscontainers` namespace, and is restarted automatically 5 seconds after it stops.

Containers are not Talos services: they do not appear in `talosctl services`, and
`talosctl service` does not apply to them. Status is reported via `ContainerStatus`.


# ContainerConfig

```yaml theme={null}
apiVersion: v1alpha1
kind: ContainerConfig
name: nginx # Name of the container.
image: docker.io/library/nginx:1.27 # OCI image reference supplying the container's root filesystem.
# Environment variables, in `KEY=value` form, merged over the image's own ENV.
environment:
    - NGINX_PORT=8080
# Filesystems to mount into the container.
mounts:
    - # Mount a user volume, referenced by the name of its `UserVolumeConfig` document.
      userVolume:
        name: web-content # Name of the `UserVolumeConfig` document to mount.
        destination: /usr/share/nginx/html # Absolute path inside the container's mount namespace.
        # Mount options. User volume mounts are read-only by default (`ro`).
        options:
            - ro
    - # Mount a tmpfs for scratch space.
      tmpfs:
        destination: /tmp # Absolute path inside the container's mount namespace.
        size: 64MiB # Size of the tmpfs, e.g. `64MiB`. Empty means the kernel default.
# Resource limits, applied as cgroup v2 settings.
resources:
    # Hard ceilings the container cannot exceed.
    limits:
        cpu: 1500m # CPU ceiling in millicores, mapped onto cgroup v2 `cpu.max`.
        memory: 512MiB # Memory ceiling, mapped onto cgroup v2 `memory.max`.
# Conditions which must be satisfied before the container is started.
dependsOn:
    # Network readiness conditions which must be satisfied.
    networks:
        - addresses

    # # Host paths which must exist before the container starts.
    # paths:
    #     - /var/mnt/web-content
```

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
      <th>Value(s)</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`name`</td>
      <td>string</td>
      <td>Name of the container.<br /><br />Must be between 1 and 63 characters long, and can only contain lowercase ASCII<br />letters, digits and hyphens. It is used as the containerd container ID and as the<br />container's log identifier, so it may not collide with a Talos service name.</td>

      <td />
    </tr>

    <tr>
      <td>`image`</td>
      <td>string</td>
      <td>OCI image reference supplying the container's root filesystem.<br /><br />A digest-pinned reference (`repo@sha256:...`) is recommended: it is the only form<br />that guarantees the same bytes on every pull. Short references are accepted and<br />normalized, so `nginx` becomes `index.docker.io/library/nginx:latest`.</td>

      <td />
    </tr>

    <tr>
      <td>`entrypoint`</td>
      <td>\[]string</td>
      <td>Overrides the image's ENTRYPOINT.<br /><br />Unset means the image's own entrypoint is used.</td>

      <td />
    </tr>

    <tr>
      <td>`args`</td>
      <td>\[]string</td>
      <td>Overrides the image's CMD.</td>

      <td />
    </tr>

    <tr>
      <td>`workingDir`</td>
      <td>string</td>
      <td>Overrides the image's WORKDIR.</td>

      <td />
    </tr>

    <tr>
      <td>`runAs`</td>
      <td><a href="#runas">ContainerRunAs</a></td>
      <td>Overrides the image's USER uid and/or gid.<br /><br />There are no user namespaces, so a container running as uid 0 is root on the host.</td>

      <td />
    </tr>

    <tr>
      <td>`environment`</td>
      <td>\[]string</td>
      <td>Environment variables, in `KEY=value` form, merged over the image's own ENV.<br /><br />Values are stored in the machine configuration verbatim, so treat anything put here<br />as being as sensitive as the machine configuration itself.</td>

      <td />
    </tr>

    <tr>
      <td>`mounts`</td>
      <td><a href="#mounts%5B%5D">ContainerMount</a></td>
      <td>Filesystems to mount into the container.</td>

      <td />
    </tr>

    <tr>
      <td>`security`</td>
      <td><a href="#security">ContainerSecurity</a></td>
      <td>Security settings for the container.</td>

      <td />
    </tr>

    <tr>
      <td>`network`</td>
      <td><a href="#network">ContainerNetwork</a></td>
      <td>Network settings for the container.</td>

      <td />
    </tr>

    <tr>
      <td>`resources`</td>
      <td><a href="#resources">ContainerResources</a></td>
      <td>Resource limits, applied as cgroup v2 settings.</td>

      <td />
    </tr>

    <tr>
      <td>`dependsOn`</td>
      <td><a href="#dependson">ContainerDependsOn</a></td>
      <td>Conditions which must be satisfied before the container is started.</td>

      <td />
    </tr>
  </tbody>
</table>

## runAs

ContainerRunAs overrides the image's user and group.

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
      <th>Value(s)</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`uid`</td>
      <td>int32</td>
      <td>UID to run the container's entrypoint as.<br /><br />Unset means use the image's own USER. There are no user namespaces, so uid 0 is host<br />root.</td>

      <td />
    </tr>

    <tr>
      <td>`gid`</td>
      <td>int32</td>
      <td>GID to run the container's entrypoint as.<br /><br />Unset means use the image's own USER.</td>

      <td />
    </tr>
  </tbody>
</table>

## mounts\[]

ContainerMount describes a single filesystem to mount into the container.

Exactly one source must be set. Raw OCI mounts are deliberately not exposed; every source is
typed so that Talos can reason about what a container is allowed to reach.

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
      <th>Value(s)</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`userVolume`</td>
      <td><a href="#uservolume">UserVolumeMount</a></td>
      <td>Mount a user volume, referenced by the name of its `UserVolumeConfig` document.<br /><br />The volume is mounted from `/var/mnt/<name>` on the host. Declaring this mount also<br />makes the container wait for the volume to be mounted before it starts.</td>

      <td />
    </tr>

    <tr>
      <td>`tmpfs`</td>
      <td><a href="#tmpfs">TmpfsMount</a></td>
      <td>Mount a tmpfs for scratch space.</td>

      <td />
    </tr>

    <tr>
      <td>`hostPath`</td>
      <td><a href="#hostpath">HostPathMount</a></td>
      <td>Bind-mount a path from the host.<br /><br />The source must already exist; Talos will not create it. This is the widest of the<br />three sources and the only one that can reach arbitrary host state.</td>

      <td />
    </tr>
  </tbody>
</table>

### userVolume

UserVolumeMount mounts a user volume by name.

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
      <th>Value(s)</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`name`</td>
      <td>string</td>
      <td>Name of the `UserVolumeConfig` document to mount.</td>

      <td />
    </tr>

    <tr>
      <td>`destination`</td>
      <td>string</td>
      <td>Absolute path inside the container's mount namespace.</td>

      <td />
    </tr>

    <tr>
      <td>`options`</td>
      <td>\[]string</td>
      <td>Mount options. User volume mounts are read-only by default (`ro`).</td>
      <td>`ro`<br />`rw`<br />`noexec`<br />`nosuid`<br />`nodev`<br />`noatime`<br />`rbind`<br />`rshared`<br /></td>
    </tr>
  </tbody>
</table>

### tmpfs

TmpfsMount mounts a tmpfs.

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
      <th>Value(s)</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`destination`</td>
      <td>string</td>
      <td>Absolute path inside the container's mount namespace.</td>

      <td />
    </tr>

    <tr>
      <td>`size`</td>
      <td>string</td>
      <td>Size of the tmpfs, e.g. `64MiB`. Empty means the kernel default.</td>

      <td />
    </tr>

    <tr>
      <td>`options`</td>
      <td>\[]string</td>
      <td>Mount options. Tmpfs mounts are writable by default (`rw`).</td>

      <td />
    </tr>
  </tbody>
</table>

### hostPath

HostPathMount bind-mounts a host path.

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
      <th>Value(s)</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`source`</td>
      <td>string</td>
      <td>Absolute path on the host. Must already exist.</td>

      <td />
    </tr>

    <tr>
      <td>`destination`</td>
      <td>string</td>
      <td>Absolute path inside the container's mount namespace.</td>

      <td />
    </tr>

    <tr>
      <td>`options`</td>
      <td>\[]string</td>
      <td>Mount options. Host path mounts are read-only by default (`ro`).</td>

      <td />
    </tr>
  </tbody>
</table>

## security

ContainerSecurity configures the container's security posture.

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
      <th>Value(s)</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`profile`</td>
      <td>ContainerSecurityProfile</td>
      <td>Security profile.<br /><br />`restricted` drops all capabilities, allows no device access, and mounts the rootfs<br />and sysfs read-only. `privileged` grants all grantable capabilities and all devices,<br />which is what extension services get implicitly.</td>
      <td>`restricted`<br />`privileged`<br /></td>
    </tr>

    <tr>
      <td>`capabilities`</td>
      <td><a href="#capabilities">ContainerCapabilities</a></td>
      <td>Linux capabilities to add or drop on top of the profile.</td>

      <td />
    </tr>
  </tbody>
</table>

### capabilities

ContainerCapabilities adjusts the container's Linux capabilities.

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
      <th>Value(s)</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`add`</td>
      <td>\[]string</td>
      <td>Capabilities to grant, without the `CAP_` prefix.</td>

      <td />
    </tr>

    <tr>
      <td>`drop`</td>
      <td>\[]string</td>
      <td>Capabilities to remove, without the `CAP_` prefix. `ALL` removes every capability.</td>

      <td />
    </tr>
  </tbody>
</table>

## network

ContainerNetwork configures the container's network namespace.

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
      <th>Value(s)</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`mode`</td>
      <td>ContainerNetworkMode</td>
      <td>Network mode.<br /><br />`none` gives the container its own empty network namespace with no host access.<br />`host` shares the host network namespace, so the container sees every interface and<br />can bind any port.</td>
      <td>`none`<br />`host`<br /></td>
    </tr>
  </tbody>
</table>

## resources

ContainerResources configures cgroup v2 resource limits.

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
      <th>Value(s)</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`limits`</td>
      <td><a href="#limits">ContainerResourceLimits</a></td>
      <td>Hard ceilings the container cannot exceed.</td>

      <td />
    </tr>
  </tbody>
</table>

### limits

ContainerResourceLimits are hard ceilings.

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
      <th>Value(s)</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`cpu`</td>
      <td>string</td>
      <td>CPU ceiling in millicores, mapped onto cgroup v2 `cpu.max`.<br /><br />`1000m` is one core.</td>

      <td />
    </tr>

    <tr>
      <td>`memory`</td>
      <td>string</td>
      <td>Memory ceiling, mapped onto cgroup v2 `memory.max`.<br /><br />Exceeding it OOM-kills the container.</td>

      <td />
    </tr>
  </tbody>
</table>

## dependsOn

ContainerDependsOn gates container startup on external conditions.

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
      <th>Value(s)</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`paths`</td>
      <td>\[]string</td>
      <td>Host paths which must exist before the container starts.<br /><br />Polled, so a path that never appears leaves the container waiting indefinitely.</td>

      <td />
    </tr>

    <tr>
      <td>`networks`</td>
      <td>\[]string</td>
      <td>Network readiness conditions which must be satisfied.</td>
      <td>`addresses`<br />`connectivity`<br />`hostname`<br />`etcfiles`<br /></td>
    </tr>

    <tr>
      <td>`time`</td>
      <td>bool</td>
      <td>Whether the clock must be synchronized before the container starts.</td>

      <td />
    </tr>

    <tr>
      <td>`containers`</td>
      <td>\[]string</td>
      <td>Other containers, by document name, which must be running first.<br /><br />Cycles are rejected when the machine configuration is applied.</td>

      <td />
    </tr>
  </tbody>
</table>