Talos Linux Documentation

Talos is a modern, secure, immutable, and minimal operating system designed specifically for running Kubernetes.

Key characteristics:

• API-Driven Management: All system management is performed via an API. There is no shell or interactive console available.
• Security: The attack surface is minimized through hardening and immutability. All API access is secured using mutual TLS (mTLS) authentication.
• Predictability: Employs immutable infrastructure principles to eliminate configuration drift and provides atomic updates.
• Evolvability: Designed to simplify architecture and provide current stable versions of Kubernetes and Linux.

The Signer API is a gRPC service that allows the Talos imager to delegate SecureBoot and PCR signing tasks to an out-of-process signer. This architecture enables the use of external hardware or specialized signing processes during image creation.

An example implementation using a YubiKey is available for reference.

Talos Linux is configured using a single YAML file known as the machine configuration. This file can contain multiple configuration documents separated by --- (three dashes) lines.

Document Types

• v1alpha1 document: This is the mandatory document containing the majority of configuration options. It uses a legacy structure.
• Named documents: Documents that include a name: field. You can include multiple named documents in a single file as long as each has a unique name.
• Unnamed documents: Documents without a name: field. You can only include one unnamed document per configuration file.

Standard Document Fields

Except for the v1alpha1 document, all other configuration documents must follow this schema:

apiVersion: v1alpha1 # version of the document
kind: NetworkRuleConfig # type of document
name: rule1 # only for named documents

You can suppress specific loglinter issues using comments. The comment must be on the same line or the immediately preceding line.

Single rule suppression

// loglint:ignore <rule_name> <reason>
log.Printf("allowed here")

Multiple rule suppression

Separate rules with a comma:

// loglint:ignore rule1,rule2 reason

Suppress all rules

Use all to suppress every rule for the line:

// loglint:ignore all reason

Before using the cloud-image-uploader, you must pre-create the vmimport IAM role in AWS. This requires creating the role with a specific trust policy and then attaching the necessary permissions policy.

Ensure you have the trust-policy.json and role-policy.json files available in your working directory before running these commands.

aws iam create-role --role-name vmimport --assume-role-policy-document file://trust-policy.json
aws iam put-role-policy --role-name vmimport --policy-name vmimport --policy-document file://role-policy.json

Use VolumeConfig to manage system volume configurations. Supported volume names are STATE, EPHEMERAL, IMAGECACHE, ETCD, CRI, KUBELET, and LOG.

Important Note: The ETCD, CRI, KUBELET, and LOG volumes default to a directory under EPHEMERAL. They can be placed on a dedicated partition by specifying provisioning. This choice (directory vs. dedicated partition) can only be made at cluster creation time; changing it on an already-provisioned node is not supported.

apiVersion: v1alpha1
kind: VolumeConfig
name: EPHEMERAL

To enable autocompletion for the bash shell, you must have the bash-completion package installed.

To load completions in your current session:

source <(talosctl completion bash)

To persist completions for every new session:

Linux:

talosctl completion bash > /etc/bash_completion.d/talosctl

macOS:

talosctl completion bash > $(brew --prefix)/etc/bash_completion.d/talosctl

Note: You will need to start a new shell for the setup to take effect.

If you have questions, bugs, or feature requests, or want to join the community, use the following channels:

• GitHub Discussions: For technical questions, bugs, and feature requests.
• Slack: Join the Talos community Slack channel. Note that you must request access via inviter.co.
• Twitter: Follow @SideroLabs.
• Office Hours: Monthly meetings held on the second Monday of every month at 16:30 UTC via Google Meet.

To use loglinter, add it to the linters.enable list and define it under linters.settings.custom as a module type.

Example configuration:

version: "2"

linters:
  enable:
    - loglinter
  settings:
    custom:
      loglinter:
        type: module
        description: checks logging conventions
        settings:
          exclude:
            - "**/*_test.go"
            - "_out/**"
            - "vendor/**"
          rules:
            slog_imports:
              allow:
                - "internal/app/machined/pkg/runtime/v1alpha1/platform/vmware/vmware_supported.go"

These parameters allow providing the initial machine configuration directly on the kernel command line. This is suitable for small configuration documents due to the ~2000 byte kernel command line limit.

Loading Order:

1. Persisted configuration from STATE partition (if exists).
2. talos.config.early.
3. Platform-specific source (e.g., talos.config for metal).
4. talos.config.inline.

Format: The configuration must be zstd compressed and base64-encoded.

Example (preparing a config):

cat config.yaml | zstd --compress --ultra -22 | base64 -w 0