From dcd071febbe9f57b26e7d0300104dd5882b46128 Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Sat, 18 Jul 2026 19:35:23 -0500 Subject: [PATCH 1/5] add Talos Linux reference --- docs/kubernetes-platforms/talos-linux.md | 485 +++++++++++++++++++++++ 1 file changed, 485 insertions(+) create mode 100644 docs/kubernetes-platforms/talos-linux.md diff --git a/docs/kubernetes-platforms/talos-linux.md b/docs/kubernetes-platforms/talos-linux.md new file mode 100644 index 0000000..94ee6ed --- /dev/null +++ b/docs/kubernetes-platforms/talos-linux.md @@ -0,0 +1,485 @@ +# Talos Linux Cheat Sheet + +> **Applies to:** Talos Linux 1.13 and `talosctl` 1.13 +> **Last reviewed:** 2026-07-18 + +A practical operational reference for installing, configuring, inspecting, upgrading, backing up, and recovering Kubernetes nodes running Talos Linux. + +> [!WARNING] +> Talos is managed through its API rather than SSH. Always verify the active `talosconfig` context, endpoints, target nodes, cluster identity, and control-plane quorum before applying configuration, upgrading, resetting, or recovering a node. + +## What Talos Linux is + +Talos Linux is an immutable, API-managed operating system designed specifically for Kubernetes. + +Key characteristics: + +- no SSH server or interactive package-management workflow; +- declarative machine configuration; +- management through the Talos API and `talosctl`; +- minimal userspace and reduced mutable surface area; +- containerd and Kubernetes components managed as system services; +- support for bare metal, virtual machines, cloud platforms, edge systems, and local test clusters. + +Talos Linux is the node operating system. Kubernetes is the orchestrator running on top of it. [Omni](omni.md) is an optional management platform above Talos and Kubernetes. + +## Core objects + +| Object | Purpose | +|---|---| +| Machine configuration | Declarative operating-system and Kubernetes-node configuration | +| `talosconfig` | Client contexts, API endpoints, node targets, and credentials | +| Endpoint | Talos API address used by `talosctl` to reach the cluster | +| Node | Machine targeted by a command; commonly supplied with `--nodes` or `-n` | +| Control plane | Kubernetes API and etcd nodes | +| Worker | Kubernetes workload node without control-plane components | +| Maintenance mode | Pre-configuration API state used during installation or recovery | +| Image Factory schematic | Content-addressed image customization definition | +| System extension | Additional supported firmware, drivers, or services included in Talos images | + +## Install `talosctl` + +macOS or Linux with Homebrew: + +```bash +brew install siderolabs/tap/talosctl +``` + +Verify the client: + +```bash +talosctl version --client +talosctl --help +``` + +Keep the `talosctl` client version aligned with the Talos version being operated, especially while generating machine configurations or performing upgrades. + +## Inspect client context before operating + +```bash +talosctl config contexts +talosctl config info +talosctl config context +talosctl config endpoint +talosctl config node +``` + +Override context targets for one command: + +```bash +talosctl --context \ + --endpoints \ + --nodes \ + version +``` + +> [!CAUTION] +> Endpoints and nodes are different. Endpoints are API entry points; nodes are the machines the request acts on. Avoid leaving a destructive command dependent on an old default node list. + +## Local disposable cluster + +Create a local Docker-backed Talos cluster: + +```bash +talosctl cluster create docker +kubectl get nodes -o wide +``` + +Inspect a local node: + +```bash +talosctl dashboard --nodes +``` + +Destroy the disposable cluster: + +```bash +talosctl cluster destroy +``` + +Do not treat the local Docker quickstart as a production architecture reference. + +## Standalone cluster lifecycle + +A normal standalone deployment follows this sequence: + +1. Boot each machine with Talos installation media. +2. Generate control-plane, worker, and client configurations. +3. Apply the machine configuration to each node. +4. Configure `talosctl` endpoints and node targets. +5. Bootstrap etcd exactly once on one control-plane node. +6. Retrieve kubeconfig and verify Kubernetes health. + +Generate machine configurations: + +```bash +talosctl machineconfig gen \ + \ + https://:6443 \ + --output-dir ./generated +``` + +Validate before applying: + +```bash +talosctl validate \ + --config ./generated/controlplane.yaml \ + --mode metal \ + --strict +``` + +Apply to a machine in maintenance mode: + +```bash +talosctl apply-config \ + --insecure \ + --nodes \ + --file ./generated/controlplane.yaml +``` + +Bootstrap one control-plane node: + +```bash +talosctl bootstrap --nodes +``` + +Retrieve Kubernetes credentials: + +```bash +talosctl kubeconfig ./kubeconfig +KUBECONFIG=./kubeconfig kubectl get nodes -o wide +``` + +> [!DANGER] +> Bootstrap is a one-time cluster operation. Do not run it again on an already bootstrapped cluster unless performing a documented recovery procedure. + +## Read-only health checks + +Start with these commands before changing a node: + +```bash +talosctl version +talosctl health +talosctl dashboard +talosctl services +talosctl get members +talosctl get machines +talosctl etcd members +talosctl etcd status +kubectl get nodes -o wide +kubectl get pods --all-namespaces +``` + +Some resources or columns vary by Talos release. Use discovery commands when needed: + +```bash +talosctl get rd +talosctl get --output yaml +``` + +## Services, logs, and support bundles + +List service state: + +```bash +talosctl services +``` + +Inspect service logs: + +```bash +talosctl logs kubelet +talosctl logs containerd +talosctl logs etcd +talosctl logs kubelet --follow +``` + +Inspect kernel messages: + +```bash +talosctl dmesg +talosctl dmesg --follow +``` + +Collect a support archive: + +```bash +talosctl support \ + --nodes , \ + --output talos-support.zip +``` + +Support bundles can contain network topology, workload metadata, logs, and infrastructure details. Sanitize them before sharing outside the organization. + +## Inspect configuration and runtime resources + +```bash +talosctl get machineconfig --output yaml +talosctl get machinestatus +talosctl get nodename +talosctl get links +talosctl get addresses +talosctl get routes +talosctl get extensions +talosctl mounts +talosctl usage +talosctl processes +talosctl netstat +``` + +Resource names can change as APIs evolve. Use `talosctl get rd` to identify current resource definitions. + +## Patch machine configuration + +Preview a configuration application: + +```bash +talosctl apply-config \ + --nodes \ + --file \ + --dry-run +``` + +Patch a node from a YAML patch: + +```bash +talosctl patch machineconfig \ + --nodes \ + --patch @ +``` + +Apply a complete reviewed configuration: + +```bash +talosctl apply-config \ + --nodes \ + --file +``` + +Useful application modes include `auto`, `no-reboot`, `reboot`, `staged`, and `try`. + +```bash +talosctl apply-config \ + --nodes \ + --file \ + --mode try \ + --timeout 2m +``` + +> [!WARNING] +> A machine configuration is the source of truth for the node. Avoid interactive one-off edits that are not reflected in Git or the configuration-generation workflow. + +## Image Factory and system extensions + +Talos Image Factory generates customized installation assets from a content-addressed schematic. + +Common customizations include: + +- supported system extensions; +- firmware and microcode; +- kernel arguments; +- platform overlays; +- ISO, PXE, disk, UKI, and installer images; +- Secure Boot assets. + +Inspect the installed schematic and extensions: + +```bash +talosctl get extensions +``` + +A typical upgrade image follows this pattern: + +```text +factory.talos.dev/metal-installer/: +``` + +Use the same intended schematic across installation media and the installer image so nodes do not unexpectedly lose required extensions during installation or upgrade. + +## Upgrade Talos Linux + +Before upgrading: + +```bash +talosctl health +talosctl etcd members +talosctl etcd status +kubectl get nodes -o wide +kubectl get pods --all-namespaces +``` + +Upgrade one node with an Image Factory installer: + +```bash +talosctl upgrade \ + --nodes \ + --image factory.talos.dev/metal-installer/: +``` + +Operational sequence: + +1. Confirm the supported upgrade path. +2. Confirm a recent etcd backup. +3. Upgrade one control-plane node at a time. +4. Wait for the node, etcd, and Kubernetes to become healthy. +5. Continue with remaining control-plane nodes. +6. Upgrade workers in controlled batches. +7. Run a full post-upgrade validation. + +> [!DANGER] +> Never upgrade multiple control-plane nodes simultaneously without proving that etcd quorum remains available. + +## Upgrade Kubernetes + +```bash +talosctl upgrade-k8s \ + --nodes \ + --to +``` + +Review compatibility between the current Talos release and the target Kubernetes release before starting. Validate API health, node readiness, system pods, admission webhooks, networking, storage, and critical workloads afterward. + +## etcd inspection and backup + +Inspect members and status: + +```bash +talosctl etcd members +talosctl etcd status --nodes ,, +``` + +Create a snapshot from a healthy control-plane node: + +```bash +talosctl etcd snapshot ./etcd-$(date +%Y%m%d-%H%M%S).snapshot \ + --nodes +``` + +Store snapshots outside the cluster, protect them as sensitive data, and test the recovery process. + +## Recover etcd from a snapshot + +Recovery is a planned disaster-recovery operation, not a routine repair command. + +```bash +talosctl bootstrap \ + --nodes \ + --recover-from ./etcd.snapshot +``` + +Before recovery: + +- confirm the snapshot belongs to the intended cluster; +- preserve machine configurations and secrets; +- understand whether surviving etcd members must be reset; +- use console access; +- follow the recovery procedure for the exact Talos version. + +> [!DANGER] +> Incorrect etcd recovery can permanently replace newer cluster state or create split-brain conditions. + +## Reboot, shutdown, and rollback + +```bash +talosctl reboot --nodes +talosctl shutdown --nodes +talosctl rollback --nodes +``` + +Use forced reboot or shutdown modes only when graceful teardown is impossible and the effect on workloads and etcd is understood. + +## Reset a node + +Inspect first: + +```bash +kubectl get node -o wide +talosctl etcd members +talosctl get disks --nodes +``` + +Reset a machine: + +```bash +talosctl reset --nodes +``` + +Reset selected Talos partitions instead of every disk: + +```bash +talosctl reset \ + --nodes \ + --system-labels-to-wipe STATE \ + --system-labels-to-wipe EPHEMERAL +``` + +> [!DANGER] +> `talosctl reset` is destructive. The default reset can wipe the machine, remove it from Kubernetes, and remove it from etcd. Cloud VMs may become unbootable when their system disk is wiped. + +## Secure Boot and disk encryption + +Talos supports Secure Boot using signed Unified Kernel Images and can use TPM-backed LUKS2 keys for system-volume encryption. + +Verify Secure Boot state: + +```bash +talosctl get securitystate --nodes +``` + +Operational cautions: + +- switching a non-UKI installation to Secure Boot may require reinstallation; +- preserve signing and PCR-policy keys when using custom Secure Boot assets; +- TPM policy changes can affect volume unlock; +- encryption settings commonly apply during initial volume provisioning, not retroactively; +- maintain tested recovery procedures before enabling encryption broadly. + +## Networking and KubeSpan + +Talos networking is declared in machine configuration and exposed through API resources. + +```bash +talosctl get links +talosctl get addresses +talosctl get routes +talosctl get resolvers +talosctl get time +``` + +KubeSpan can provide encrypted node-to-node connectivity across networks. Treat it as part of the cluster design: document address selection, discovery dependencies, MTU, routing, failure behavior, and observability. + +## Troubleshooting workflow + +1. Confirm the active context, endpoints, and node targets. +2. Check physical or virtual console state. +3. Run `talosctl version`, `health`, `services`, and `dashboard`. +4. Inspect `dmesg` and the relevant service logs. +5. Verify network addresses, routes, DNS, and time synchronization. +6. Check etcd membership and quorum on control-plane nodes. +7. Check Kubernetes nodes and system pods. +8. Compare the running machine configuration with the intended configuration. +9. Collect a support bundle before destructive repair. +10. Apply the least disruptive documented recovery action. + +## Common failure patterns + +| Symptom | Checks | +|---|---| +| `talosctl` cannot connect | Context, endpoint reachability, TCP 50000, certificate validity, Omni ownership | +| Node in maintenance mode | Installation media, missing or rejected machine configuration, disk state | +| Kubernetes API unavailable | Control-plane services, etcd quorum, API endpoint or load balancer | +| Worker remains `NotReady` | Kubelet logs, CNI, DNS, time, container images, certificates | +| Upgrade stalls | Console, installer image, extension compatibility, disk space, network access | +| Missing driver or firmware | Image Factory schematic and installed extensions | +| Node rejoins with old settings | Generated configuration, applied patch, reboot requirement, wrong target node | +| etcd unhealthy | Member list, disk latency, quorum, time, network loss, alarms | + +## References + +- [Talos Linux documentation](https://docs.siderolabs.com/talos) +- [Talos Linux 1.13 CLI reference](https://docs.siderolabs.com/talos/v1.13/reference/cli) +- [Talos Linux getting started](https://docs.siderolabs.com/talos/v1.13/getting-started/getting-started) +- [Image Factory](https://docs.siderolabs.com/talos/v1.13/learn-more/image-factory) +- [Talos logging](https://docs.siderolabs.com/talos/v1.13/configure-your-talos-cluster/logging-and-telemetry/logging) +- [Resetting a machine](https://docs.siderolabs.com/talos/v1.13/configure-your-talos-cluster/lifecycle-management/resetting-a-machine) +- [Secure Boot](https://docs.siderolabs.com/talos/v1.13/platform-specific-installations/bare-metal-platforms/secureboot) From b1419c7c847f9c81b00e8c136a07d76b40fc3ea3 Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Sat, 18 Jul 2026 19:36:54 -0500 Subject: [PATCH 2/5] add Omni reference --- docs/kubernetes-platforms/omni.md | 526 ++++++++++++++++++++++++++++++ 1 file changed, 526 insertions(+) create mode 100644 docs/kubernetes-platforms/omni.md diff --git a/docs/kubernetes-platforms/omni.md b/docs/kubernetes-platforms/omni.md new file mode 100644 index 0000000..c5095d9 --- /dev/null +++ b/docs/kubernetes-platforms/omni.md @@ -0,0 +1,526 @@ +# Sidero Labs Omni Cheat Sheet + +> **Applies to:** Current Sidero Labs Omni and `omnictl` +> **Last reviewed:** 2026-07-18 + +A practical operational reference for registering Talos Linux machines, creating and managing Kubernetes clusters, handling access, upgrades, backups, infrastructure providers, and recovery through Omni. + +> [!WARNING] +> Once a machine joins Omni, Omni becomes the management authority for that Talos installation. The local Talos API is disabled for normal direct administration, and future configuration changes must be made through Omni. Leaving that model generally requires reprovisioning the machine with standard Talos installation media. + +## Product relationship + +| Name | Meaning | +|---|---| +| Sidero Labs | The vendor that develops Talos Linux and Omni | +| Talos Linux | Immutable, API-managed Kubernetes node operating system | +| Omni | Fleet, lifecycle, identity, and cluster-management platform for Talos and Kubernetes | +| SideroLink | Encrypted connectivity used between machines and Omni | +| Sidero Metal | Separate older bare-metal and Cluster API project; not another name for Omni | + +Omni is not a Kubernetes distribution. It manages Talos Linux machines and the Kubernetes clusters running on them. + +## Core capabilities + +- register Talos machines across bare metal, virtual machines, cloud, edge, and mixed environments; +- create, scale, upgrade, and delete Kubernetes clusters; +- manage Talos and Kubernetes access through centralized identity; +- provide encrypted machine connectivity through SideroLink; +- create machine classes and cluster templates; +- integrate infrastructure providers for static and dynamic machine provisioning; +- manage etcd backups and cluster recovery; +- expose UI and API-driven workflows through `omnictl`; +- support workload access and service-proxy features where enabled. + +## Hosted and self-hosted Omni + +Omni is available as: + +- hosted SaaS operated by Sidero Labs; +- licensed self-hosted deployment; +- non-production or home-lab use under the applicable BUSL terms. + +Production use requires a commercial license. Verify current licensing and deployment terms before adopting Omni for business workloads. + +Self-hosting options can include: + +- a single virtual machine; +- Kubernetes not managed by the same Omni instance; +- external etcd; +- more complex high-availability designs. + +Hosted Omni is generally the lowest-operational-overhead option. Self-hosted Omni introduces responsibility for backups, upgrades, certificates, identity, storage, registry services, and disaster recovery. + +## Install `omnictl` + +macOS or Linux with Homebrew: + +```bash +brew install siderolabs/tap/omnictl +``` + +Verify the client: + +```bash +omnictl version +omnictl --help +``` + +## Client configuration + +Omni client configuration is called `omniconfig`. + +Default path: + +```text +$HOME/.talos/omni/config +``` + +Inspect contexts: + +```bash +omnictl config contexts +omnictl config info +omnictl config context +``` + +Create a context manually when required: + +```bash +omnictl config new \ + --url \ + --identity \ + +``` + +Environment override: + +```bash +export OMNICONFIG= +``` + +> [!CAUTION] +> Verify the active Omni context and identity before applying templates, deleting clusters, rotating join tokens, or downloading administrative credentials. + +## Inspect available resources + +Omni uses a resource-oriented API similar in feel to `kubectl` and `talosctl`. + +```bash +omnictl get rd +omnictl get clusters +omnictl get machines +omnictl get machineclasses +omnictl get clusterstatuses +omnictl get etcdbackupstatuses +``` + +Inspect one resource: + +```bash +omnictl get -o yaml +``` + +Watch changes: + +```bash +omnictl get --watch +``` + +Resource names can evolve. Use `omnictl get rd` rather than assuming an old resource spelling remains valid. + +## Download installation media + +Download Omni-configured media: + +```bash +omnictl download iso +``` + +Use the UI or CLI to generate media that includes the intended Omni join configuration and Talos image customizations. + +Typical lifecycle: + +1. Generate installation media. +2. Boot a bare-metal machine or VM. +3. Allow the machine to register through SideroLink. +4. Label or classify the machine. +5. Assign it to a cluster or machine class. +6. Let Omni apply Talos configuration and bootstrap Kubernetes. + +## Join an existing Talos machine + +Create a join token: + +```bash +omnictl jointoken create --ttl +``` + +List tokens: + +```bash +omnictl jointoken list +``` + +Generate a partial machine configuration: + +```bash +omnictl jointoken machine-config \ + --token-name +``` + +Generate join kernel arguments when needed: + +```bash +omnictl jointoken kernel-args --token-name +``` + +Join methods include: + +- booting preconfigured Omni installation media; +- applying a Machine Join Config to a machine booted from standard Talos media. + +> [!DANGER] +> Joining a machine changes its management model. Confirm that existing automation, direct Talos access, recovery procedures, and break-glass expectations are compatible with Omni before enrolling production nodes. + +## SideroLink connectivity + +SideroLink provides encrypted communication between Omni and managed machines. + +Check when registration or management fails: + +- DNS resolution and time synchronization; +- outbound network access to Omni endpoints; +- UDP reachability where required; +- firewall and proxy rules; +- join-token validity; +- machine serial or console logs; +- MTU and path quality; +- duplicate machine identities or stale resources. + +HTTP tunneling may be available for networks that block UDP, but it adds overhead and should not be enabled without a network requirement. + +## Download kubeconfig and talosconfig + +Download and merge a cluster kubeconfig: + +```bash +omnictl kubeconfig \ + --cluster \ + --merge +``` + +Write to a specific path: + +```bash +omnictl kubeconfig ./kubeconfig \ + --cluster \ + --force +``` + +Download a cluster Talos configuration: + +```bash +omnictl talosconfig \ + --cluster \ + --merge +``` + +Download a generic Omni Talos configuration: + +```bash +omnictl talosconfig ./talosconfig --force +``` + +> [!WARNING] +> Administrative kubeconfig and talosconfig files are sensitive credentials. Prefer identity-backed access, short-lived sessions, narrowly scoped service accounts, secure storage, and auditable workflows. + +## Cluster templates + +Omni cluster templates are YAML documents that declare cluster resources and can be stored in Git. + +Common document kinds include: + +- `Cluster`; +- `ControlPlane`; +- `Workers`; +- `Machine`. + +A minimal conceptual template: + +```yaml +kind: Cluster +name: +kubernetes: + version: +talos: + version: +features: + diskEncryption: true + backupConfiguration: + interval: 1h +--- +kind: ControlPlane +machines: + - + - + - +--- +kind: Workers +name: workers +machineClass: + name: + size: 3 +``` + +Render and validate offline: + +```bash +omnictl cluster template render \ + --file +``` + +Apply through Omni: + +```bash +omnictl apply \ + --file \ + --dry-run + +omnictl apply \ + --file +``` + +Store patches, manifests, version choices, and machine-class intent with the template so the cluster can be reproduced and reviewed. + +## Machine classes + +Machine classes select machines by labels and desired count. + +Use them for: + +- automatically selecting available machines; +- dynamic infrastructure-provider capacity; +- worker pools with different hardware profiles; +- location, environment, role, or accelerator placement; +- scaling through declarative cluster templates. + +Validate label selectors carefully. An overly broad class can allocate the wrong hardware or location to a production cluster. + +## Infrastructure providers + +Current documented provider types include: + +- bare metal; +- Proxmox; +- vSphere; +- libvirt; +- KubeVirt. + +An Omni instance can connect to multiple provider deployments. A provider commonly represents one location, management API, credential boundary, region, or network segment. + +### Static providers + +Static providers manage existing machines and can handle operations such as: + +- power control; +- PXE boot; +- Talos provisioning; +- returning machines to an available pool. + +### Dynamic providers + +Dynamic providers create and destroy machines through another infrastructure API. + +Operational controls: + +- isolate provider credentials by location or platform; +- scope service accounts narrowly; +- document capacity and quota limits; +- monitor provisioning failures and stale instances; +- avoid deleting provider-managed machines out of band; +- test cluster deletion and failed-provision cleanup. + +List configured providers: + +```bash +omnictl infraprovider list +``` + +## Talos configuration overrides + +Omni is the source of truth for critical Talos configuration, identity, certificates, endpoints, and connectivity. Some fields that work in standalone Talos are forbidden or ignored under Omni. + +Use Omni-supported patches and template fields rather than directly editing Omni-owned values. + +> [!CAUTION] +> A direct Talos configuration that is valid for standalone Talos may be rejected, ignored, or later reconciled by Omni. + +## Cluster upgrades + +Omni manages both Talos Linux and Kubernetes upgrades. + +Before upgrading: + +```bash +omnictl get clusters +omnictl get clusterstatuses +omnictl get etcdbackupstatus -o yaml +``` + +Operational sequence: + +1. Confirm the supported Talos and Kubernetes version path. +2. Confirm a recent successful etcd backup. +3. Confirm control-plane count and quorum. +4. Review disruption budgets and workload shutdown behavior. +5. Start the Talos or Kubernetes upgrade through Omni. +6. Monitor each machine and cluster status. +7. Validate nodes, system pods, networking, storage, and workloads. +8. Synchronize updated Kubernetes bootstrap manifests where required. + +Omni upgrades control-plane nodes in a controlled sequence and checks etcd health. Do not bypass this process by deleting machines or Kubernetes nodes directly. + +## Stalled upgrade troubleshooting + +Inspect machine logs: + +```bash +omnictl machine-logs +``` + +Inspect cluster and machine resources: + +```bash +omnictl get clusterstatuses -o yaml +omnictl get machines -o yaml +``` + +Use serial, IPMI, VNC, or hypervisor console access when the Talos API is unavailable. + +During a stalled control-plane upgrade: + +- do not delete the VM or bare-metal resource out of band; +- do not add control-plane nodes as a quorum repair attempt; +- do not run `kubectl delete node` against a control-plane node; +- do not continue upgrading other control-plane nodes; +- preserve logs and backup state before recovery. + +## etcd backups + +Inspect backup status: + +```bash +omnictl get etcdbackupstatus -o yaml +``` + +Confirm: + +- the error field is empty; +- the last backup time is recent; +- backup storage is durable and protected; +- restoration has been tested; +- retention meets recovery objectives. + +Backups are the primary recovery path for an unrecoverable control-plane failure. + +## Cluster deletion + +Preview deletion: + +```bash +omnictl cluster delete --dry-run --verbose +``` + +Delete the cluster: + +```bash +omnictl cluster delete +``` + +Handle disconnected machines only with full understanding of whether they still exist and contain data: + +```bash +omnictl cluster delete \ + --destroy-disconnected-machines +``` + +> [!DANGER] +> Cluster deletion can destroy managed virtual machines, release bare-metal machines, remove cluster credentials, and permanently eliminate workloads and data not stored externally. + +## Users, service accounts, and access + +Inspect users: + +```bash +omnictl user list +``` + +Use service accounts for automation instead of sharing human credentials. + +Access design should distinguish: + +- Omni administrative access; +- Talos machine access; +- Kubernetes API access; +- workload service access; +- infrastructure-provider credentials; +- emergency break-glass access. + +Integrate enterprise identity providers and map access to least-privilege roles. Review inactive users and service accounts regularly. + +## Audit and support + +Review audit events: + +```bash +omnictl audit-log +``` + +Download a cluster support bundle: + +```bash +omnictl support \ + --cluster \ + --output +``` + +Support bundles and audit logs can contain sensitive infrastructure, identity, and workload metadata. Protect them accordingly. + +## Common failure patterns + +| Symptom | Checks | +|---|---| +| Machine never appears in Omni | Join token, media or join config, SideroLink network path, DNS, time, console logs | +| Machine is connected but unavailable for a cluster | Allocation state, labels, machine class, existing cluster ownership | +| Cluster creation stalls | Control-plane count, installation disk, Talos image, provider state, API endpoint | +| `talosctl` direct access stops working | Machine is Omni-managed; use Omni-provided talosconfig and supported access path | +| Provider cannot create machines | Credentials, quotas, templates, network placement, provider logs | +| Upgrade stalls | Machine logs, console, backup status, quorum, image availability | +| Kubeconfig access fails | Identity session, role, cluster state, OIDC or service-account configuration | +| Machine remains disconnected | SideroLink reachability, token revocation, firewall, clock, machine identity | +| Template apply changes unexpected resources | Rendered diff, document names, selectors, machine classes, version fields | + +## Troubleshooting workflow + +1. Verify the active omniconfig context and identity. +2. Check Omni service health and account status. +3. Inspect cluster, machine, and provider resources. +4. Review machine and provider logs. +5. Confirm SideroLink connectivity, DNS, time, MTU, and firewall behavior. +6. Verify backup status before any destructive recovery. +7. Compare templates and patches with the resources currently stored in Omni. +8. Use console access for machines that cannot reach Omni. +9. Avoid out-of-band deletion of machines or control-plane nodes. +10. Apply the documented Omni recovery path and verify the full cluster afterward. + +## References + +- [Omni overview](https://docs.siderolabs.com/omni/overview/what-is-omni) +- [Omni CLI reference](https://docs.siderolabs.com/omni/reference/cli) +- [Join machines to Omni](https://docs.siderolabs.com/omni/omni-cluster-setup/registering-machines/join-machines-to-omni) +- [Cluster templates](https://docs.siderolabs.com/omni/reference/cluster-templates) +- [Infrastructure providers](https://docs.siderolabs.com/omni/infrastructure-and-extensions/infrastructure-providers) +- [Upgrade Omni clusters](https://docs.siderolabs.com/omni/cluster-management/upgrading-clusters) +- [Talos configuration overrides](https://docs.siderolabs.com/omni/cluster-management/talos-config-overrides) +- [Options for running Omni](https://docs.siderolabs.com/omni/self-hosted/options-for-running-omni) From 6245a8169add435a9728105ecb4fd9e54a8da195 Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Sat, 18 Jul 2026 19:37:51 -0500 Subject: [PATCH 3/5] index Talos and Omni references --- README.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2f19353..0157136 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Infrastructure Reference -Practical quick-reference notes for network engineering, Linux operations, cloud platforms, infrastructure automation, and troubleshooting. +Practical quick-reference notes for network engineering, Linux operations, cloud platforms, Kubernetes platforms, infrastructure automation, and troubleshooting. > [!WARNING] > These notes are a memory aid, not a substitute for vendor documentation, change review, backups, or a tested rollback plan. Commands that alter state can cause outages or data loss. Validate syntax against the exact software and platform release you operate. @@ -24,6 +24,8 @@ The diagrams are intentionally limited to concepts where visual relationships im | Spanning-tree root and alternate path | [Visual guide](docs/visual-guides.md#spanning-tree-root-and-alternate-path) | [Spanning Tree](docs/networking/spanning-tree.md) | | Leaf-spine topology | [Visual guide](docs/visual-guides.md#leaf-spine-fabric) | [Leaf-spine design](docs/networking/leaf-spine.md) | | Pulumi change lifecycle | [Visual guide](docs/visual-guides.md#pulumi-change-lifecycle) | [Pulumi](docs/automation/pulumi.md) | +| Talos and Omni management boundary | [Visual guide](docs/visual-guides.md#talos-and-omni-management-boundary) | [Talos Linux](docs/kubernetes-platforms/talos-linux.md) and [Omni](docs/kubernetes-platforms/omni.md) | +| Omni machine-to-cluster lifecycle | [Visual guide](docs/visual-guides.md#omni-machine-to-cluster-lifecycle) | [Omni](docs/kubernetes-platforms/omni.md) | | Linux boot sequence | [Visual guide](docs/visual-guides.md#linux-boot-sequence) | [Linux boot and kernel](docs/linux/linux-boot.md) | | Git branch and pull-request workflow | [Visual guide](docs/visual-guides.md#git-branch-and-pull-request-workflow) | [Git](docs/development/git.md) | | Spec-driven development lifecycle | [Visual guide](docs/visual-guides.md#spec-driven-development-lifecycle) | [Spec-driven development](docs/development/spec-driven-development.md) | @@ -75,6 +77,13 @@ The diagrams are intentionally limited to concepts where visual relationships im | Docker and Docker Compose | [docs/containers/docker.md](docs/containers/docker.md) | | Kubernetes and kubectl | [docs/containers/kubernetes.md](docs/containers/kubernetes.md) | +## Kubernetes platforms + +| Platform | Reference | +|---|---| +| Talos Linux | [docs/kubernetes-platforms/talos-linux.md](docs/kubernetes-platforms/talos-linux.md) | +| Sidero Labs Omni | [docs/kubernetes-platforms/omni.md](docs/kubernetes-platforms/omni.md) | + ## Infrastructure automation | Topic | Reference | From 531ca5a4743dbdd509129ce19850bf67fd0da856 Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Sat, 18 Jul 2026 19:38:35 -0500 Subject: [PATCH 4/5] add Talos and Omni visual guides --- docs/visual-guides.md | 70 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/docs/visual-guides.md b/docs/visual-guides.md index 06133cc..4ca22f2 100644 --- a/docs/visual-guides.md +++ b/docs/visual-guides.md @@ -97,6 +97,76 @@ flowchart LR A preview is not a substitute for validating the selected stack, cloud identity, region, policy controls, and rollback plan. +## Talos and Omni management boundary + +Related references: [kubernetes-platforms/talos-linux.md](kubernetes-platforms/talos-linux.md) and [kubernetes-platforms/omni.md](kubernetes-platforms/omni.md) + +Standalone Talos is managed directly through the Talos API. When a machine joins Omni, Omni becomes the management authority and brokers normal Talos and Kubernetes access through its identity and policy model. + +```mermaid +flowchart LR + Engineer["Engineer or automation"] + TalosConfig["talosconfig"] + TalosAPI["Talos API"] + Standalone["Standalone Talos Linux nodes"] + + Identity["Identity provider or
Omni service account"] + OmniConfig["omniconfig"] + Omni["Omni API and UI"] + SideroLink["SideroLink
encrypted connectivity"] + Managed["Omni-managed Talos nodes"] + Kubernetes["Kubernetes API"] + + Engineer --> TalosConfig + TalosConfig --> TalosAPI + TalosAPI --> Standalone + + Engineer --> OmniConfig + Identity --> Omni + OmniConfig --> Omni + Omni --> SideroLink + SideroLink --> Managed + Omni --> Kubernetes + Managed --> Kubernetes +``` + +The two paths are intentionally different. Direct standalone procedures should not be assumed to work unchanged on an Omni-managed machine. + +## Omni machine-to-cluster lifecycle + +Related reference: [kubernetes-platforms/omni.md](kubernetes-platforms/omni.md) + +Omni can register manually provisioned machines or obtain machines through infrastructure providers, then allocate them to a cluster and manage their Talos and Kubernetes lifecycle. + +```mermaid +flowchart LR + Media["Omni installation media
or Machine Join Config"] + Provider["Infrastructure provider
bare metal, Proxmox, vSphere,
libvirt, or KubeVirt"] + Boot["Boot or create machine"] + Register["Register through SideroLink"] + Inventory["Machine inventory
labels and status"] + Class["Machine class or
explicit allocation"] + Cluster["Cluster template
control plane and workers"] + Configure["Omni applies Talos configuration"] + Bootstrap["Bootstrap Kubernetes"] + Operate["Scale, upgrade,
back up, and monitor"] + Recover["Restore or reprovision"] + + Media --> Boot + Provider --> Boot + Boot --> Register + Register --> Inventory + Inventory --> Class + Class --> Cluster + Cluster --> Configure + Configure --> Bootstrap + Bootstrap --> Operate + Operate --> Recover + Recover --> Inventory +``` + +Out-of-band deletion of provider-managed or control-plane machines can leave Omni waiting for resources that no longer exist and can break etcd quorum. + ## Linux boot sequence Related reference: [linux/linux-boot.md](linux/linux-boot.md) From 2ecefb265b894da510763b486bdb8e37de33228c Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Sat, 18 Jul 2026 19:38:58 -0500 Subject: [PATCH 5/5] validate Kubernetes platform references --- .github/workflows/docs-quality.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/docs-quality.yml b/.github/workflows/docs-quality.yml index c7bcb2f..9ff356b 100644 --- a/.github/workflows/docs-quality.yml +++ b/.github/workflows/docs-quality.yml @@ -37,6 +37,7 @@ jobs: "cisco-contact-center", "cloud", "containers", + "kubernetes-platforms", "automation", "linux", "high-availability",