Skip to main content
If you have existing Talos clusters running without Omni management, you can import them to be managed by Omni. The import process connects your Talos nodes to Omni, preserves the existing cluster configuration as config patches, and registers the cluster as a managed resource, without resetting or disrupting the running workloads.

​
Prerequisites

Before proceeding, ensure you have the following:
  • omnictl installed and configured.
  • talosctl installed (optional, but useful for inspecting node state and discovering Talos nodes before import).
  • Network access from omnictl to your Omni instance, to Image Factory (or the custom Image Factory configured for your Omni instance), and to all Talos nodes.
  • os:admin role on the Talos cluster you want to import.
  • Operator role or above in Omni.

​
How import works

Before running the import, it helps to understand what happens during the import process:
  1. Omni discovers the Talos cluster state using the provided node endpoints and builds an import context.
  2. Omni validates that the cluster is healthy and ready to be imported.
  3. A backup of all current machine configurations is saved to a zip file.
  4. The Talos nodes are connected to Omni by applying the necessary configuration to each node.
  5. The cluster resources are created in Omni to represent the imported cluster.
After import completes, the cluster is marked as locked. This prevents Omni from making any changes to the cluster until you are ready to hand over management. You will unlock the cluster in Step 3 after verifying the import was successful.

​
How import handles your cluster configuration

Understanding how Omni handles schematics and config patches during import helps you anticipate the outcome and troubleshoot any issues that arise.

​
Image schematic

Talos Linux Image Factory allows you to create Talos installers with custom extensions, kernel arguments, and other settings. This configuration is called a Schematic. During import, Omni attempts to detect whether each node was booted from an Image Factory asset. If it was, Omni ensures the same Schematic is used with the Image Factory connected to your Omni instance. If a node was not booted from an Image Factory asset, the validation step will fail with an error indicating the Schematic cannot be found. In this case you have two options:
  • Create a matching Schematic in your Omni instance’s Image Factory and use it to upgrade the affected nodes before retrying the import.
  • Re-run the import with --force to skip Schematic validation.
Note: If --force is used, Omni will not be able to guarantee upgrade continuity for those nodes using their existing configuration. Omni will still be able to upgrade them, but will create and apply a new Schematic rather than reusing the existing one.
This limitation does not apply to nodes booted directly from Talos release assets.

​
Config patches

To preserve the existing cluster state during import, Omni uses config patches instead of overwriting node configurations. During import, Omni uses the --initial-talos-version and --initial-kubernetes-version values to generate the default machine configuration it would create for each node. It then compares this default configuration with the actual configuration running on each node and generates a config patch that captures the differences. This effectively preserves all customizations made to the cluster since it was first created. Some machine configuration fields are not permitted on Omni-managed clusters and are therefore excluded from the generated patches. For example, the following fields are not included:
  • cluster.id
  • cluster.secret
  • cluster.token
  • cluster.controlPlane.endpoint
  • machine.token
  • machine.ca
  • machine.type
These fields are managed internally by Omni and cannot be overridden through config patches. After the import completes, the final machine configuration for each node is produced by applying its config patch to the Omni-generated default configuration. You can inspect the resulting configuration under the Config tab on the Cluster Machine overview page in the Omni UI, and view the patches under the Patches tab.

​
Import command syntax

The omnictl cluster import command is the entry point for all import operations: 
omnictl cluster import [flags]

​
Import flags

Several flag values are inferred automatically from the connected cluster or local environment if not provided. The available flags are:
FlagDescription
--nodesComma-separated list of node endpoints to import.
--talos-versionTalos version of the cluster. Detected from nodes if not set.
--kubernetes-versionKubernetes version of the cluster. Detected from nodes if not set.
--initial-talos-versionTalos version used when the cluster was originally created. Defaults to the current Talos version if not set.
--initial-kubernetes-versionKubernetes version used when the cluster was originally created. Defaults to the current Kubernetes version if not set.
--talosconfigPath to the Talos configuration file. Defaults to the TALOSCONFIG environment variable, then $HOME/.talos/config.
--talos-contextThe Talos config context to use. Defaults to the selected context in the Talos configuration file.
--talos-endpointsOverride the default endpoints in the Talos configuration file.
--dry-runPreview the import without making any changes.
--forceSkip validation steps. See Image schematic for when this may be needed.

