Runbook — Talos Linux Image & Node Deployment di Incus Cluster#

Cluster: trim-computes-shr-incus-01 s/d 04 (Lenovo ThinkAgile HX630, Debian 13, Incus 7.2 Zabbly) Storage: lvmcluster di QNAP iSCSI — pool-qnap-hdd-01 (cluster-wide) Talos: v1.13.7, schematic Image Factory 376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba Terakhir diperbarui: 25 Juli 2026

1. Konsep — Kenapa Talos BEDA dari Template Windows#

Talos itu immutable OS untuk Kubernetes: tidak ada SSH, tidak ada shell, tidak ada package install. Node dikelola sepenuhnya via API (talosctl) dengan machine config.

Konsekuensinya untuk workflow template:

Sumber kebenaran selalu file image dari Image Factory — bukan VM yang pernah hidup.

2. Image Factory — Generate & Download#

1. Buka https://factory.talos.dev → Metal → amd64 → pilih versi.
2. System Extensions: mayoritas hardware extension (ENA, amdgpu, ucode, NIC firmware) TIDAK relevan untuk VM — driver virtio sudah built-in. Yang layak dipertimbangkan untuk environment kita:
   • siderolabs/iscsi-tools + siderolabs/util-linux-tools — WAJIB kalau akan pakai persistent storage K8s via iSCSI ke QNAP (democratic-csi, Longhorn, OpenEBS).
   • siderolabs/qemu-guest-agent — opsional, manfaat tipis (Incus tidak meng-consume QGA).
   • Extension nambah belakangan = schematic baru + talosctl upgrade semua node (reboot). Lebih murah mikir sekarang.
3. Download Disk Image biasa: metal-amd64.raw.zst.
   • ❌ BUKAN ISO (kita import sebagai disk image, bukan boot installer).
   • ❌ BUKAN varian SecureBoot — image itu di-sign key Sidero Labs, OVMF Incus hanya bawa cert Microsoft; butuh enroll key manual per VM tanpa manfaat di internal cluster. Jalur kita security.secureboot=false.
4. CATAT dua string ini (identitas kombinasi extension):
   • Schematic ID: 376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba
   • Installer image (non-secureboot): factory.talos.dev/metal-installer/<schematic-id>:v1.13.7 — dipakai di machine.install.image dan talosctl upgrade.

mkdir -p ~/templates/talos && cd ~/templates/talos
wget https://factory.talos.dev/image/<schematic-id>/v1.13.7/metal-amd64.raw.zst

3. Import sebagai Incus Image#

cd ~/templates/talos

# decompress (butuh: apt install zstd)
unzstd metal-amd64.raw.zst

# raw → qcow2 (hanya blok allocated yang terbawa, hasilnya kecil)
qemu-img convert -f raw -O qcow2 metal-amd64.raw talos-disk.qcow2
qemu-img info talos-disk.qcow2

# metadata image
cat > metadata.yaml <<EOF
architecture: x86_64
creation_date: $(date +%s)
properties:
  description: Talos Linux v1.13.7 metal (schematic 376567988a)
  os: talos
  release: v1.13.7
EOF
tar czf metadata.tar.gz metadata.yaml

# import — alias SELALU ber-versi
incus image import metadata.tar.gz talos-disk.qcow2 --alias talos-v1.13.7 --project Templates
incus image list --project Templates

Rationale jalur import: bug lvmcluster #3705 ada di arah publish/EXPORT. Arah import/launch-from-image proven jalan di cluster ini (semua VM Rocky lahir dari image). Versi Talos baru = import baru side-by-side (talos-v1.14.x), jangan menimpa alias lama.

Image lintas project#

Image namespace itu per-project. Kalau launch dari project lain (default, Staging) error image not found:

incus image copy local:talos-v1.13.7 local: \
  --project Templates --target-project <project-tujuan> --copy-aliases

4. Profile Node Talos (sekali bikin)#

Buat per project yang akan menjalankan node (profile juga per-project):

incus profile create os-trim-talos --project <project> <<EOF
config:
  security.secureboot: "false"
  limits.cpu: "2"
  limits.memory: 4GiB
description: Talos Linux node baseline
devices: {}
EOF

Network device pakai profile net-vlan existing (pola yang sama dengan VM lain). Sizing acuan: control plane 2 CPU / 4GiB / disk 20GiB; worker sesuai beban, disk lebih besar kalau image container banyak.

security.secureboot=false itu WAJIB — tanpa ini OVMF menolak kernel Talos (tidak di-sign Microsoft) dan VM gagal boot dengan gejala mirip BdsDxe/access denied.

5. Launch Node#

incus launch talos-v1.13.7 <nama-node> --vm --project <project> \
  --target <node-incus> \
  -p default -p os-trim-talos -p <profile-network> \
  -d root,size=20GiB

Begitu memakai -p, profile default TIDAK otomatis ikut — sebut eksplisit di urutan pertama supaya root disk & baseline tetap terbawa.

Verifikasi via console (satu-satunya “layar” Talos):

incus console <nama-node> --type=vga --project <project>

Yang dicari: dashboard Talos dengan STAGE: Maintenance + IP dari DHCP. Sampai titik ini node belum punya identitas apa pun — aman, memang begitu.

IP visibility: incus info TIDAK akan menampilkan IP (tidak ada agent). Sumber IP: dashboard console, DHCP lease di VLAN, atau ARP switch. Untuk produksi: buat static DHCP reservation per MAC supaya IP node deterministik.

6. Bootstrap Cluster Kubernetes (sekali per cluster)#

Dari workstation yang terinstall talosctl (bukan dari dalam node):

# 1. Generate config cluster — SIMPAN direktori ini (berisi CA & secrets!)
talosctl gen config <nama-cluster-k8s> https://<ip-cp-01>:6443

# edit controlplane.yaml / worker.yaml sesuai kebutuhan, minimal pastikan:
#   machine.install.disk: /dev/sda
#   machine.install.image: factory.talos.dev/metal-installer/<schematic-id>:v1.13.7

# 2. Apply ke node maintenance mode (per node, --insecure hanya untuk apply pertama)
talosctl apply-config --insecure -n <ip-cp-01> --file controlplane.yaml
# node install ke disk → reboot → jadi control plane

# 3. Bootstrap etcd — SEKALI SAJA, di CP pertama SAJA
talosctl --talosconfig talosconfig bootstrap -n <ip-cp-01>

# 4. Ambil kubeconfig
talosctl --talosconfig talosconfig kubeconfig -n <ip-cp-01>
kubectl get nodes

Scaling worker = launch VM dari image (§5) + apply worker.yaml:

talosctl apply-config --insecure -n <ip-worker-baru> --file worker.yaml

⚠️ File secrets hasil gen config (talosconfig, CA, dsb) = kunci cluster. Simpan di secret manager (pola GCP Secret Manager seperti credentials Nutanix), JANGAN di git polos.

7. Upgrade#

• Talos OS: talosctl upgrade -n <ip> --image factory.talos.dev/metal-installer/<schematic-id>:<versi-baru> — node handle sendiri (drain-less A/B upgrade). Image Incus TIDAK terlibat.
• Kubernetes: talosctl upgrade-k8s -n <ip-cp> --to <versi>.
• Image Incus: hanya untuk node BARU — import versi baru dengan alias baru saat rilis, image lama biarkan sampai tidak ada kebutuhan rollback.
• Ganti/tambah extension: generate schematic baru di factory (ID berubah!) → catat ID baru → upgrade node ke installer image schematic baru + import disk image baru untuk node berikutnya.

8. Larangan: incus publish pada Talos#

JANGAN pernah publish VM Talos jadi image:

1. VM yang sudah ter-apply config membawa identitas node (certs, etcd member ID, hostname) — semua clone lahir sebagai “node yang sama” → konflik etcd.
2. Redundan — image pristine sudah kita punya dari factory (arah hulu).
3. Bug publish lvmcluster (#3705) tetap berlaku di build saat ini.

Butuh “template”? Itu = file metal-amd64.raw.zst + schematic ID. Selesai.

9. Troubleshooting#

11. Referensi#

• Image Factory: https://factory.talos.dev (schematic 376567988a...b4ba)
• Talos docs — getting started & machine config: https://www.talos.dev/latest/
• Runbook terkait: runbook-template-windows-server-2022.md (bug lvmcluster #3705, konvensi project/pool cluster)
• Fix upstream lvmcluster publish: https://github.com/lxc/incus/pull/3705