kubectl (Kubernetes CLI)

What it is

kubectl is the Kubernetes control client: apply manifests, inspect workloads, stream logs, exec into pods. It talks to any cluster via a kubeconfig.

Install

Static binary, current stable (x86_64; swap amd64→arm64 for ARM):

curl -fsSLO "https://dl.k8s.io/release/$(curl -fsSL https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -m 0755 kubectl /usr/local/bin/kubectl && rm kubectl

Or the Google apt repo (sudo apt install kubectl after adding pkgs.k8s.io). Keep the client within one minor version of the server.

Authenticate

Auth is the kubeconfig, not a login command:

export KUBECONFIG=~/.kube/config           # default
kubectl config get-contexts
kubectl config use-context <context>

Kubeconfigs are bearer secrets — keep them mode 600, and archive copies in Vaultwarden (https://vault.portugalfuturista.org).

Configure for this environment

No production cluster yet on the Proxmox fleet; the plan is k3s (below). For cloud clusters, fetch credentials with the vendor CLI:

gcloud container clusters get-credentials <name> --zone <zone>
aws eks update-kubeconfig --name <name>

Self-hosted equivalent

k3s — lightweight Kubernetes, ideal on a Proxmox CT/VM (asus or gigabyte):

# on the node (Debian/Ubuntu CT, privileged or with nesting enabled)
curl -sfL https://get.k3s.io | sh -
sudo cat /etc/rancher/k3s/k3s.yaml    # copy to laptop ~/.kube/config

On the laptop, edit the server: line to https://<node-ip>:6443 and:

kubectl get nodes
# NAME   STATUS   ROLES                AGE   VERSION
# k3s1   Ready    control-plane,master 1m    v1.x.y+k3s1

For a pure-laptop dev cluster, k3d (k3s in Docker) is the fastest option.

Aurélio integration

The cli-devops skill uses kubectl/helm for cluster operations. Connector registry id: kubernetes.

Verify

kubectl version --client
# Client Version: v1.x.y ...
kubectl get --raw /readyz    # against a configured cluster
# ok

Troubleshooting

connection refused to 127.0.0.1:8080 — no context set; run kubectl config get-contexts and use-context.
k3s kubeconfig 403 on the laptop — you copied k3s.yaml but left server: https://127.0.0.1:6443; point it at the node IP.
Version skew warnings — keep kubectl within ±1 minor of the server; reinstall from dl.k8s.io/release/stable.txt.
Proxmox CT can't run k3s — enable nesting/keyctl or use an unprivileged-with-features CT; plain VMs are the least-friction path.

2.6 KiB Raw Permalink Blame History