From 4681ec79fbd04e86cce55c5dcc2baa726032c491 Mon Sep 17 00:00:00 2001 From: Amarachi Iheanacho Date: Mon, 26 Oct 2026 23:12:35 +0100 Subject: [PATCH] docs: add security page for Talos Containers Add a how-to page to the v1.14 and v1.15 docs covering the security side of a ContainerConfig document: the restricted and privileged profiles, adding and dropping capabilities, runAs, and Talos API access with machinedAccess. The machinedAccess section states what the setting does and what it does not: it mounts the machined socket and lets the container request any role, but the socket is owned by the apid user, so the container also needs runAs 50, DAC_OVERRIDE, or the privileged profile. Resource limits, networking, and startup order have their own pages. Part of #885 Signed-off-by: Amarachi Iheanacho --- .../talos-containers/configure-security.mdx | 134 ++++++++++++++++++ .../talos-containers/configure-security.mdx | 134 ++++++++++++++++++ 2 files changed, 268 insertions(+) create mode 100644 public/talos/v1.14/talos-containers/configure-security.mdx create mode 100644 public/talos/v1.15/talos-containers/configure-security.mdx diff --git a/public/talos/v1.14/talos-containers/configure-security.mdx b/public/talos/v1.14/talos-containers/configure-security.mdx new file mode 100644 index 00000000..ba58c444 --- /dev/null +++ b/public/talos/v1.14/talos-containers/configure-security.mdx @@ -0,0 +1,134 @@ +--- +title: "Configure Security for a Talos Container" +description: "Set the security profile, Linux capabilities, user, and Talos API access with machinedAccess for a Talos Container." +canonical: https://docs.siderolabs.com/talos/v1.14/talos-containers/configure-security +--- + +import { VersionWarningBanner } from "/snippets/version-warning-banner.jsx" + + + +Talos Containers do not use user namespaces, so root inside a container is also root on the host. +This page explains how to limit what a container can access on the host, through its security profile, the user it runs as, and its Linux capabilities, and how to give it access to the Talos API. +For more information, see the [`ContainerConfig` reference](../reference/configuration/container/containerconfig). + +## Choose a security profile + +The `security.profile` field sets the starting permissions of a container. + +Talos has two security profiles, which give a container the following permissions: + +- **`restricted`**: The default. The container has no Linux capabilities and no access to host devices. Its root filesystem and sysfs are read-only. +- **`privileged`**: The container has every capability except `SYS_BOOT` and `SYS_MODULE`, and can use any host device. Host device files are not added to the container's `/dev` automatically. Its root filesystem is writable, and sysfs stays read-only. These are the same permissions that extension services have. + + **Example:** The following document uses the `privileged` profile: + + ```yaml + apiVersion: v1alpha1 + kind: ContainerConfig + name: storage-agent + image: registry.example.com/storage-agent@sha256:... + security: + profile: privileged + ``` + +Both profiles also run the container with the `no_new_privs` flag and containerd's default seccomp profile. + +A container that needs only one or two capabilities can keep the `restricted` profile and add those capabilities instead, as described in [Add or drop Linux capabilities](#add-or-drop-linux-capabilities). + +## Run as a specific user + +The `runAs` field sets the uid and gid that the container's process runs as. +It overrides the image's `USER`. + +**Example:** The following document runs a container as uid and gid 65534: + +```yaml +apiVersion: v1alpha1 +kind: ContainerConfig +name: web +image: registry.example.com/web@sha256:... +runAs: + uid: 65534 + gid: 65534 +``` + +Without `runAs`, the container runs as the image's `USER`, or as root if the image sets none. + + +Talos only applies an image `USER` that is a number. +An image that names its user, such as `USER nginx`, runs as root, and Talos logs a warning. + + +## Add or drop Linux capabilities + +The `security.capabilities` field changes the Linux capabilities that the security profile grants. +Capabilities are written without the `CAP_` prefix, so `CAP_NET_ADMIN` is `NET_ADMIN`. + +The field has two lists: + +- **`add`**: Grants capabilities on top of the security profile. +- **`drop`**: Removes capabilities from the security profile. `ALL` removes every capability, so dropping `ALL` and adding one capability leaves only that capability. + +Added capabilities only work for a process that runs as root. +Talos does not set ambient capabilities, so a process that runs as any other user loses them when it starts. +The example below therefore assumes an image that runs as root. + +**Example:** The following document keeps the `restricted` profile and adds `NET_BIND_SERVICE`, which allows the container to listen on ports below 1024: + +```yaml +apiVersion: v1alpha1 +kind: ContainerConfig +name: web +image: registry.example.com/web@sha256:... +network: + mode: host +security: + capabilities: + add: + - NET_BIND_SERVICE +``` + +## Give a container access to the Talos API + +Containers that call the Talos API on their own machine, such as infrastructure agents, get access to it through the `security.machinedAccess` field. + + +A container with access to the Talos API can request any role, including `os:admin`, and so can control the whole machine. `machinedAccess` is intended only for containers that manage the machine. + + +Setting `machinedAccess: true` does three things: + +- It mounts the Talos API socket, `/system/run/machined/machine.sock`, into the container as read-only. +- It registers the container's process with the Talos API, which then accepts requests from the container with any role they ask for. +- When SELinux is enabled, it runs the container in an SELinux domain that is allowed to use the socket. + +The socket belongs to uid and gid 50, the user that `apid` runs as. +A container with only `machinedAccess` cannot open it, because the `restricted` profile grants no capability that bypasses file permissions. + +The container also needs one of the following: + +- **`runAs` with uid and gid 50**: The container's process owns the socket. +- **The `DAC_OVERRIDE` capability**: The container runs as root and can bypass file permissions. +- **The `privileged` profile**: The profile includes `DAC_OVERRIDE`. + +**Example:** The following document combines `machinedAccess` with `runAs`, so no extra capabilities are needed: + +```yaml +apiVersion: v1alpha1 +kind: ContainerConfig +name: infra-agent +image: registry.example.com/infra-agent@sha256:... +runAs: + uid: 50 + gid: 50 +security: + machinedAccess: true +``` + +## Next steps + +The following pages cover related topics: + +- **[How Talos Containers Work](./how-talos-containers-work)**: The security model behind these settings. +- **[Configure Resource Limits](./configure-resource-limits)**: How to limit the CPU and memory a container uses. diff --git a/public/talos/v1.15/talos-containers/configure-security.mdx b/public/talos/v1.15/talos-containers/configure-security.mdx new file mode 100644 index 00000000..ba58c444 --- /dev/null +++ b/public/talos/v1.15/talos-containers/configure-security.mdx @@ -0,0 +1,134 @@ +--- +title: "Configure Security for a Talos Container" +description: "Set the security profile, Linux capabilities, user, and Talos API access with machinedAccess for a Talos Container." +canonical: https://docs.siderolabs.com/talos/v1.14/talos-containers/configure-security +--- + +import { VersionWarningBanner } from "/snippets/version-warning-banner.jsx" + + + +Talos Containers do not use user namespaces, so root inside a container is also root on the host. +This page explains how to limit what a container can access on the host, through its security profile, the user it runs as, and its Linux capabilities, and how to give it access to the Talos API. +For more information, see the [`ContainerConfig` reference](../reference/configuration/container/containerconfig). + +## Choose a security profile + +The `security.profile` field sets the starting permissions of a container. + +Talos has two security profiles, which give a container the following permissions: + +- **`restricted`**: The default. The container has no Linux capabilities and no access to host devices. Its root filesystem and sysfs are read-only. +- **`privileged`**: The container has every capability except `SYS_BOOT` and `SYS_MODULE`, and can use any host device. Host device files are not added to the container's `/dev` automatically. Its root filesystem is writable, and sysfs stays read-only. These are the same permissions that extension services have. + + **Example:** The following document uses the `privileged` profile: + + ```yaml + apiVersion: v1alpha1 + kind: ContainerConfig + name: storage-agent + image: registry.example.com/storage-agent@sha256:... + security: + profile: privileged + ``` + +Both profiles also run the container with the `no_new_privs` flag and containerd's default seccomp profile. + +A container that needs only one or two capabilities can keep the `restricted` profile and add those capabilities instead, as described in [Add or drop Linux capabilities](#add-or-drop-linux-capabilities). + +## Run as a specific user + +The `runAs` field sets the uid and gid that the container's process runs as. +It overrides the image's `USER`. + +**Example:** The following document runs a container as uid and gid 65534: + +```yaml +apiVersion: v1alpha1 +kind: ContainerConfig +name: web +image: registry.example.com/web@sha256:... +runAs: + uid: 65534 + gid: 65534 +``` + +Without `runAs`, the container runs as the image's `USER`, or as root if the image sets none. + + +Talos only applies an image `USER` that is a number. +An image that names its user, such as `USER nginx`, runs as root, and Talos logs a warning. + + +## Add or drop Linux capabilities + +The `security.capabilities` field changes the Linux capabilities that the security profile grants. +Capabilities are written without the `CAP_` prefix, so `CAP_NET_ADMIN` is `NET_ADMIN`. + +The field has two lists: + +- **`add`**: Grants capabilities on top of the security profile. +- **`drop`**: Removes capabilities from the security profile. `ALL` removes every capability, so dropping `ALL` and adding one capability leaves only that capability. + +Added capabilities only work for a process that runs as root. +Talos does not set ambient capabilities, so a process that runs as any other user loses them when it starts. +The example below therefore assumes an image that runs as root. + +**Example:** The following document keeps the `restricted` profile and adds `NET_BIND_SERVICE`, which allows the container to listen on ports below 1024: + +```yaml +apiVersion: v1alpha1 +kind: ContainerConfig +name: web +image: registry.example.com/web@sha256:... +network: + mode: host +security: + capabilities: + add: + - NET_BIND_SERVICE +``` + +## Give a container access to the Talos API + +Containers that call the Talos API on their own machine, such as infrastructure agents, get access to it through the `security.machinedAccess` field. + + +A container with access to the Talos API can request any role, including `os:admin`, and so can control the whole machine. `machinedAccess` is intended only for containers that manage the machine. + + +Setting `machinedAccess: true` does three things: + +- It mounts the Talos API socket, `/system/run/machined/machine.sock`, into the container as read-only. +- It registers the container's process with the Talos API, which then accepts requests from the container with any role they ask for. +- When SELinux is enabled, it runs the container in an SELinux domain that is allowed to use the socket. + +The socket belongs to uid and gid 50, the user that `apid` runs as. +A container with only `machinedAccess` cannot open it, because the `restricted` profile grants no capability that bypasses file permissions. + +The container also needs one of the following: + +- **`runAs` with uid and gid 50**: The container's process owns the socket. +- **The `DAC_OVERRIDE` capability**: The container runs as root and can bypass file permissions. +- **The `privileged` profile**: The profile includes `DAC_OVERRIDE`. + +**Example:** The following document combines `machinedAccess` with `runAs`, so no extra capabilities are needed: + +```yaml +apiVersion: v1alpha1 +kind: ContainerConfig +name: infra-agent +image: registry.example.com/infra-agent@sha256:... +runAs: + uid: 50 + gid: 50 +security: + machinedAccess: true +``` + +## Next steps + +The following pages cover related topics: + +- **[How Talos Containers Work](./how-talos-containers-work)**: The security model behind these settings. +- **[Configure Resource Limits](./configure-resource-limits)**: How to limit the CPU and memory a container uses.