Saltar a contenido

Ansible CI (plan/apply)

Automatización del bootstrap de k3s (k3s/ansible/) en GitHub Actions, sobre el runner self-hosted ARC (runs-on: homelab). Ver la página de servicio docs/services/ansible-ci.md y el diseño en docs/specs/2026-09-07-ansible-ci-design.md.

Workflows

Workflow Trigger Qué hace
ansible-plan.yml pull_request en k3s/ansible/** ansible-lint + --syntax-check + --check --diff + diff de helm template (traefik/argocd) comentado en la PR
ansible-apply.yml push a main en k3s/ansible/** + workflow_dispatch reejecución idempotente de site.yml

Clave SSH de CI (dedicada)

Es un keypair ed25519 exclusivo de CI, distinto de la clave personal.

Generar (una sola vez)

ssh-keygen -t ed25519 -C "gorkarevilla@ci" -f ci_key -N ""
  • ci_key.pub → a ci_ssh_keys en terraform/variables.tf (futuras VMs) y a mano al ~/.ssh/authorized_keys de ubuntu en los 3 nodos (cloud-init no re-inyecta en VMs ya existentes):
for ip in 192.168.20.10 192.168.20.11 192.168.20.12; do
  ssh ubuntu@$ip "mkdir -p ~/.ssh && grep -qF '$(cat ci_key.pub)' ~/.ssh/authorized_keys 2>/dev/null || echo '$(cat ci_key.pub)' >> ~/.ssh/authorized_keys"
done
  • ci_key (privada) → solo como GitHub secret:
gh secret set ANSIBLE_SSH_PRIVATE_KEY --repo gorkarevilla/homelab < ci_key
rm -f ci_key ci_key.pub   # la privada NO vive en el repo

Rotar

  1. Generar un keypair nuevo (arriba).
  2. Reemplazar la pública en los 3 nodos y en ci_ssh_keys.
  3. gh secret set ANSIBLE_SSH_PRIVATE_KEY ... con la privada nueva.
  4. Los runners efímeros recogen la clave nueva en la siguiente ejecución.

Secrets de GitHub

Secret Uso
ANSIBLE_SSH_PRIVATE_KEY clave privada CI (plan y apply)
ARGOCD_REPO_TOKEN PAT read-only para registrar el repo en Argo CD (solo apply; solo obligatorio en bootstrap limpio)

Orden secret → merge

Como el apply es automático al mergear, cualquier Secret (Vaultwarden → VKS) o certificado (cert-manager) que referencien los recursos debe estar sincronizado antes de mergear. El flujo de alta de secrets de AGENTS.md (.env → vaultwarden-import.json → importar → VKS sync ≤5 min) es prerrequisito del merge, no un paso posterior.

Re-ejecución manual

gh workflow run ansible-apply.yml --repo gorkarevilla/homelab

Limitaciones conocidas

  • --check salta las tareas command/shell (k3s, kubectl apply, helm upgrade): la vista es parcial; se complementa con el diff de helm template.
  • El plan no valida que existan los secrets/certs referenciados (no tiene kubeconfig): responsabilidad del flujo VKS/cert-manager antes del merge.
  • El render de helm template replica a mano las flags de helm de los roles (argocd/tasks/main.yml, traefik/tasks/main.yml): si esas flags cambian, hay que actualizar el paso en ansible-plan.yml en el mismo PR.

Bootstrap de la propia CI (una sola vez)

  1. Los workflows se introducen en un "PR de infra" que sí dispara la CI (añade k3s/ansible/.ansible-lint y los propios workflows): el plan corre en el pull_request y el apply se ejecuta al mergear sobre los 3 nodos.
  2. Generar la clave CI, inyectarla en los nodos + ci_ssh_keys, y dar de alta los GitHub secrets (arriba) — prerrequisito para que el apply no falle en el SSH.
  3. Añadir .ansible-lint (ya en el repo).
  4. A partir de ahí, cualquier PR que toque k3s/ansible/** dispara el plan.