This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Reference

1: Cluster Templates
2: Access Policies (ACLs)
3: omnictl CLI

1 - Cluster Templates

Reference documentation for cluster templates.

Cluster templates are parsed, validated, and converted to Omni resources, which are then created or updated via the Omni API. Omni guarantees backward compatibility for cluster templates, so the same template can be used with any future version of Omni.

All referenced files in machine configuration patches should be stored relative to the current working directory.

Structure

The Cluster Template is a YAML file consisting of multiple documents, with each document having a kind field that specifies the type of the document. Some documents might also have a name field that specifies the name (ID) of the document.

kind: Cluster
name: example
labels:
  my-label: my-value
kubernetes:
  version: v1.26.0
talos:
  version: v1.3.2
features:
  diskencryption: true
patches:
  - name: kubespan-enabled
    inline:
      machine:
        network:
          kubespan:
            enabled: true
systemExtensions:
  - siderolabs/hello-world-service
---
kind: ControlPlane
machines:
  - 27c16241-96bf-4f17-9579-ea3a6c4a3ca8
  - 4bd92fba-998d-4ef3-ab43-638b806dd3fe
  - 8fdb574a-a252-4d7d-94f0-5cdea73e140a
---
kind: Workers
machines:
  - b885f565-b64f-4c7a-a1ac-d2c8c2781373
  - a54f21dc-6e48-4fc1-96aa-3d7be5e2612b
---
kind: Workers
name: xlarge
machines:
  - 1f721dee-6dbb-4e71-9832-226d73da3841
systemExtensions:
  - siderolabs/hello-world-service
---
kind: Machine
name: 27c16241-96bf-4f17-9579-ea3a6c4a3ca8
---
kind: Machine
name: 4bd92fba-998d-4ef3-ab43-638b806dd3fe
install:
  disk: /dev/vda
---
kind: Machine
name: 8fdb574a-a252-4d7d-94f0-5cdea73e140a
install:
  disk: /dev/vda
---
kind: Machine
name: b885f565-b64f-4c7a-a1ac-d2c8c2781373
install:
  disk: /dev/vda
systemExtensions:
  - siderolabs/hello-world-service
---
kind: Machine
name: a54f21dc-6e48-4fc1-96aa-3d7be5e2612b
locked: true
install:
  disk: /dev/vda
---
kind: Machine
name: 1f721dee-6dbb-4e71-9832-226d73da3841
install:
  disk: /dev/vda

Each cluster template should have exactly one document of kind: Cluster, kind: ControlPlane, and any number of kind: Workers with different names.

Every Machine document must be referenced by either a ControlPlane or Workers document.

Document Types

`Cluster`

The Cluster document specifies the cluster configuration, labels, defines the cluster name and base component versions.

kind: Cluster
name: example
labels:
  my-label: my-value
annotations:
  my-annotation: my-value
kubernetes:
  version: v1.26.1
talos:
  version: v1.3.3
features:
  enableWorkloadProxy: true
  diskEncryption: true
  backupConfiguration:
    interval: 1h
patches:
  - file: patches/example-patch.yaml
systemExtensions:
  - siderolabs/hello-world-service

Field	Type	Description
`kind`	string	`Cluster`
`name`	string	Cluster name: only letters, digits and `-` and `_` are allowed. The cluster name is used as a key by all other documents, so if the cluster name changes, a new cluster will be created.
`labels`	map[string]string	Labels to be applied to the cluster.
`annotations`	map[string]string	Annotations to be applied to the cluster.
`kubernetes.version`	string	Kubernetes version to use, `vA.B.C`.
`talos.version`	string	Talos version to use, `vA.B.C`.
`features.enableWorkloadProxy`	boolean	Whether to enable the workload proxy feature. Defaults to `false`.
`features.diskEncryption`	boolean	Whether to enable disk encryption. Defaults to `false`.
`features.backupConfiguration.interval`	string	Cluster etcd backup interval. Must be a valid Go duration. Zero `0` disables automatic backups.
`patches`	array	List of patches to apply to the cluster.
`systemExtensions`	array	The list of system extensions to be installed on every machine in the cluster.

`ControlPlane`

The ControlPlane document specifies the control plane configuration, defines the number of control plane nodes, and the list of machines to use.

