omni-cluster-operator

omni-cluster-operator lets platform teams manage Sidero Omni cluster templates with normal Kubernetes custom resources, without replacing Omni.

Independent Community Project

omni-cluster-operator is not affiliated with, sponsored by, endorsed by, or maintained by Sidero Labs. Sidero, Omni, Talos, and related names are trademarks or projects of their respective owners.

The operator runs in a Kubernetes namespace, reads an OmniConnection, assembles one OmniCluster plus its child template documents, validates the rendered Omni cluster-template YAML with Omni's public Go client, syncs it to Omni, and reports status back through Kubernetes conditions while keeping Omni as the lifecycle authority.

Use it when you want:

• GitOps-friendly Omni cluster lifecycle configuration.
• Omni service account keys stored in Kubernetes Secrets.
• Separate Kubernetes resources for cluster settings, control plane, workers, and static machines.
• Opt-in workload-cluster kubeconfig Secret exports for scoped automation.
• Opt-in direct Helm releases for add-ons that need Helm release state in the workload cluster.
• Opt-in workload-cluster Secret syncs for private bootstrap data that should not live in Git.
• Finalizer-based remote cleanup, with an orphan mode when you want to keep the Omni cluster after deleting Kubernetes resources.

Which operator should I use?

Use omni-cluster-operator when Omni is part of your management plane and you want Kubernetes resources to render, validate, sync, and delete Omni cluster templates.

If you want to manage Talos Linux clusters directly without Omni, consider talos-operator instead. It provides Kubernetes custom resources for Talos cluster lifecycle management, including direct Talos configuration, upgrades, backups, and generated access secrets. See Choosing an Operator for a more detailed comparison.

Start here

1. Install the operator.
2. Choose the right operator, if you are comparing Omni-backed and direct Talos lifecycle management.
3. Manage a cluster lifecycle.
4. Configure workload-cluster access, if management-cluster automation needs a kubeconfig Secret.
5. Understand direct Helm reconciliation, if add-ons need Helm release lifecycle in the workload cluster.
6. Configure NVIDIA GPU workers, if the cluster should run GPU workloads.
7. Plan GitOps ordering and deletion behavior.
8. Check status and debug reconciliation.
9. Use the API reference when writing manifests.

Important model

OmniCluster is the resource with remote side effects. It references an OmniConnection; child resources reference the cluster with spec.clusterRef.name.

flowchart LR
  Secret["Secret: serviceAccountKey"] --> Connection["OmniConnection"]
  Connection --> Cluster["OmniCluster"]
  ControlPlane["OmniControlPlane"] --> Cluster
  Workers["OmniWorkers"] --> Cluster
  Machine["OmniMachine"] --> Cluster
  Export["OmniKubeconfigExport"] --> HelmRelease["OmniHelmRelease"]
  Export --> SecretSync["OmniSecretSync"]
  HelmRelease --> Cluster
  SecretSync --> Cluster
  Export --> Cluster
  Cluster --> Omni["Sidero Omni"]

All of these objects must live in the operator release namespace because the default deployment runs in namespaced mode.