Saltar a contenido

Bootstrap del cluster k3s

Procedimiento para arrancar la plataforma k3s sobre las VMs de Proxmox.

Precondiciones

  1. VMs encendidas: terraform/variables.tf ya deja started = true (default). Si no lo está, ponerlo para kobe, kyrie y kawhi, abrir el PR con el terraform plan y mergear (o arrancarlas a mano desde Proxmox).
  2. Red en VLAN 20: el bridge vmbr0 de Proxmox debe estar VLAN-aware (en Proxmox: luka → System → Network → vmbr0 → Edit → marcar "VLAN aware"). Las VMs se crean con vlan_id = 20 (ver terraform/variables.tf → network_vlan_id). El puerto físico de luka en UniFi ya es trunk (nativa Default + VLAN 20 taggeada), así que no hay que tocar el switch.
  3. Máquina de control con ansible-core, kubectl y helm.
  4. SSH: poder llegar a ubuntu@192.168.20.10/11/12 con la clave inyectada por cloud-init (ver variables.tf → ci_ssh_keys).

1. Preparar el PAT de GitHub (repo privado)

Argo CD necesita leer gorkarevilla/homelab (privado). Crea un fine-grained PAT con permiso de solo lectura (Contents: Read-only) sobre ese repo y exportalo:

export ARGOCD_REPO_TOKEN="github_pat_..."

Conveniencia: hay un .env local en la raíz del repo (gitignored) para guardar estos tokens de momento. Cárgalo con set -a; source ../.env; set +a desde k3s/ansible antes de lanzar el playbook.

No se commitea. Ansible lo lee de la variable de entorno (no se pasa como argumento, para no exponerlo en el listado de procesos). Si no lo defines, Argo CD se instala igual pero el repo queda sin registrar; se puede añadir después desde Settings → Repositories.

2. Ejecutar el bootstrap

cd k3s/ansible
ansible-playbook -i inventory/hosts.yml playbooks/site.yml

Qué hace (por orden): instala k3s server en kobe → une kyrie/kawhi → baja el kubeconfig → espera nodos Ready → despliega MetalLB → Traefik v3 + Gateway API → Argo CD + app-of-apps.

3. Verificar

ansible-playbook -i inventory/hosts.yml playbooks/verify.yml

Esperado: 3 nodos Ready, pods de MetalLB/Traefik Running, la Service traefik con IP externa 192.168.20.60 del pool, y la Application apps en Synced.

4. Acceso a Argo CD

  • UI: https://argocd.local.gorkarevilla.com (Traefik, wildcard TLS).
  • Usuario: admin. Password: la muestra el playbook al final (también en el secret argocd-initial-admin-secret). Guárdala en tu gestor de contraseñas.

5. kubeconfig

El kubeconfig queda en k3s/ansible/.kubeconfig (gitignored). Para usarlo:

export KUBECONFIG="$(pwd)/k3s/ansible/.kubeconfig"
kubectl get nodes

Re-ejecución

El playbook es idempotente: la instalación de k3s salta si ya existe, y helm upgrade --install reusa los releases. Puedes reejecutarlo para recuperar un nodo o aplicar cambios de configuración.

Limpiar / resetear (solo si es necesario)

Para desmontar el cluster por completo (¡destructivo!):

ssh ubuntu@192.168.20.11 sudo /usr/local/bin/k3s-agent-uninstall.sh
ssh ubuntu@192.168.20.12 sudo /usr/local/bin/k3s-agent-uninstall.sh
ssh ubuntu@192.168.20.10 sudo /usr/local/bin/k3s-uninstall.sh

Bootstrap vía CI

Para cambios en k3s/ansible/** el bootstrap ya no se hace a mano: la Ansible CI (ver docs/runbooks/ansible-ci.md) valida en el PR y aplica site.yml al mergear a main. El bootstrap desde cero (cluster nuevo) sigue siendo manual con este runbook.