​
Steps to import a Talos cluster

Before proceeding, ensure you have reviewed how import works and have all prerequisites in place.

​
Step 1: Preview the import

Run the import command with --dry-run to preview what will happen without making any changes. Use the flags from the Import flags table above to build your command: 
omnictl cluster import \
  --talosconfig <path-to-talosconfig> \
  --nodes <node-ip-1>,<node-ip-2>,<node-ip-3> \
  --talos-version <talos-version> \
  --kubernetes-version <kubernetes-version> \
  --initial-talos-version <initial-talos-version> \
  --initial-kubernetes-version <initial-kubernetes-version> \
  --dry-run
A successful dry run will include the following in its output: 
cluster "<cluster-name>" is imported successfully but marked as 'locked' to prevent changes done by Omni
 > skipped in dry-run
If validation fails, the dry run will report the error and exit without making any changes. Review the error and address any issues before proceeding.

​
Step 2: Run the import

Once you are satisfied with the dry run output, run the same command without --dry-run: 
omnictl cluster import \
  --talosconfig <path-to-talosconfig> \
  --nodes <node-ip-1>,<node-ip-2>,<node-ip-3> \
  --talos-version <talos-version> \
  --kubernetes-version <kubernetes-version> \
  --initial-talos-version <initial-talos-version> \
  --initial-kubernetes-version <initial-kubernetes-version>
A successful import will include the following in its output: 
cluster "<cluster-name>" is imported successfully but marked as 'locked' to prevent changes done by Omni
The cluster is now registered in Omni but remains locked. No changes will be applied until you explicitly unlock it.

​
Step 3: Unlock the cluster

When you are ready for Omni to begin managing the cluster, unlock it by running the following command, replacing <cluster-name> with the name of your cluster: 
omnictl cluster unlock <cluster-name>
Unlocking the cluster hands over management to Omni. As part of this process, Omni updates the kube-apiserver, kube-scheduler, and kube-controller-manager static pod definitions to use the Omni-managed Kubernetes API endpoint, and applies any pending configuration changes. Before unlocking, you can review pending changes in the Omni UI under the cluster’s Config tab, or using omnictl from the CLI. For more information on cluster locking and unlocking, see Lock nodes.

​
Step 4: Rotate CA certificates

All imported clusters are labeled tainted-by-importing, which indicates that the cluster secrets are still accessible to anyone with the original talosconfig or kubeconfig. To revoke that access and remove the label, rotate the CA certificates for both the Talos and Kubernetes APIs, replacing <cluster-name> with the name of your cluster: 
omnictl cluster -n <cluster-name> secret rotate talos-ca
omnictl cluster -n <cluster-name> secret rotate kubernetes-ca
For full details on the rotation process, see CA Rotation.

​
Abort an import

An in-progress import can be aborted using the following command, replacing <cluster-name> with the name of your cluster: 
omnictl cluster import abort <cluster-name>
Aborting removes all resources created by Omni during the import and temporarily disconnects Omni from the Talos nodes. Unlike deleting a cluster, aborting an import does not reset the machines the cluster simply stops being managed by Omni.
Note: The cluster must be in locked state to abort an import.
During import, Omni applies configuration changes to each node to establish the Omni connection. If the import is aborted, these changes are not automatically reverted. To restore the nodes to their pre-import state, choose the approach that matches your situation:
  • Use Option 1 if the cluster was never unlocked after import and the backed-up configs still reflect the current node state.
  • Use Option 2 if the cluster was unlocked and further modified after import, making the backed-up configs potentially out of date.

​
Option 1: Restore from backup

Apply the backed-up machine configs using talosctl, replacing <node-ip> and <backup-config-file> with the IP of each node and the path to its backed-up config file: 
talosctl apply-config --nodes <node-ip> --file <backup-config-file>

​
Option 2: Manually revert using a config patch

Apply the following patch to each node using talosctl patch machineconfig to remove the partial documents added during import: 
talosctl patch machineconfig --nodes <node-ip> --patch @- <<'EOF'
apiVersion: v1alpha1
kind: SideroLinkConfig
$patch: delete
---
apiVersion: v1alpha1
kind: EventSinkConfig
$patch: delete
---
apiVersion: v1alpha1
kind: KmsgLogConfig
name: omni-kmsg
$patch: delete
EOF