Skip to main content
FieldTypeDescriptionValue(s)
namestringName 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.
imagestringOCI image reference supplying the container’s root filesystem.

A digest-pinned reference (repo@sha256:...) is recommended: it is the only form
that guarantees the same bytes on every pull. Short references are accepted and
normalized, so nginx becomes index.docker.io/library/nginx:latest.
entrypoint[]stringOverrides the image’s ENTRYPOINT.

Unset means the image’s own entrypoint is used.
args[]stringOverrides the image’s CMD.
workingDirstringOverrides the image’s WORKDIR.
runAsContainerRunAsOverrides 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[]stringEnvironment 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.
mountsContainerMountFilesystems to mount into the container.
securityContainerSecuritySecurity settings for the container.
networkContainerNetworkNetwork settings for the container.
resourcesContainerResourcesResource limits, applied as cgroup v2 settings.
dependsOnContainerDependsOnConditions which must be satisfied before the container is started.

runAs

ContainerRunAs overrides the image’s user and group.
FieldTypeDescriptionValue(s)
uidint32UID 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.
gidint32GID 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.
FieldTypeDescriptionValue(s)
userVolumeUserVolumeMountMount 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 also
makes the container wait for the volume to be mounted before it starts.
tmpfsTmpfsMountMount a tmpfs for scratch space.
hostPathHostPathMountBind-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.
FieldTypeDescriptionValue(s)
namestringName of the UserVolumeConfig document to mount.
destinationstringAbsolute path inside the container’s mount namespace.
options[]stringMount options. User volume mounts are read-only by default (ro).ro
rw
noexec
nosuid
nodev
noatime
rbind
rshared

tmpfs

TmpfsMount mounts a tmpfs.
FieldTypeDescriptionValue(s)
destinationstringAbsolute path inside the container’s mount namespace.
sizestringSize of the tmpfs, e.g. 64MiB. Empty means the kernel default.
options[]stringMount options. Tmpfs mounts are writable by default (rw).

hostPath

HostPathMount bind-mounts a host path.
FieldTypeDescriptionValue(s)
sourcestringAbsolute path on the host. Must already exist.
destinationstringAbsolute path inside the container’s mount namespace.
options[]stringMount options. Host path mounts are read-only by default (ro).

security

ContainerSecurity configures the container’s security posture.
FieldTypeDescriptionValue(s)
profileContainerSecurityProfileSecurity profile.

restricted drops all capabilities, allows no device access, and mounts the rootfs
and sysfs read-only. privileged grants all grantable capabilities and all devices,
which is what extension services get implicitly.
restricted
privileged
capabilitiesContainerCapabilitiesLinux capabilities to add or drop on top of the profile.

capabilities

ContainerCapabilities adjusts the container’s Linux capabilities.
FieldTypeDescriptionValue(s)
add[]stringCapabilities to grant, without the CAP_ prefix.
drop[]stringCapabilities to remove, without the CAP_ prefix. ALL removes every capability.

network

ContainerNetwork configures the container’s network namespace.
FieldTypeDescriptionValue(s)
modeContainerNetworkModeNetwork 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 and
can bind any port.
none
host

resources

ContainerResources configures cgroup v2 resource limits.
FieldTypeDescriptionValue(s)
limitsContainerResourceLimitsHard ceilings the container cannot exceed.

limits

ContainerResourceLimits are hard ceilings.
FieldTypeDescriptionValue(s)
cpustringCPU ceiling in millicores, mapped onto cgroup v2 cpu.max.

1000m is one core.
memorystringMemory ceiling, mapped onto cgroup v2 memory.max.

Exceeding it OOM-kills the container.

dependsOn

ContainerDependsOn gates container startup on external conditions.
FieldTypeDescriptionValue(s)
paths[]stringHost paths which must exist before the container starts.

Polled, so a path that never appears leaves the container waiting indefinitely.
networks[]stringNetwork readiness conditions which must be satisfied.addresses
connectivity
hostname
etcfiles
timeboolWhether the clock must be synchronized before the container starts.
containers[]stringOther containers, by document name, which must be running first.

Cycles are rejected when the machine configuration is applied.