As control plane machines run an etcd cluster, it is recommended to use a number of machines for the control plane that can achieve a stable quorum (i.e. 1, 3, 5, etc.). Changing the set of machines in the control plane will trigger a rolling scale-up/scale-down of the control plane.

The control plane should have at least a single machine, but it is recommended to use at least 3 machines for the control plane for high-availability.

kind: ControlPlane
labels:
  my-label: my-value
annotations:
  my-annotation: my-value
machines:
  - 27c16241-96bf-4f17-9579-ea3a6c4a3ca8
  - 4bd92fba-998d-4ef3-ab43-638b806dd3fe
  - 8fdb574a-a252-4d7d-94f0-5cdea73e140a
patches:
  - file: patches/example-controlplane-patch.yaml
systemExtensions:
  - siderolabs/hello-world-service

Field	Type	Description
`kind`	string	`ControlPlane`
`labels`	map[string]string	Labels to be applied to the control plane machine set.
`annotations`	map[string]string	Annotations to be applied to the control plane machine set.
`machines`	array	List of machine IDs to use for control plane nodes (mutually exclusive with `machineClass`).
`patches`	array	List of patches to apply to the machine set.
`machineClass`	MachineClass	Machine Class configuration (mutually exclusive with `machines`).
`systemExtensions`	array	The list of system extensions to be installed on every machine in the machine set.

`Workers`

The Workers document specifies the worker configuration, defines the number of worker nodes, and the list of machines to use.

kind: Workers
name: workers
labels:
  my-label: my-value
annotations:
    my-annotation: my-value
machines:
  - b885f565-b64f-4c7a-a1ac-d2c8c2781373
updateStrategy:
  rolling:
    maxParallelism: 3
deleteStrategy:
  type: Rolling
  rolling:
    maxParallelism: 5
patches:
  - file: patches/example-workers-patch.yaml
systemExtensions:
  - siderolabs/hello-world-service

Field	Type	Description
`kind`	string	`Workers`
`name`	string	Worker machine set name: only letters, digits and `-` and `_` are allowed. Defaults to `workers` when omitted. Must be unique and not be `control-planes`.
`labels`	map[string]string	Labels to be applied to the worker machine set.
`annotations`	map[string]string	Annotations to be applied to the worker machine set.
`machines`	array	List of machine IDs to use as worker nodes in the machine set (mutually exclusive with `machineClass`).
`patches`	array	List of patches to apply to the machine set.
`machineClass`	MachineClass	Machine Class configuration (mutually exclusive with `machines`).
`updateStrategy`	UpdateStrategy	Update strategy for the machine set. Defaults to `type: Rolling` with `maxParallelism: 1`.
`deleteStrategy`	UpdateStrategy	Delete strategy for the machine set. Defaults to `type: Unset`.
`systemExtensions`	array	The list of system extensions to be installed on every machine in the machine set.

`MachineClass`

The MachineClass section of the Control Plane or the Workers defines the rule for picking the machines in the machine set.

kind: Workers
name: workers
machineClass:
  name: worker-class
  size: 2

Field	Type	Description
`name`	string	Name of the machine class to use.
`size`	number	Number of machines to pick from the matching machine class.

Note

size field supports keyword unlimited|infinity which makes the machine set pick all available machines from the specified machine class.

`UpdateStrategy`

The UpdateStrategy section of the Workers defines the update and/or the delete strategy for the machine set.

kind: Workers
name: workers
updateStrategy:
  rolling:
    maxParallelism: 3
deleteStrategy:
  type: Rolling
  rolling:
    maxParallelism: 5

Field	Type	Description
`type`	string	Strategy type. Can be `Rolling` or `Unset`. Defaults to `Rolling` for `updateStrategy` and `Unset` for the `deleteStrategy`. When `Unset`, all updates and/or deletes will be applied at once.
`rolling.maxParallelism`	number	Maximum number of machines to update and/or delete in parallel. Only used when the `type` is `Rolling`. Defaults to `1`.

`Machine`

The Machine document specifies the install disk and machine-specific configuration patches. They are optional, but every Machine document must be referenced by either a ControlPlane or Workers document.

kind: Machine
name: 27c16241-96bf-4f17-9579-ea3a6c4a3ca8
labels:
  my-label: my-value
annotations:
  my-annotation: my-value
locked: false
install:
  disk: /dev/vda
