CLI: K3s Cluster Management

Overview

The agentmetal k3s subcommand manages lightweight Kubernetes (K3s) clusters. K3s is a certified Kubernetes distribution optimized for resource-constrained environments while remaining fully compatible with standard Kubernetes APIs.

Operations

Create a Cluster

agentmetal k3s create \
  --name production \
  --version 1.28 \
  --masters 3 \
  --workers 5 \
  --pod-cidr 10.42.0.0/16 \
  --service-cidr 10.43.0.0/16

Flag	Required	Description
`--name`	Yes	Cluster name
`--version`	No	K3s version (default: latest stable)
`--masters`	No	Number of master nodes (default: 1, use 3 for HA)
`--workers`	No	Number of worker nodes (default: 2)
`--pod-cidr`	No	CIDR range for pod networking (default: 10.42.0.0/16)
`--service-cidr`	No	CIDR range for service networking (default: 10.43.0.0/16)

### List Clusters

agentmetal k3s list

ID           NAME         VERSION   MASTERS   WORKERS   STATE
k3s-a1b2c3   production   1.28      3         5         running
k3s-d4e5f6   staging      1.28      1         2         running

Get Cluster Details

agentmetal k3s get k3s-a1b2c3

Retrieve Kubeconfig

agentmetal k3s get k3s-a1b2c3 --kubeconfig

This outputs the kubeconfig YAML which can be saved to a file:

agentmetal k3s get k3s-a1b2c3 --kubeconfig > ~/.kube/config
kubectl get nodes

Delete a Cluster

agentmetal k3s delete k3s-a1b2c3

K3sClusterSpec Fields

Field	Type	Description
`version`	string	K3s version (e.g., `1.28`)
`master_count`	int	Number of control plane nodes
`worker_count`	int	Number of worker nodes
`pod_cidr`	string	Pod network CIDR
`service_cidr`	string	Service network CIDR

## Examples

Create an HA cluster and use kubectl:

# Create a high-availability cluster
agentmetal k3s create --name prod --version 1.28 --masters 3 --workers 5
Retrieve kubeconfig
agentmetal k3s get k3s-abc123 --kubeconfig > /tmp/kubeconfig.yaml
export KUBECONFIG=/tmp/kubeconfig.yaml
Verify the cluster
kubectl get nodes
kubectl get pods -A