API Reference¶

This page summarizes the user-facing fields. The generated CRDs under config/crd/bases are the source of truth for Kubernetes schema validation.

OmniConnection¶

Defines one Omni endpoint and the service account key used by the operator.

Field	Required	Notes
`spec.endpoint`	Yes	Omni API URL. Must start with `http://`, `https://`, or `grpc://`.
`spec.auth.serviceAccountSecretRef.name`	Yes	Secret name in the same namespace.
`spec.auth.serviceAccountSecretRef.key`	Yes	Secret key. Defaults to `serviceAccountKey`.
`spec.insecureSkipTLSVerify`	No	Disables TLS verification. Use only for local development.

Status includes Ready, Reachable, Stalled, endpoint, connectionRef, observedGeneration, and lastCheckTime.

OmniCluster¶

Owns remote Omni cluster lifecycle and cluster-level template settings.

Field	Required	Notes
`spec.connectionRef.name`	Yes	`OmniConnection` in the same namespace.
`spec.clusterName`	No	Remote Omni cluster name. Defaults to `metadata.name`.
`spec.kubernetes.version`	Yes	Kubernetes version such as `v1.35.0`.
`spec.kubernetes.manifests`	No	Omni-managed Kubernetes manifests, either inline or file-backed.
`spec.talos.version`	Yes	Talos version such as `v1.13.2`.
`spec.features`	No	Optional workload proxy, embedded discovery, disk encryption, and backup settings.
`spec.patches`	No	Cluster-scope Talos machine configuration patches.
`spec.systemExtensions`	No	System extensions installed on every machine.
`spec.kernelArgs`	No	Kernel args for static machines.
`spec.templateRoot`	No	Directory inside the operator container for file-backed patches and manifests.
`spec.deletePolicy.orphan`	No	Leave the remote Omni cluster intact on Kubernetes deletion.
`spec.deletePolicy.destroyMachines`	No	Forcefully remove disconnected nodes while deleting template resources.
`spec.syncInterval`	No	Periodic reconciliation interval. Defaults to `5m`.
`spec.suspend`	No	Stop remote Omni sync while keeping resources and finalizers.

Status includes Ready, Validated, Synced, selected child references, rendered template hash, remote cluster phase, and observed generation.

OmniControlPlane¶

Defines the Omni ControlPlane template document. Exactly one OmniControlPlane should reference each OmniCluster.

Field	Required	Notes
`spec.clusterRef.name`	Yes	`OmniCluster` in the same namespace.
`spec.machines`	Conditional	Explicit Omni machine IDs. Mutually exclusive with `machineClass`.
`spec.machineClass.name`	Conditional	Omni MachineClass name. Mutually exclusive with `machines`.
`spec.machineClass.size`	Conditional	Number of machines or an Omni size keyword such as `unlimited`.
`spec.patches`	No	Machine-set patches.
`spec.systemExtensions`	No	Extensions for every machine in the set.
`spec.kernelArgs`	No	Kernel args for static machines in the set.
`spec.bootstrapSpec`	No	Restore bootstrap settings.

OmniWorkers¶

Defines one Omni Workers template document.

Field	Required	Notes
`spec.clusterRef.name`	Yes	`OmniCluster` in the same namespace.
`spec.workerSetName`	No	Remote worker set name. Defaults to `metadata.name`; cannot be `control-planes`.
`spec.machines`	Conditional	Explicit Omni machine IDs. Mutually exclusive with `machineClass`.
`spec.machineClass.name`	Conditional	Omni MachineClass name. Mutually exclusive with `machines`.
`spec.machineClass.size`	Conditional	Number of machines or an Omni size keyword such as `unlimited`.
`spec.patches`	No	Machine-set patches.
`spec.systemExtensions`	No	Extensions for every machine in the set.
`spec.kernelArgs`	No	Kernel args for static machines in the set.
`spec.updateStrategy`	No	Config update behavior.
`spec.upgradeStrategy`	No	Version, extension, and kernel arg upgrade behavior.
`spec.deleteStrategy`	No	Machine removal behavior.

OmniMachine¶

Defines optional per-machine settings for a static machine.

Field	Required	Notes
`spec.clusterRef.name`	Yes	`OmniCluster` in the same namespace.
`spec.machineID`	No	Omni machine ID. Defaults to `metadata.name`.
`spec.locked`	No	Prevents config updates, upgrades, and downgrades. Omni allows locked machines only as workers.
`spec.install.disk`	No	Talos install disk path.
`spec.patches`	No	Machine-specific patches.
`spec.systemExtensions`	No	Machine-specific system extensions.
`spec.kernelArgs`	No	Machine-specific kernel args.

OmniHelmRelease¶

Reconciles a Helm release directly in an Omni-created workload cluster using an explicit kubeconfig Secret.