patches:
  - file: patches/example-machine-patch.yaml
systemExtensions:
  - siderolabs/hello-world-service

Field	Type	Description
`kind`	string	`Machine`
`name`	string	Machine ID.
`labels`	map[string]string	Labels to be applied to the machine set node.
`annotations`	map[string]string	Annotations to be applied to the machine set node.
`locked`	string	Whether the machine should be marked as locked. Can be `true` only if the machine is used as a worker.
`install.disk`	string	Disk to install Talos on. Matters only for Talos running from ISO or iPXE.
`patches`	array	List of patches to apply to the machine.
`systemExtensions`	array	The list of system extensions to be installed on the machine.

Note

When Talos is not installed and the install disk is not specified, Omni will try to pick the install disk automatically. It will find the smallest disk which is larger than 5GB.

Common Fields

`patches`

The patches field is a list of machine configuration patches to apply to a cluster, a machine set, or an individual machine. Config patches modify the configuration before it is applied to each machine in the cluster. Changing configuration patches modifies the machine configuration which gets automatically applied to the machine.

patches:
  - file: patches/example-patch.yaml
  - name: kubespan-enabled
    inline:
      machine:
        network:
          kubespan:
            enabled: true
  - idOverride: 950-set-env-vars
    labels:
      my-label: my-value
    annotations:
      my-annotation: my-value
    inline:
      machine:
        env:
          MY_ENV_VAR: my-value

Field	Type	Description
`file`	string	Path to the patch file. Path is relative to the current working directory when executing `omnictl`. File should contain Talos machine configuration strategic patch.
`name`	string	Name of the patch. Required for `inline` patches when `idOverride` is not set, optional for `file` patches (default name will be based on the file path).
`idOverride`	string	Override the config patch ID, so it won’t be generated from the `name` or `file`.
`labels`	map[string]string	Labels to be applied to the config patch.
`annotations`	map[string]string	Annotations to be applied to the config patch.
`inline`	object	Inline patch containing Talos machine configuration strategic patch.

A configuration patch may be either inline or file based. Inline patches are useful for small changes, file-based patches are useful for more complex changes, or changes shared across multiple clusters.

2 - Access Policies (ACLs)

Reference documentation for ACLs.

ACLs are used to control fine-grained access policies of users to resources; and are validated, stored, and evaluated as an AccessPolicy resource in Omni.

At the moment, only Kubernetes cluster access (group impersonation) is supported.

Structure

`AccessPolicy`

The AccessPolicy is a single resource containing a set of user groups, a set of cluster groups, a list of matching rules and a list of tests.

metadata:
  namespace: default
  type: AccessPolicies.omni.sidero.dev
  id: access-policy
spec:
  usergroups:
    # match level-1 users by fnmatch expression
    level-1:
      users:
        - match: level-1*
    # match level-2 users by label selectors
    level-2:
      users:
        - labelselectors:
            - level=2
    # match level-3 users by explicit list
    level-3:
      users:
        - name: admin1@example.com
        - name: admin2@example.com
  clustergroups:
    dev:
      clusters:
        - match: dev-*
    staging:
      clusters:
        - match: staging-*
        - match: preprod-*
    production:
      clusters:
        - match: prod-*
  rules:
    - users:
        - group/level-1
      clusters:
        - group/dev
      role: Operator
    - users:
        - group/level-1
      clusters:
        - group/staging
      role: Reader
      kubernetes:
        impersonate:
          groups:
            - read-only
    - users:
        - group/level-2
      clusters:
        - group/dev
        - group/staging
      role: Operator
    - users:
        - group/level-2
      clusters:
        - group/production
      role: Reader
      kubernetes:
        impersonate:
          groups:
            - read-only
    - users:
        - group/level-3
      clusters:
        - group/dev
        - group/staging
        - group/production
      role: Admin
    # simple rule - without links to user or cluster groups
    - users:
        - vault-admin@example.com
      clusters:
        - vault
      role: Admin
  tests:
    # level-1 tests
    - name: level-1 engineer has Operator access to dev cluster
      user:
        name: level-1-a@example.com
      cluster:
        name: dev-cluster-1
      expected:
        role: Operator
    - name: level-1 engineer has read-only access to staging cluster
      user:
        name: level-1-b@example.com
      cluster:
        name: staging-cluster-1
      expected:
        role: Reader
        kubernetes:
          impersonate:
            groups:
              - read-only
    - name: level-1 engineer has no access to production cluster
      user:
        name: level-1-c@example.com
      cluster:
        name: production-cluster-1
      expected:
        role: None
        kubernetes:
          impersonate:
            groups: []
    # level-2 tests
    - name: level-2 engineer has Operator access to staging cluster
      user:
        name: something@example.com
        labels:
          level: "2"
      cluster:
        name: preprod-cluster-1
      expected:
        role: Operator
    - name: level-2 engineer has read-only access to prod cluster
      user:
        name: something@example.com
        labels:
          level: "2"
      cluster:
        name: prod-cluster-1
      expected:
        role: Reader
        kubernetes:
          impersonate:
            groups:
              - read-only
    # level-3 tests
    - name: level-3 engineer has admin access to prod cluster
      user:
        name: admin1@example.com
      cluster:
        name: prod-cluster-1
      expected:
        role: Admin
    # vault-admin tests
    - name: vault-admin has admin access to vault
      user:
        name: vault-admin@example.com
      cluster:
        name: vault
      expected:
        role: Admin

