Skip to content

docs: add Talos Containers documentation - #897

Draft
Iheanacho-ai wants to merge 11 commits into
siderolabs:mainfrom
Iheanacho-ai:talos-containers
Draft

Iheanacho-ai wants to merge 11 commits into
siderolabs:mainfrom
Iheanacho-ai:talos-containers

Conversation

@Iheanacho-ai

Copy link
Copy Markdown
Member

What

Combines the Talos Containers navigation and pages into one PR to merge.

Why

Each page was reviewed in its own PR. The nav and link checks only pass once they are together.

Change

Merges:

Add Storage and Configuration Files (#884) is not included yet. It is blocked on talos#14740. The overview links to it, so validate-docs-nav and broken-links fail on that page only.

Part of #881

Testing

  • Ran: validate-docs-nav, check-missing-local, canonical-links-check, broken-links, and the docs.json check on the combined branch.
  • Result: everything passes except the missing storage page.

Add a how-to page to the v1.14 and v1.15 docs covering the network
modes of a ContainerConfig document: none, the default, and host.

Part of siderolabs#885

Signed-off-by: Amarachi Iheanacho <amarachi.iheanacho@siderolabs.com>
@mintlify

mintlify Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit e84e59b.

Approve preview

@github-project-automation github-project-automation Bot moved this to To Do in Planning Oct 29, 2026
@talos-bot talos-bot moved this from To Do to In Review in Planning Oct 29, 2026
@Iheanacho-ai Iheanacho-ai changed the title Talos containers docs: add Talos Containers documentation Oct 29, 2026
@github-actions

github-actions Bot commented Oct 29, 2026 •

Copy link
Copy Markdown

📋 Automated documentation review

⚠️ The reviewer did not finish on commit e84e59b (it timed out or errored) — see the workflow run log. This run did not produce a result; any findings from an earlier run on this PR still stand.

@Iheanacho-ai
Iheanacho-ai marked this pull request as draft October 29, 2026 08:47
@smira smira removed this from Planning Oct 29, 2026
@Iheanacho-ai
Iheanacho-ai force-pushed the talos-containers branch 2 times, most recently from d6f4d78 to f381b3c Compare November 4, 2026 08:04
Add a how-to page to the v1.14 and v1.15 docs covering CPU and memory
limits for a Talos Container. The v1.15 copy adds a swap limit for one
container and WorkloadResourceConfig for a combined memory limit on all
containers.

CPUPartitionConfig is left out: Talos records it, but nothing applies it
to the cgroups yet (tracked in #14535).

Part of siderolabs#885

Signed-off-by: Amarachi Iheanacho <amarachi.iheanacho@siderolabs.com>
Add a "Talos Containers" group to the v1.14 and v1.15 navigation, after
"Configure your Talos cluster".

Add Talos Containers to the product switcher and the docs homepage as a
link into that group. The pages live inside the Talos Linux versions, so
the product has no navigation of its own: the generator gains an `href`
field for such linked products, which Mintlify renders as a link in the
switcher. A linked product is left out of product-nav.js, where its url
segment would overwrite the entry of the product it links into.

The pages themselves land in separate pull requests, so the nav check
fails until they are combined with this branch.

Part of siderolabs#881

Signed-off-by: Amarachi Iheanacho <amarachi.iheanacho@siderolabs.com>
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 siderolabs#885

Signed-off-by: Amarachi Iheanacho <amarachi.iheanacho@siderolabs.com>
@Iheanacho-ai
Iheanacho-ai force-pushed the talos-containers branch 11 times, most recently from bafa055 to 44c6990 Compare November 16, 2026 14:01
@Iheanacho-ai
Iheanacho-ai force-pushed the talos-containers branch 5 times, most recently from 21ad019 to 56d7a2c Compare November 16, 2026 15:25
Add a how-to page to the v1.14 and v1.15 docs covering the dependsOn
field of a ContainerConfig document: waiting for host paths, network
readiness, time synchronization, and other containers.

Talos v1.14 accepts the containers condition and rejects cycles, but
does not wait for the other containers to start; v1.15 enforces it.
The v1.15 copy uses the renamed dependsOn.network field.

Part of siderolabs#885

Signed-off-by: Amarachi Iheanacho <amarachi.iheanacho@siderolabs.com>
Add the explanation page for Talos Containers to the v1.14 and v1.15
docs. It covers when to use Talos Containers instead of extension
services, static pods, or Kubernetes workloads, how Talos runs a
container, the container lifecycle, the security model, and the
current limitations.

Commands, status resources, image requirements, and field-level
security settings live on the other Talos Containers pages, so the
v1.14 and v1.15 copies are identical.

Closes siderolabs#882

Signed-off-by: Amarachi Iheanacho <amarachi.iheanacho@siderolabs.com>
Add a tutorial to the v1.14 and v1.15 docs that runs traefik/whoami as
a Talos Container. It declares the container in a ContainerConfig
document, applies it with talosctl patch, checks it with talosctl
containers, logs, and curl, updates the image tag, and removes the
document with a $patch: delete patch.

The tutorial uses whoami instead of the nginx example from the
reference because it runs under the default restricted profile as a
non-root user, with no capabilities and a read-only root filesystem.

The v1.15 copy also checks the container with ContainerStatus.

Closes siderolabs#883

Signed-off-by: Amarachi Iheanacho <amarachi.iheanacho@siderolabs.com>
Add a how-to page to the v1.14 and v1.15 docs for inspecting Talos
Containers with talosctl containers, logs, stats, image list, and
restart in the taloscontainers namespace, reading their status
resources, and fixing containers that never start, fail to pull their
image, or restart in a loop.

The two copies differ where the releases do. v1.14 reports status
through ContainerImageStatus, ContainerMountStatus, and
ContainerInstanceStatus, and shows unmet dependencies only in the
controller runtime log. v1.15 adds ContainerStatus,
ContainerDependencyStatus, and the dashboard Containers screen.

Closes siderolabs#886

Signed-off-by: Amarachi Iheanacho <amarachi.iheanacho@siderolabs.com>
Add a requirements page for Talos Containers to the v1.14 and v1.15
docs. It lists what the machine needs (Talos version, cluster
membership, disk space, optional user volumes), what the image and
registry need (architecture, registry access, signature policy), the
talosctl version and the minimum role for each operation, and that
Docker-based test clusters ignore CPU and memory limits.

The v1.15 copy notes that container status resources and dashboard
support need Talos 1.15.

Part of siderolabs#881

Signed-off-by: Amarachi Iheanacho <amarachi.iheanacho@siderolabs.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants