K3s Node

OverviewCopy Anchor Link

Production runs on a single VM, k3s01, created by Terraform (environments/k3s) and configured by the Ansible playbooks in polinetwork-cd/ansible.

DisksCopy Anchor Link

Ansible finds the data disks by Azure LUN, refuses to touch a disk that is smaller than expected or holds an unexpected filesystem, formats them only when blank and mounts them by UUID. Both disks have prevent_destroy in Terraform.

See Add Storage for how volumes are carved out of these disks.

What Ansible sets upCopy Anchor Link

The provisioning playbook (ansible/playbooks/provision.yml) applies these roles, in order:

After that, Flux takes over everything inside the cluster (see Flux).

Notable K3s settingsCopy Anchor Link

• Pod and Service CIDRs are 10.52.0.0/16 and 10.53.0.0/16. The K3s default 10.43.0.0/16 would collide with the Azure VNet.
• ServiceLB and the bundled local-storage are disabled. Storage comes from the local-path provisioner managed by Flux.
• The bundled Traefik stays as the ingress controller, but Flux turns its Service into ClusterIP: only cloudflared reaches it.
• Secrets encryption at rest is enabled.
• The API server signs service-account tokens for a public OIDC issuer (pnk3soidc storage account). Azure trusts that issuer, which is how External Secrets reads Key Vault without any stored credential.

Security guardrailsCopy Anchor Link

• The VM's public IP is outbound-only: the NSG denies all inbound traffic. The host firewall also drops everything except the node itself, cluster traffic, and SSH from private ranges (WARP sessions arrive from the cloudflared pods).
• Pods cannot reach the Azure Instance Metadata Service (169.254.169.254), so they can't borrow the VM's managed identities.
• An admission policy rejects pods using hostNetwork, hostPID or hostIPC outside kube-system, and another one forbids pods from running as the keyvault-reader service account.

Running the playbooksCopy Anchor Link

The playbooks run from your machine against 10.43.1.4 over SSH, so connect WARP first.

cd ansible
ansible-galaxy collection install -r requirements.yml
./scripts/provision-and-verify.sh

The script is the only supported way to apply changes. It runs the playbook in check mode, then applies it twice and fails if the second run still changes something (the playbook must be idempotent). Finally it runs playbooks/verify.yml, which checks the disks, the K3s version, the firewall, the SSH configuration, that Flux is ready, that pods can't reach Azure IMDS, and it takes and validates a fresh backup. Logs are saved in ansible/artifacts/ (ignored by Git).

To run from inside the VM (for example through Azure Run Command), put a reviewed checkout on the VM and run:

./scripts/provision-and-verify.sh inventories/local/hosts.yml

CICopy Anchor Link

The Ansible workflow in polinetwork-cd runs on every pull request that touches ansible/, clusters/k3s/, infrastructure/, apps/ or tests/. It runs ansible-lint, shellcheck, a playbook syntax check, kustomize build on every Flux path and the manifest tests in tests/. It does not touch the VM.

Upgrading K3sCopy Anchor Link

1. Pick a release from K3s releases and download its k3s-arm64 binary checksum.
2. Update k3s_version, k3s_release_url and k3s_sha256 in ansible/vars/main.yml.
3. Open a PR, merge it, then run ./scripts/provision-and-verify.sh. K3s restarts with the new binary; workloads come back on their own.

The Flux Operator is upgraded the same way (flux_operator_* and flux_distribution_version).