Field	Type	Description
`metadata.namespace`	string	Always set to `default`.
`metadata.type`	string	`AccessPolicies.omni.sidero.dev`.
`metadata.id`	string	Always set to `access-policy`.
`spec.usergroups`	map[string]UserGroup	Map of user group names to user group definitions.
`spec.clustergroups`	map[string]ClusterGroup	Map of cluster group names to cluster group definitions.
`spec.rules`	array	List of rules to match.
`spec.tests`	array	List of tests to run when the resource is created or updated.

`UserGroup`

A UserGroup is a group of users.

users:
  - name: user1@example.com
  - name: user2@example.com

Field	Type	Description
`users`	array	List of Users.

`User`

A User is a single user.

name: user1@example.com
match: user1*
labelselectors:
  - level=1

Field	Type	Description
`name`	string	User identity used to authenticate to Omni.
`match`	string	fnmatch expression to match user identities.
`labelselectors`	array	List of label selector strings.

Note: name, match and labelselectors are mutually exclusive. Only one of them can be set to a non-zero value.

`ClusterGroup`

A ClusterGroup is a group of clusters.

clusters:
  - name: cluster-1
  - name: cluster-2

Field	Type	Description
`clusters`	array	List of Clusters.

`Cluster`

A Cluster is a single cluster.

name: cluster-1
match: cluster-1*

Field	Type	Description
`name`	string	Cluster name (ID).
`match`	fnmatch expression to match cluster names (IDs).

Note: name and match are mutually exclusive. Only one of them can be set to a non-zero value.

`Rule`

A Rule is a set of users, clusters and Kubernetes impersonation groups.

The reserved prefix group/ is used to reference a user group in users or a cluster group in clusters.

users:
  - user1@example.com
  - group/user-group-1
clusters:
  - cluster1
  - group/cluster-group-1
role: Operator
kubernetes:
  impersonate:
    groups:
      - system:masters
      - another-impersonation-group

Field	Type	Description
`users`	array	List of Users or UserGroups.
`clusters`	array	List of Clusters or ClusterGroups.
`role`	enum	Role to grant to the user.
`kubernetes.impersonate.groups`	array	List of `string`s representing Kubernetes impersonation groups.

`Role`

A Role is the role to grant to the user.

Possible values: None, Reader, Operator, Admin.

`Test`

A Test is a single test case.

Test cases are run when the resource is created or updated, and if any of them fail, the operation is rejected.

name: support engineer has full access to staging cluster
user:
  name: support1@example.com
cluster:
  name: staging-cluster-1
expected:
  role: Operator
  kubernetes:
    impersonate:
      groups:
        - system:masters

Field	Type	Description
`name`	string	Human-friendly test case name.
`user`	TestUser	User identity to use in the test.
`cluster`	TestCluster	Cluster to use in the test.
`expected`	Expected	Expected result.

`TestUser`

A TestUser is the user identity to use in a test case.

name: user1@example.com
labels:
  level: "1"

Field	Type	Description
`name`	string	User identity to use in the test.
`labels`	map[string]string	Map of label names to label values.

`TestCluster`

A TestCluster is the cluster to use in a test case.

name: cluster-1

