Clusters

Manage Kubernetes cluster lifecycle: create, list, inspect, delete, retrieve kubeconfig, check available versions, and list nodes.

---

Versions

List available Kubernetes versions for cluster creation.

ace k8s cluster versions

Example output:

Available Kubernetes Versions:
  v1.32.6
  v1.31.10
  v1.30.14

The CLI uses the display label (e.g. v1.32.6) and automatically resolves it to the full RKE2 version value (e.g. v1.32.6+rke2r1) at creation time.

---

Create

Create a new managed Kubernetes cluster.

ace k8s cluster create \
  --name <cluster-name> \
  --version <k8s-version> \
  --flavor <flavor-name-or-id> \
  --worker-name <pool-name> \
  [options]

Required Flags

Flag	Description
--name	Cluster name (lowercase alphanumeric with hyphens, max 63 chars)
--version	Kubernetes version (use ace k8s cluster versions to list)
--flavor	Flavor name or UUID for worker nodes (use ace flavor list)
--worker-name	Name for the initial worker node pool

Optional Flags

Flag	Default	Description
--worker-count	1	Number of worker nodes (1-8)
--volume-size	50	Volume size in GB per worker node (20-256)
--endpoint-access	Public	API endpoint access: Public, Private, or Public and Private
--network-isolation	Disabled	Network isolation: Enabled or Disabled
--nginx-ingress	Enabled	Nginx ingress controller: Enabled or Disabled
--nginx-default-backend	Enabled	Nginx default backend: Enabled or Disabled
--network-provider	Calico	Network provider (currently only Calico)
--snapshot-backup	No	Enable ETCD snapshot backup: Yes or No
--secrets-encryption	Disabled	Secrets encryption: Enabled or Disabled
--max-worker-nodes	8	Maximum number of worker nodes allowed
--security-group		Security group UUID to attach
--gpu	false	Mark as GPU flavor
--autoscale	false	Enable cluster autoscaling (can only be set at creation)
--autoscale-min	1	Minimum nodes for autoscaling
--autoscale-max	3	Maximum nodes for autoscaling

Examples

Minimal cluster:

ace k8s cluster create \
  --name my-cluster \
  --version v1.32.6 \
  --flavor ACE.CPU.4C16R \
  --worker-name pool1

Multi-node with custom volume size:

ace k8s cluster create \
  --name prod-cluster \
  --version v1.32.6 \
  --flavor ACE.CPU.8C32R \
  --worker-name workers \
  --worker-count 3 \
  --volume-size 100

GPU cluster:

ace k8s cluster create \
  --name gpu-cluster \
  --version v1.32.6 \
  --flavor ACE.GPU.A100 \
  --worker-name gpu-pool \
  --gpu

With autoscaling:

ace k8s cluster create \
  --name auto-cluster \
  --version v1.32.6 \
  --flavor ACE.CPU.4C16R \
  --worker-name pool1 \
  --autoscale \
  --autoscale-min 1 \
  --autoscale-max 5

With security group and ETCD snapshots:

ace k8s cluster create \
  --name secure-cluster \
  --version v1.32.6 \
  --flavor ACE.CPU.4C16R \
  --worker-name pool1 \
  --security-group <sg-uuid> \
  --snapshot-backup Yes \
  --secrets-encryption Enabled

Note: Autoscaling can only be enabled at cluster creation time. It cannot be toggled after the cluster is created. When autoscaling is enabled, --autoscale-max must be less than or equal to --max-worker-nodes.

---

List

List all Kubernetes clusters in the current project and region.

ace k8s cluster list

Example output:

NAME                      ID                   STATE        K8S VERSION    PODS       CPU        MEMORY
my-cluster                c-m-abc123           active       v1.32.6        12/110     4/16       8/32 GiB

JSON output:

ace k8s cluster list -o json

---

Get / Show

Get detailed information about a specific cluster. Accepts cluster name or ID.

ace k8s cluster get <cluster-name-or-id>

Examples:

ace k8s cluster get my-cluster
ace k8s cluster show c-m-abc123

Example output:

  Name:                    my-cluster
  ID:                      c-m-abc123
  State:                   active
  K8s Version:             v1.32.6
  Nodes:                   2
  Deployments:             5
  Total Resources:         12
  Endpoint:                https://rancher.example.com/dashboard/...
  Age:                     3d
  Created:                 2025-03-15T10:30:00Z

---

Delete

Delete a Kubernetes cluster. Accepts cluster name or ID.

ace k8s cluster delete <cluster-name-or-id>

Examples:

ace k8s cluster delete my-cluster
ace k8s cluster rm c-m-abc123

Note: Deleting the last cluster in a project will tear down all K8s infrastructure for that project.

---

Kubeconfig

Generate a kubeconfig file for kubectl access to a cluster.

ace k8s cluster kubeconfig <cluster-name-or-id>

By default the YAML kubeconfig is written to stdout, ready to redirect into a file or pipe into kubectl.

Save to file:

ace k8s cluster kubeconfig my-cluster > ~/.kube/config

Merge with existing config:

ace k8s cluster kubeconfig my-cluster > ~/.kube/ace-cluster.yaml
export KUBECONFIG=~/.kube/config:~/.kube/ace-cluster.yaml

Output format

The --output / -o flag is honoured:

Format	Output
table (default)	Raw YAML kubeconfig on stdout — ready for redirection into ~/.kube/config.
yaml	Raw YAML kubeconfig (identical to table for this command).
json	A wrapper object: {"kubeconfig": "<yaml-as-string>"}. Useful for piping into jq or automation.

# JSON wrapper (handy for jq pipelines)
ace k8s cluster kubeconfig my-cluster -o json | jq -r .kubeconfig > ~/.kube/config

Verify access:

kubectl get nodes
kubectl get pods --all-namespaces

---

Nodes

List nodes in a Kubernetes cluster. When no --pool is specified, the CLI automatically queries all node pools and merges the results.

ace k8s cluster nodes <cluster-name-or-id> [--pool <pool-name>]

Flags

Flag	Description
--cluster	Alternative to positional argument for cluster name/ID
--pool	Filter nodes by a specific node pool name

Examples

List all nodes across all pools:

ace k8s cluster nodes my-cluster

Filter by pool:

ace k8s cluster nodes my-cluster --pool pool1

Example output:

NAME                           STATE        POOL
my-cluster-pool1-abc123-x9k2z  active       pool1
my-cluster-pool1-abc123-y8j3w  active       pool1

The table view auto-hides columns that are uniformly empty across the row set (e.g. ID, IP, AGE are dropped when the backend hasn't populated them yet). Use -o json for the full per-node payload.

Full payload:

ace k8s cluster nodes my-cluster -o json

---

Global Flags

All K8s commands support these global flags:

Flag	Description
-o, --output	Output format: table (default) or json
-v, --verbose	Show full JSON response
--project	Override project ID
--region	Override region