> ## Documentation Index > Fetch the complete documentation index at: https://docs.siderolabs.com/llms.txt > Use this file to discover all available pages before exploring further. # Extension Services > Use extension services in Talos Linux. export const VersionWarningBanner = () => { const latestVersion = "v1.13"; const [latestUrl, setLatestUrl] = useState(null); const [currentVersion, setCurrentVersion] = useState(null); const [isBeta, setIsBeta] = useState(false); const parseVersion = v => v.replace("v", "").split(".").map(Number); const isGreaterVersion = (a, b) => { const [aMajor, aMinor] = parseVersion(a); const [bMajor, bMinor] = parseVersion(b); if (aMajor > bMajor) return true; if (aMajor === bMajor && aMinor > bMinor) return true; return false; }; useEffect(() => { if (typeof window === "undefined") return; const {pathname, hash, search} = window.location; const match = pathname.match(/\/talos\/(v\d+\.\d+)\//); if (!match) return; const detectedVersion = match[1]; if (detectedVersion === latestVersion) return; setCurrentVersion(detectedVersion); if (isGreaterVersion(detectedVersion, latestVersion)) { setIsBeta(true); } const newPath = pathname.replace(`/talos/${detectedVersion}/`, `/talos/${latestVersion}/`); setLatestUrl(`${newPath}${search}${hash}`); }, []); if (!latestUrl || !currentVersion) return null; return
{isBeta ? <> ⚠️ You are viewing a beta version of Talos ({currentVersion}). This version may be unstable. View latest stable version {latestVersion} → : <> ⚠️ You are viewing an older version of Talos ({currentVersion}). View the latest version {latestVersion} → }
; }; Talos provides a way to run additional system services early in the Talos boot process. Extension services should be included into the Talos root filesystem (e.g. using [system extensions](./system-extensions)). Extension services run as privileged containers with ephemeral root filesystem located in the Talos root filesystem. Extension services can be used to extend core features of Talos in a way that is not possible via [static pods](../../configure-your-talos-cluster/images-container-runtime/static-pods) or Kubernetes DaemonSets. Potential extension services use-cases: * storage: Open iSCSI, software RAID, etc. * networking: BGP FRR, etc. * platform integration: VMWare open VM tools, etc. ## Configuration Talos on boot scans directory `/usr/local/etc/containers` for `*.yaml` files describing the extension services to run. Format of the extension service config: ```yaml theme={null} name: hello-world container: entrypoint: ./hello-world environment: - XDG_RUNTIME_DIR=/run args: - -f mounts: - # OCI Mount Spec depends: - configuration: true - service: cri - path: /run/machined/machined.sock - network: - addresses - connectivity - hostname - etcfiles - time: true restart: never|always|untilSuccess logToConsole: true|false ``` ### `name` Field `name` sets the service name, valid names are `[a-z0-9-_]+`. The service container root filesystem path is derived from the `name`: `/usr/local/lib/containers/`. The extension service will be registered as a Talos service under an `ext-` identifier. ### `container` * `entrypoint` defines the container entrypoint relative to the container root filesystem (`/usr/local/lib/containers/`) * `environmentFile` (**deprecated**) defines the path to a file containing environment variables, the service waits for the file to exist before starting. Use `ExtensionServiceConfig` instead. * `environment` defines the container environment variables. * `args` defines the additional arguments to pass to the entrypoint * `mounts` defines the volumes to be mounted into the container root #### `container.mounts` The section `mounts` uses the standard OCI spec: ```yaml theme={null} - source: /var/log/audit destination: /var/log/audit type: bind options: - rshared - bind - ro ``` All requested directories will be mounted into the extension service container mount namespace. If the `source` directory doesn't exist in the host filesystem, it will be created (only for writable paths in the Talos root filesystem). #### `container.security` The section `security` follows this example: ```yaml theme={null} maskedPaths: - "/should/be/masked" readonlyPaths: - "/path/that/should/be/readonly" - "/another/readonly/path" writeableRootfs: true writeableSysfs: true rootfsPropagation: shared ``` > * The rootfs is readonly by default unless `writeableRootfs: true` is set. > * The sysfs is readonly by default unless `writeableSysfs: true` is set. > * Masked paths if not set defaults to [containerd defaults](https://github.com/containerd/containerd/tree/main/pkg/oci/spec.go). > Masked paths will be mounted to `/dev/null`. > To set empty masked paths use: > > ```yaml theme={null} > container: > security: > maskedPaths: [] > ``` > > * Read Only paths if not set defaults to [containerd defaults](https://github.com/containerd/containerd/tree/main/pkg/oci/spec.go). > Read-only paths will be mounted to `/dev/null`. > To set empty read only paths use: > > ```yaml theme={null} > container: > security: > readonlyPaths: [] > ``` > > * Rootfs propagation is not set by default (container mounts are private). ### `depends` The `depends` section describes extension service start dependencies: the service will not be started until all dependencies are met. Available dependencies: * `service: `: wait for the service `` to be running and healthy * `path: `: wait for the `` to exist * `network: [addresses, connectivity, hostname, etcfiles]`: wait for the specified network readiness checks to succeed * `time: true`: wait for the NTP time sync * `configuration: true`: wait for `ExtensionServiceConfig` resource with a name matching the extension name to be available. The mounts specified in the `ExtensionServiceConfig` will be added as extra mounts to the extension service. ### `restart` Field `restart` defines the service restart policy, it allows to either configure an always running service or a one-shot service: * `always`: restart service always * `never`: start service only once and never restart * `untilSuccess`: restart failing service, stop restarting on successful run ### `logToConsole` Field `logToConsole` defines whether the service logs should also be written to the console, i.e., to kernel log buffer (or to the container logs in container mode). This feature is particularly useful for debugging extensions that operate in maintenance mode or early in the boot process when service logs cannot be accessed yet. ## Example Example layout of the Talos root filesystem contents for the extension service: ```text theme={null} / └── usr    └── local       ├── etc      │   └── containers       │     └── hello-world.yaml       └── lib           └── containers          └── hello-world          ├── hello └── config.ini ``` Talos discovers the extension service configuration in `/usr/local/etc/containers/hello-world.yaml`: ```yaml theme={null} name: hello-world container: entrypoint: ./hello args: - --config - config.ini depends: - network: - addresses restart: always ``` Talos starts the container for the extension service with container root filesystem at `/usr/local/lib/containers/hello-world`: ```text theme={null} / ├── hello └── config.ini ``` Extension service is registered as `ext-hello-world` in `talosctl services`: ```shell theme={null} $ talosctl service ext-hello-world NODE 172.20.0.5 ID ext-hello-world STATE Running HEALTH ? EVENTS [Running]: Started task ext-hello-world (PID 1100) for container ext-hello-world (2m47s ago) [Preparing]: Creating service runner (2m47s ago) [Preparing]: Running pre state (2m47s ago) [Waiting]: Waiting for service "containerd" to be "up" (2m48s ago) [Waiting]: Waiting for service "containerd" to be "up", network (2m49s ago) ``` An extension service can be started, restarted and stopped using `talosctl service ext-hello-world start|restart|stop`. Use `talosctl logs ext-hello-world` to get the logs of the service. Complete example of the extension service can be found in the [extensions repository](https://github.com/talos-systems/extensions/tree/main/examples/hello-world-service).