Field	Type	Description
`name`	string	Cluster name (ID).

`Expected`

An Expected is the expected results of a test case.

role: Operator
kubernetes:
  impersonate:
    groups:
      - system:masters
      - another-impersonation-group

Field	Type	Description
`role`	enum	Role to grant to the user.
`kubernetes.impersonate.groups`	array	List of `string`s representing Kubernetes impersonation groups.

3 - omnictl CLI

omnictl CLI tool reference.

omnictl apply

Create or update resource using YAML file as an input

omnictl apply [flags]

Options

  -d, --dry-run       Dry run, implies verbose
  -f, --file string   Resource file to load and apply
  -h, --help          help for apply
  -v, --verbose       Verbose output

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl cluster delete

Delete all cluster resources.

Synopsis

Delete all resources related to the cluster. The command waits for the cluster to be fully destroyed.

omnictl cluster delete cluster-name [flags]

Options

      --destroy-disconnected-machines   removes all disconnected machines which are part of the cluster from Omni
  -d, --dry-run                         dry run
  -h, --help                            help for delete
  -v, --verbose                         verbose output (show diff for each resource)

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl cluster kubernetes manifest-sync

Sync Kubernetes bootstrap manifests from Talos controlplane nodes to Kubernetes API.

Synopsis

Sync Kubernetes bootstrap manifests from Talos controlplane nodes to Kubernetes API. Bootstrap manifests might be updated with Talos version update, Kubernetes upgrade, and config patching. Talos never updates or deletes Kubernetes manifests, so this command fills the gap to keep manifests up-to-date.

omnictl cluster kubernetes manifest-sync cluster-name [flags]

Options

      --dry-run   don't actually sync manifests, just print what would be done (default true)
  -h, --help      help for manifest-sync

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl cluster kubernetes upgrade-pre-checks

Run Kubernetes upgrade pre-checks for the cluster.

Synopsis

Verify that upgrading Kubernetes version is available for the cluster: version compatibility, deprecated APIs, etc.

omnictl cluster kubernetes upgrade-pre-checks cluster-name [flags]

Options

  -h, --help        help for upgrade-pre-checks
      --to string   target Kubernetes version for the planned upgrade

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl cluster kubernetes

Cluster Kubernetes management subcommands.

Synopsis

Commands to render, validate, manage cluster templates.

Options

  -h, --help   help for kubernetes

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl cluster machine lock

Lock the machine

Synopsis

When locked, no config updates, upgrades and downgrades will be performed on the machine.

omnictl cluster machine lock machine-id [flags]

Options

  -h, --help   help for lock

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl cluster machine unlock

Unlock the machine

Synopsis

Removes locked annotation from the machine.

omnictl cluster machine unlock machine-id [flags]

Options

  -h, --help   help for unlock

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl cluster machine

Machine related commands.

Synopsis

Commands to manage cluster machines.

Options

  -h, --help   help for machine

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl cluster status

Show cluster status, wait for the cluster to be ready.

Synopsis

Shows current cluster status, if the terminal supports it, watch the status as it updates. The command waits for the cluster to be ready by default.

omnictl cluster status cluster-name [flags]

Options

  -h, --help            help for status
  -q, --quiet           suppress output
  -w, --wait duration   wait timeout, if zero, report current status and exit (default 5m0s)

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl cluster template delete

Delete all cluster template resources from Omni.

Synopsis

Delete all resources related to the cluster template. This command requires API access.

omnictl cluster template delete [flags]

Options

      --destroy-disconnected-machines   removes all disconnected machines which are part of the cluster from Omni
  -d, --dry-run                         dry run
  -f, --file string                     path to the cluster template file.
  -h, --help                            help for delete
  -v, --verbose                         verbose output (show diff for each resource)

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl cluster template diff

Show diff in resources if the template is synced.

Synopsis

Query existing resources for the cluster and compare them with the resources generated from the template. This command requires API access.

omnictl cluster template diff [flags]

Options

  -f, --file string   path to the cluster template file.
  -h, --help          help for diff

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl cluster template export

Export a cluster template from an existing cluster on Omni.

Synopsis

Export a cluster template from an existing cluster on Omni. This command requires API access.

omnictl cluster template export cluster-name [flags]

Options

  -c, --cluster string   cluster name
  -f, --force            overwrite output file if it exists
  -h, --help             help for export
  -o, --output string    output file (default: stdout)

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl cluster template render

