Talos
Omni
Kubernetes GuidesOmni exposes a gRPC API for programmatic access to cluster management, machine state, and authentication. If you’re working interactively, omnictl wraps this same API and handles authentication automatically, but for custom tooling, automation pipelines, and external integrations, you’ll want to work with the API directly.Documentation Index
Fetch the complete documentation index at: https://docs.siderolabs.com/llms.txt
Use this file to discover all available pages before exploring further.
Connect using the Go client library
The recommended entry point for API integration is the official Go client package. While the raw gRPC API is available through the proto schemas in the Omni repository, the Go client provides a higher-level interface that simplifies common operations. In addition to generated API bindings, the client library handles authentication, resource unmarshaling, and the COSI resource lifecycle, making it easier to work with Omni resources directly from Go applications. The Go client package is documented at: For a complete example that demonstrates connecting to Omni and interacting with resources, see: client/pkg/client/example_test.go.Authenticate with service accounts
Before making any API calls, you’ll need a service account. The Omni API authenticates programmatic access through service accounts, where each account issues a key that the client presents with every request. See Create an Omni Service Account for setup instructions.Manage cluster lifecycle
Once authenticated, cluster lifecycle operations are best handled through the cluster templates package rather than the raw API. Cluster templates provide a stable, versioned interface for creating and updating clusters, and Omni guarantees backward compatibility for the template schema across versions. The template resource definitions are documented at: For the complete template schema and examples, see Cluster TemplatesWatching resources for status
Beyond managing clusters, Omni resources support watch operations, which allow clients to receive real-time updates when resource state changes. This is commonly used for observability integrations, automation pipelines, and systems that need to react to provisioning or cluster health events. The following resources are commonly used for status monitoring:| Resource | Description |
|---|---|
ClusterStatus | Overall cluster health and lifecycle phase |
MachineStatus | Per-machine connectivity and provisioning status |
ClusterMachineStatus | Per-machine status within a specific cluster |
MachineStatusMetrics | Aggregated machine metrics grouped by state, such as connected, available, allocated, and pending machines |
ClusterStatusMetrics | Aggregated cluster metrics grouped by lifecycle phase, such as healthy, unhealthy, scaling, or destroying clusters |