Field	Required	Notes
`spec.clusterRef.name`	Yes	`OmniCluster` in the same namespace. Used for attachment/status; it does not export credentials.
`spec.kubeconfigSecretRef.name`	Yes	Secret in the same namespace containing workload-cluster kubeconfig data.
`spec.kubeconfigSecretRef.key`	No	Secret data key. Defaults to `kubeconfig`.
`spec.releaseName`	No	Helm release name. Defaults to `metadata.name`.
`spec.namespace`	No	Workload-cluster release namespace. Defaults to `default`.
`spec.chart.repository`	Yes	Helm repository URL.
`spec.chart.chart`	Yes	Helm chart name to install or upgrade.
`spec.chart.version`	Yes	Helm chart version to install or upgrade.
`spec.chart.values`	No	Helm values object passed to install and upgrade.
`spec.createNamespace`	No	Ask Helm to create the release namespace during install.
`spec.wait`	No	Ask Helm to wait for reconciled resources to become ready.
`spec.waitForJobs`	No	Include Jobs in Helm wait behavior.
`spec.timeout`	No	Helm action timeout. Defaults to `5m`.
`spec.atomic`	No	Roll back failed upgrades and uninstall failed installs when waiting.
`spec.disableHooks`	No	Disable Helm hooks.
`spec.skipCRDs`	No	Skip CRD installation. Helm does not upgrade CRDs.
`spec.maxHistory`	No	Maximum retained Helm release revisions. Zero uses Helm's default.
`spec.deletionPolicy`	No	`Uninstall` removes the workload-cluster release on CR deletion; `Orphan` leaves it behind. Defaults to `Uninstall`.

Status includes Ready, Released, release name, namespace, chart, chart version, release revision, release status, last Helm action, timestamps, last error, and observed generation.

OmniKubeconfigExport¶

Exports a scoped workload-cluster service-account kubeconfig into a Secret only when explicitly requested.

Field	Required	Notes
`spec.clusterRef.name`	Yes	`OmniCluster` in the same namespace.
`spec.targetSecretRef.name`	Yes	Target Secret in the same namespace.
`spec.targetSecretRef.key`	No	Secret data key. Defaults to `kubeconfig`.
`spec.serviceAccount.user`	Yes	Kubernetes username for the generated kubeconfig.
`spec.serviceAccount.groups`	Yes	Kubernetes groups for the generated kubeconfig. `system:masters` requires `allowClusterAdmin: true`.
`spec.serviceAccount.allowClusterAdmin`	No	Allows `system:masters`. Leave false for scoped automation credentials.
`spec.ttl`	Yes	Requested service-account kubeconfig lifetime, such as `24h`.
`spec.renewBefore`	No	Rotate before expiration, such as `4h`. Must be less than `ttl`.
`spec.deletionPolicy`	Yes	`Delete` removes the target Secret on deletion; `Orphan` leaves it behind.

Status includes Ready, Accepted, Exported, target Secret name/key, kubeconfig hash, expiration time, next rotation time, and last rotation time.

The target Secret is created in the same namespace as the export. The default data key is kubeconfig. Secret labels and annotations include the owning export UID/name, remote cluster name, generated kubeconfig hash, export spec hash, expiration time, and last rotation time.

Changing the service-account user, groups, TTL, target key, or remote cluster name changes the export spec hash and causes a new kubeconfig request. renewBefore, target Secret name, and deletion policy affect rotation or cleanup behavior but do not change the generated kubeconfig identity.

OmniSecretSync¶

Copies a management-cluster Secret into an Omni-created workload cluster using an explicit workload-cluster kubeconfig Secret.

Field	Required	Notes
`spec.clusterRef.name`	Yes	`OmniCluster` in the same namespace. Used for attachment/status; it does not export credentials.
`spec.kubeconfigSecretRef.name`	Yes	Secret in the same namespace containing workload-cluster kubeconfig data.
`spec.kubeconfigSecretRef.key`	No	Secret data key. Defaults to `kubeconfig`.
`spec.sourceSecretRef.name`	Yes	Source Secret in the same namespace as the `OmniSecretSync`.
`spec.targetSecretRef.name`	Yes	Target Secret name in the workload cluster.
`spec.targetSecretRef.namespace`	Yes	Target Secret namespace in the workload cluster.
`spec.type`	No	Target Secret type override. Defaults to the source Secret type.
`spec.labels`	No	Extra labels to write on the workload-cluster target Secret.
`spec.annotations`	No	Extra annotations to write on the workload-cluster target Secret.
`spec.createNamespace`	No	Create the workload-cluster target namespace if missing.
`spec.deletionPolicy`	Yes	`Delete` removes the target Secret on deletion; `Orphan` leaves it behind.

Status includes Ready, Accepted, Synced, source Secret name, target Secret name/namespace, target Secret type, synced content hash, last attempt time, last sync time, last error, and observed generation.

OmniSecretSync copies data and Secret type only. It does not copy management-cluster owner references, resource versions, labels, or annotations from the source Secret. The target Secret receives operator ownership labels/annotations plus any spec.labels and spec.annotations.

Common nested fields¶

Patches¶

Each patch may use inline or file.

Field	Notes
`file`	Path relative to `OmniCluster.spec.templateRoot` in the operator container.
`name`	Human-readable patch name.
`idOverride`	Overrides Omni's generated config patch ID.
`labels`	Labels applied to the generated config patch.
`annotations`	Annotations applied to the generated config patch.
`inline`	Talos strategic machine configuration patch.

Update strategies¶

updateStrategy, upgradeStrategy, and deleteStrategy use the same shape:

type: Rolling
rolling:
  maxParallelism: 1

type may be Rolling or Unset. When unset, Omni applies the operation at once.