Render a cluster template to a set of resources.

Synopsis

Validate template contents, convert to resources and output resources to stdout as YAML. This command is offline (doesn’t access API).

omnictl cluster template render [flags]

Options

  -f, --file string   path to the cluster template file.
  -h, --help          help for render

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl cluster template status

Show template cluster status, wait for the cluster to be ready.

Synopsis

Shows current cluster status, if the terminal supports it, watch the status as it updates. The command waits for the cluster to be ready by default.

omnictl cluster template status [flags]

Options

  -f, --file string     path to the cluster template file.
  -h, --help            help for status
  -q, --quiet           suppress output
  -w, --wait duration   wait timeout, if zero, report current status and exit (default 5m0s)

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl cluster template sync

Apply template to the Omni.

Synopsis

Query existing resources for the cluster and compare them with the resources generated from the template, create/update/delete resources as needed. This command requires API access.

omnictl cluster template sync [flags]

Options

  -d, --dry-run       dry run
  -f, --file string   path to the cluster template file.
  -h, --help          help for sync
  -v, --verbose       verbose output (show diff for each resource)

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl cluster template validate

Validate a cluster template.

Synopsis

Validate that template contains valid structures, and there are no other warnings. This command is offline (doesn’t access API).

omnictl cluster template validate [flags]

Options

  -f, --file string   path to the cluster template file.
  -h, --help          help for validate

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl cluster template

Cluster template management subcommands.

Synopsis

Commands to render, validate, manage cluster templates.

Options

  -h, --help   help for template

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl cluster

Cluster-related subcommands.

Synopsis

Commands to destroy clusters and manage cluster templates.

Options

  -h, --help   help for cluster

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl completion bash

Generate the autocompletion script for bash

Synopsis

Generate the autocompletion script for the bash shell.

This script depends on the ‘bash-completion’ package. If it is not installed already, you can install it via your OS’s package manager.

To load completions in your current shell session:

source <(omnictl completion bash)

To load completions for every new session, execute once:

Linux:

omnictl completion bash > /etc/bash_completion.d/omnictl

macOS:

omnictl completion bash > $(brew --prefix)/etc/bash_completion.d/omnictl

You will need to start a new shell for this setup to take effect.

omnictl completion bash

Options

  -h, --help              help for bash
      --no-descriptions   disable completion descriptions

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl completion fish

Generate the autocompletion script for fish

Synopsis

Generate the autocompletion script for the fish shell.

To load completions in your current shell session:

omnictl completion fish | source

To load completions for every new session, execute once:

omnictl completion fish > ~/.config/fish/completions/omnictl.fish

You will need to start a new shell for this setup to take effect.

omnictl completion fish [flags]

Options

  -h, --help              help for fish
      --no-descriptions   disable completion descriptions

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl completion powershell

Generate the autocompletion script for powershell

Synopsis

Generate the autocompletion script for powershell.

To load completions in your current shell session:

omnictl completion powershell | Out-String | Invoke-Expression

To load completions for every new session, add the output of the above command to your powershell profile.

omnictl completion powershell [flags]

Options

  -h, --help              help for powershell
      --no-descriptions   disable completion descriptions

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl completion zsh

Generate the autocompletion script for zsh

Synopsis

Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:

echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions in your current shell session:

source <(omnictl completion zsh)

To load completions for every new session, execute once:

Linux:

omnictl completion zsh > "${fpath[1]}/_omnictl"

macOS:

omnictl completion zsh > $(brew --prefix)/share/zsh/site-functions/_omnictl

You will need to start a new shell for this setup to take effect.

omnictl completion zsh [flags]

Options

  -h, --help              help for zsh
      --no-descriptions   disable completion descriptions

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl completion

Generate the autocompletion script for the specified shell

Synopsis

Generate the autocompletion script for omnictl for the specified shell. See each sub-command’s help for details on how to use the generated script.

Options

  -h, --help   help for completion

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl config add

Add a new context

omnictl config add <context> [flags]

Options

      --basic-auth string   basic auth credentials
  -h, --help                help for add
      --identity string     identity to use for authentication
      --url string          URL of the server (default "grpc://127.0.0.1:8080")

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl config basic-auth

Set the basic auth credentials

