> For the complete documentation index, see [llms.txt](https://docs.acecloud.ai/knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.acecloud.ai/knowledge-base/cli/kubernetes/clusters.md). # 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. ```bash 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. ```bash ace k8s cluster create \ --name \ --version \ --flavor \ --worker-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:** ```bash ace k8s cluster create \ --name my-cluster \ --version v1.32.6 \ --flavor ACE.CPU.4C16R \ --worker-name pool1 ``` **Multi-node with custom volume size:** ```bash 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:** ```bash ace k8s cluster create \ --name gpu-cluster \ --version v1.32.6 \ --flavor ACE.GPU.A100 \ --worker-name gpu-pool \ --gpu ``` **With autoscaling:** ```bash 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:** ```bash ace k8s cluster create \ --name secure-cluster \ --version v1.32.6 \ --flavor ACE.CPU.4C16R \ --worker-name pool1 \ --security-group \ --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. ```bash 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:** ```bash ace k8s cluster list -o json ``` *** ## Get / Show Get detailed information about a specific cluster. Accepts cluster name or ID. ```bash ace k8s cluster get ``` **Examples:** ```bash 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. ```bash ace k8s cluster delete ``` **Examples:** ```bash 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. ```bash ace k8s cluster kubeconfig ``` By default the YAML kubeconfig is written to stdout, ready to redirect into a file or pipe into `kubectl`. **Save to file:** ```bash ace k8s cluster kubeconfig my-cluster > ~/.kube/config ``` **Merge with existing config:** ```bash 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": ""}`. Useful for piping into `jq` or automation. | ```bash # JSON wrapper (handy for jq pipelines) ace k8s cluster kubeconfig my-cluster -o json | jq -r .kubeconfig > ~/.kube/config ``` **Verify access:** ```bash 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. ```bash ace k8s cluster nodes [--pool ] ``` ### 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:** ```bash ace k8s cluster nodes my-cluster ``` **Filter by pool:** ```bash 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:** ```bash 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 |