Kubernetes

The Kubernetes service provides managed lightweight Kubernetes clusters backed by K3s. The Kubernetes Agent handles cluster creation, node management, high availability, and ongoing maintenance.

Features

• K3s — lightweight, certified Kubernetes distribution ideal for bare-metal deployments
• HA control plane — deploy 3 or more masters with embedded etcd for high availability
• Auto-joining workers — new worker nodes are automatically configured and joined to the cluster
• Kubeconfig management — retrieve cluster credentials with a single command
• Version management — upgrade clusters to new K3s versions with rolling updates

Create a Cluster

Basic Cluster

agentmetal k3s create \
  --name staging \
  --version v1.28 \
  --masters 1 \
  --workers 3

HA Cluster

agentmetal k3s create \
  --name production \
  --version v1.28 \
  --masters 3 \
  --workers 5 \
  --vpc prod

An HA cluster uses 3 master nodes with embedded etcd for control plane redundancy.

Get Kubeconfig

Retrieve the kubeconfig file to interact with your cluster using kubectl:

agentmetal k3s get staging --kubeconfig > ~/.kube/staging.yaml
export KUBECONFIG=~/.kube/staging.yaml
kubectl get nodes

Scale Workers

Add more worker nodes to an existing cluster:

agentmetal k3s scale staging --workers 8

The agent provisions new VMs, installs K3s in agent mode, and joins them to the cluster.

Upgrade

Upgrade the cluster to a new K3s version:

agentmetal k3s upgrade staging --version v1.29

The agent performs a rolling upgrade: masters first (one at a time), then workers, with drain and cordon for zero-downtime upgrades.

What the Agent Manages

The Kubernetes Agent performs these operations:

1. K3s installation — installs K3s on master and worker nodes with the appropriate configuration flags
2. Node token distribution — securely distributes the node join token to worker nodes
3. HA setup — for multi-master clusters, configures embedded etcd and ensures all masters are clustered
4. Cluster health — monitors node readiness, pod scheduling, and control plane component health
5. Certificate rotation — manages K3s TLS certificates and rotates them before expiry
6. Upgrade orchestration — coordinates rolling upgrades across the cluster with drain/cordon/uncordon

Instance Types

Kubernetes nodes are provisioned as Compute instances. Recommended sizes:

## Networking

K3s uses Flannel for pod networking by default. When placed in a VPC, the cluster network is isolated from other VPCs and accessible only through the WireGuard overlay.