omnictl config basic-auth <username> <password> [flags]

Options

  -h, --help   help for basic-auth

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl config context

Set the current context

omnictl config context <context> [flags]

Options

  -h, --help   help for context

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl config contexts

List defined contexts

omnictl config contexts [flags]

Options

  -h, --help   help for contexts

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl config identity

Set the auth identity for the current context

omnictl config identity <identity> [flags]

Options

  -h, --help   help for identity

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl config info

Show information about the current context

omnictl config info [flags]

Options

  -h, --help   help for info

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl config merge

Merge additional contexts from another client configuration file

Synopsis

Contexts with the same name are renamed while merging configs.

omnictl config merge <from> [flags]

Options

  -h, --help   help for merge

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl config new

Generate a new client configuration file

omnictl config new [<path>] [flags]

Options

      --basic-auth string   basic auth credentials
  -h, --help                help for new
      --identity string     identity to use for authentication
      --url string          URL of the server (default "grpc://127.0.0.1:8080")

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl config url

Set the URL for the current context

omnictl config url <url> [flags]

Options

  -h, --help   help for url

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl config

Manage the client configuration file (omniconfig)

Options

  -h, --help   help for config

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl delete

Delete a specific resource by ID or all resources of the type.

Synopsis

Similar to ‘kubectl delete’, ‘omnictl delete’ initiates resource deletion and waits for the operation to complete.

omnictl delete <type> [<id>] [flags]

Options

      --all                Delete all resources of the type.
  -h, --help               help for delete
  -n, --namespace string   The resource namespace. (default "default")
  -l, --selector string    Selector (label query) to filter on, supports '=' and '==' (e.g. -l key1=value1,key2=value2)

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl download

Download installer media

Synopsis

This command downloads installer media from the server

It accepts one argument, which is the name of the image to download. Name can be one of the following:

 * iso - downloads the latest ISO image
 * AWS AMI (amd64), Vultr (arm64), Raspberry Pi 4 Model B - full image name
 * oracle, aws, vmware - platform name
 * rockpi_4, rock64 - board name

To get the full list of available images, look at the output of the following command: omnictl get installationmedia -o yaml

The download command tries to match the passed string in this order:

* name
* profile

By default it will download amd64 image if there are multiple images available for the same name.

For example, to download the latest ISO image for arm64, run:

omnictl download iso --arch amd64

To download the latest Vultr image, run:

omnictl download "vultr"

To download the latest Radxa ROCK PI 4 image, run:

omnictl download "rockpi_4"

omnictl download <image name> [flags]

Options

      --arch string                  Image architecture to download (amd64, arm64) (default "amd64")
  -h, --help                         help for download
      --initial-labels stringArray   Bake initial labels into the generated installation media
      --output string                Output file or directory, defaults to current working directory (default ".")

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl get

Get a specific resource or list of resources.

Synopsis

Similar to ‘kubectl get’, ‘omnictl get’ returns a set of resources from the OS. To get a list of all available resource definitions, issue ‘omnictl get rd’

omnictl get <type> [<id>] [flags]

Options

  -h, --help                     help for get
      --id-match-regexp string   Match resource ID against a regular expression.
  -n, --namespace string         The resource namespace. (default "default")
  -o, --output string            Output format (json, table, yaml, jsonpath). (default "table")
  -l, --selector string          Selector (label query) to filter on, supports '=' and '==' (e.g. -l key1=value1,key2=value2)
  -w, --watch                    Watch the resource state.

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl kubeconfig

Download the admin kubeconfig of a cluster

Synopsis

Download the admin kubeconfig of a cluster. If merge flag is defined, config will be merged with ~/.kube/config or [local-path] if specified. Otherwise kubeconfig will be written to PWD or [local-path] if specified.

omnictl kubeconfig [local-path] [flags]

Options

  -c, --cluster string              cluster to use
  -f, --force                       force overwrite of kubeconfig if already present, force overwrite on kubeconfig merge
      --force-context-name string   force context name for kubeconfig merge
      --groups strings              group to be used in the service account token (groups). only used when --service-account is set to true (default [system:masters])
  -h, --help                        help for kubeconfig
  -m, --merge                       merge with existing kubeconfig (default true)
      --service-account             create a service account type kubeconfig instead of a OIDC-authenticated user type
      --ttl duration                ttl for the service account token. only used when --service-account is set to true (default 8760h0m0s)
      --user string                 user to be used in the service account token (sub). required when --service-account is set to true

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl machine-logs

