| Field | Type | Description | Value(s) |
|---|---|---|---|
name | string | Name of the container. Must be between 1 and 63 characters long, and can only contain lowercase ASCII letters, digits and hyphens. It is used as the containerd container ID and as the container’s log identifier, so it may not collide with a Talos service name. | |
image | string | OCI image reference supplying the container’s root filesystem. A digest-pinned reference ( repo@sha256:...) is recommended: it is the only formthat guarantees the same bytes on every pull. Short references are accepted and normalized, so nginx becomes index.docker.io/library/nginx:latest. | |
entrypoint | []string | Overrides the image’s ENTRYPOINT. Unset means the image’s own entrypoint is used. | |
args | []string | Overrides the image’s CMD. | |
workingDir | string | Overrides the image’s WORKDIR. | |
runAs | ContainerRunAs | Overrides the image’s USER uid and/or gid. There are no user namespaces, so a container running as uid 0 is root on the host. | |
environment | []string | Environment variables, in KEY=value form, merged over the image’s own ENV.Values are stored in the machine configuration verbatim, so treat anything put here as being as sensitive as the machine configuration itself. | |
mounts | ContainerMount | Filesystems to mount into the container. | |
security | ContainerSecurity | Security settings for the container. | |
network | ContainerNetwork | Network settings for the container. | |
resources | ContainerResources | Resource limits, applied as cgroup v2 settings. | |
dependsOn | ContainerDependsOn | Conditions which must be satisfied before the container is started. |
runAs
ContainerRunAs overrides the image’s user and group.| Field | Type | Description | Value(s) |
|---|---|---|---|
uid | int32 | UID to run the container’s entrypoint as. Unset means use the image’s own USER. There are no user namespaces, so uid 0 is host root. | |
gid | int32 | GID to run the container’s entrypoint as. Unset means use the image’s own USER. |
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.| Field | Type | Description | Value(s) |
|---|---|---|---|
userVolume | UserVolumeMount | Mount a user volume, referenced by the name of its UserVolumeConfig document.The volume is mounted from /var/mnt/<name> on the host. Declaring this mount alsomakes the container wait for the volume to be mounted before it starts. | |
tmpfs | TmpfsMount | Mount a tmpfs for scratch space. | |
hostPath | HostPathMount | Bind-mount a path from the host. The source must already exist; Talos will not create it. This is the widest of the three sources and the only one that can reach arbitrary host state. |
userVolume
UserVolumeMount mounts a user volume by name.| Field | Type | Description | Value(s) |
|---|---|---|---|
name | string | Name of the UserVolumeConfig document to mount. | |
destination | string | Absolute path inside the container’s mount namespace. | |
options | []string | Mount options. User volume mounts are read-only by default (ro). | rorwnoexecnosuidnodevnoatimerbindrshared |
tmpfs
TmpfsMount mounts a tmpfs.| Field | Type | Description | Value(s) |
|---|---|---|---|
destination | string | Absolute path inside the container’s mount namespace. | |
size | string | Size of the tmpfs, e.g. 64MiB. Empty means the kernel default. | |
options | []string | Mount options. Tmpfs mounts are writable by default (rw). |
hostPath
HostPathMount bind-mounts a host path.| Field | Type | Description | Value(s) |
|---|---|---|---|
source | string | Absolute path on the host. Must already exist. | |
destination | string | Absolute path inside the container’s mount namespace. | |
options | []string | Mount options. Host path mounts are read-only by default (ro). |
security
ContainerSecurity configures the container’s security posture.| Field | Type | Description | Value(s) |
|---|---|---|---|
profile | ContainerSecurityProfile | Security profile.restricted drops all capabilities, allows no device access, and mounts the rootfsand sysfs read-only. privileged grants all grantable capabilities and all devices,which is what extension services get implicitly. | restrictedprivileged |
capabilities | ContainerCapabilities | Linux capabilities to add or drop on top of the profile. |
capabilities
ContainerCapabilities adjusts the container’s Linux capabilities.| Field | Type | Description | Value(s) |
|---|---|---|---|
add | []string | Capabilities to grant, without the CAP_ prefix. | |
drop | []string | Capabilities to remove, without the CAP_ prefix. ALL removes every capability. |
network
ContainerNetwork configures the container’s network namespace.| Field | Type | Description | Value(s) |
|---|---|---|---|
mode | ContainerNetworkMode | Network mode.none gives the container its own empty network namespace with no host access.host shares the host network namespace, so the container sees every interface andcan bind any port. | nonehost |
resources
ContainerResources configures cgroup v2 resource limits.| Field | Type | Description | Value(s) |
|---|---|---|---|
limits | ContainerResourceLimits | Hard ceilings the container cannot exceed. |
limits
ContainerResourceLimits are hard ceilings.| Field | Type | Description | Value(s) |
|---|---|---|---|
cpu | string | CPU ceiling in millicores, mapped onto cgroup v2 cpu.max.1000m is one core. | |
memory | string | Memory ceiling, mapped onto cgroup v2 memory.max.Exceeding it OOM-kills the container. |
dependsOn
ContainerDependsOn gates container startup on external conditions.| Field | Type | Description | Value(s) |
|---|---|---|---|
paths | []string | Host paths which must exist before the container starts. Polled, so a path that never appears leaves the container waiting indefinitely. | |
networks | []string | Network readiness conditions which must be satisfied. | addressesconnectivityhostnameetcfiles |
time | bool | Whether the clock must be synchronized before the container starts. | |
containers | []string | Other containers, by document name, which must be running first. Cycles are rejected when the machine configuration is applied. |