Skip to main content
Omni models all objects as API resources, including clusters, machines, users, infrastructure providers, and internal system objects. The omnictl CLI gives you direct access to these resources, allowing you to inspect and manage them without using the UI. This document explains how Omni resources are structured and how to manage them using omnictl.

​
Resource relationships

Omni resources do not exist in isolation. They are interconnected and continuously reconciled by controllers. For example:
  • A link resource is associated with a corresponding machine resource.
  • machine resources can become part of a cluster through MachineSet and MachineSetNode resources.
  • Controllers automatically create and maintain status and system resources.
These relationships are maintained through reconciliation rather than simple parent–child ownership. Controllers observe the desired state and ensure the system converges toward it. To inspect any resource and its metadata, run:
This command returns the complete resource definition, including metadata, status, and configuration fields. For example, to view the complete definition of a cluster named talos-default, run:
The output looks similar to:
A resource definition is divided into two main sections: metadata The metadata section describes the identity and lifecycle state of the resource. It includes:
  • namespace, type, and id, which uniquely identify the object
  • version, which tracks revisions of the resource
  • owner, which contains the name of the controller that manages this resource (for example, ClusterStatusController). If this field is set, the resource is controller-managed and cannot be modified directly with omnictl.
  • phase, which reflects the current lifecycle state
  • created and updated timestamps
  • finalizers, which list controllers that must complete cleanup work before the resource can be fully deleted
spec The spec section defines the desired state of the cluster. For a cluster, this includes:
  • Installed image and version settings
  • Kubernetes and Talos versions
  • Feature flags
  • Backup configuration
Once you understand this structure, you can use omnictl to query and manage resources confidently.

​
Manage resources with the CLI

The CLI allows you to query existing resources, apply updates, and remove objects from your Omni instance. Keep in mind that some resources are managed entirely by controllers. These resources are read-only, changing them manually is not possible. To discover which resource types are available in your environment, run:
This command displays the available Resource Definitions in your Omni instance.

​
Manage a cluster

You can create or update an Omni cluster using a cluster templates:

​
Cluster and machine resources

Clusters and machines define the structure and runtime state of your infrastructure. List all clusters:
Inspect a specific cluster:
This command outputs the live cluster resource definition in YAML format. It represents the current state of the cluster in Omni. This is different from a cluster template, which defines the desired configuration used to create or manage clusters.
List all machines:
Inspect a specific machine:

​
Access and identity resources

Access control and identity are also resource-driven.

​
Manage users

Users represent human identities that can authenticate with Omni and are assigned roles that define their permissions. You can manage users directly with omnictl: List users:
Create a user:
See Account Role for details about the available roles and their permissions. Update a user’s role:
Inspect a specific user:

​
Manage service accounts

Service accounts are intended for automation and system-to-system interactions. You can manage service accounts with the following commands: List service accounts:
Create a service account:
Renew a service account access key:

​
Manage join tokens

Join tokens allow machines or infrastructure providers to securely register with Omni. You can create and manage join tokens using omnictl: List join tokens
Create a join token
Renew join token TTL
Revoke a join token
Unrevoke a join token

​
Infrastructure and Integration Resources

Infrastructure providers are represented as resources. List infrastructure providers:
Create an infrastructure provider
Renew an infra provider key
Lists existing machine connections to Omni:

​
Filter and watch resources for changes

In addition to listing resources, you can filter results and watch for changes in real time. Filter by label:
Watch a resource:

​
Delete resources

You can remove resources using the delete command. Delete a specific resource:
Delete all resources of a type:
Deletion may fail if dependent resources still exist.