Get logs for a machine

Synopsis

Get logs for a provided machine id

omnictl machine-logs machineID [flags]

Options

  -f, --follow              specify if the logs should be streamed
  -h, --help                help for machine-logs
      --log-format string   log format (raw, omni, dmesg) to display (default is to display in raw format) (default "raw")
      --tail int32          lines of log file to display (default is to show from the beginning) (default -1)

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl serviceaccount create

Create a service account

omnictl serviceaccount create <name> [flags]

Options

  -h, --help            help for create
  -r, --role string     role of the service account. only used when --use-user-role=false
  -t, --ttl duration    TTL for the service account key (default 8760h0m0s)
  -u, --use-user-role   use the role of the creating user. if true, --role is ignored (default true)

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl serviceaccount destroy

Destroy a service account

omnictl serviceaccount destroy <name> [flags]

Options

  -h, --help   help for destroy

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl serviceaccount list

List service accounts

omnictl serviceaccount list [flags]

Options

  -h, --help   help for list

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl serviceaccount renew

Renew a service account by registering a new public key to it

omnictl serviceaccount renew <name> [flags]

Options

  -h, --help           help for renew
  -t, --ttl duration   TTL for the service account key (default 8760h0m0s)

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl serviceaccount

Manage service accounts

Options

  -h, --help   help for serviceaccount

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl talosconfig

Download the admin talosconfig of a cluster

Synopsis

Download the admin talosconfig of a cluster. If merge flag is defined, config will be merged with ~/.talos/config or [local-path] if specified. Otherwise talosconfig will be written to PWD or [local-path] if specified.

omnictl talosconfig [local-path] [flags]

Options

      --admin            get admin talosconfig (DEBUG-ONLY)
  -c, --cluster string   cluster to use
  -f, --force            force overwrite of talosconfig if already present
  -h, --help             help for talosconfig
  -m, --merge            merge with existing talosconfig (default true)

Options inherited from parent commands

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

omnictl

A CLI for accessing Omni API.

Options

      --context string             The context to be used. Defaults to the selected context in the omniconfig file.
  -h, --help                       help for omnictl
      --insecure-skip-tls-verify   Skip TLS verification for the Omni GRPC and HTTP API endpoints.
      --omniconfig string          The path to the omni configuration file. Defaults to 'OMNICONFIG' env variable if set, otherwise the config directory according to the XDG specification.

Reference

1 - Cluster Templates

Structure

Document Types

Cluster

ControlPlane

Workers

MachineClass

Note

UpdateStrategy

Machine

Note

Common Fields

patches

2 - Access Policies (ACLs)

Structure

AccessPolicy

UserGroup

User

ClusterGroup

Cluster

Rule

Role

Test

TestUser

TestCluster

Expected

3 - omnictl CLI

omnictl apply

Options

Options inherited from parent commands

SEE ALSO

omnictl cluster delete

Synopsis

Options

Options inherited from parent commands

SEE ALSO

omnictl cluster kubernetes manifest-sync

Synopsis

Options

Options inherited from parent commands

SEE ALSO

omnictl cluster kubernetes upgrade-pre-checks

Synopsis

Options

Options inherited from parent commands

SEE ALSO

omnictl cluster kubernetes

Synopsis

Options

Options inherited from parent commands

SEE ALSO

omnictl cluster machine lock

Synopsis

Options

Options inherited from parent commands

SEE ALSO

omnictl cluster machine unlock

Synopsis

Options

Options inherited from parent commands

SEE ALSO

omnictl cluster machine

Synopsis

Options

Options inherited from parent commands

SEE ALSO

omnictl cluster status

Synopsis

Options

Options inherited from parent commands

SEE ALSO

omnictl cluster template delete

Synopsis

Options

Options inherited from parent commands

SEE ALSO

omnictl cluster template diff

Synopsis

Options

`Cluster`

`ControlPlane`

`Workers`

`MachineClass`

`UpdateStrategy`

`Machine`

`patches`

`AccessPolicy`

`UserGroup`

`User`

`ClusterGroup`

`Cluster`

`Rule`

`Role`

`Test`

`TestUser`

`TestCluster`

`Expected`