Saltar a contenido

GitOps — catálogo y troubleshooting

Parte de la guía de implementación

El recorrido paso a paso está en Fase 4 — GitOps. Ansible bootstrap (K3s, red): Fases 0–3.

Referencia de Applications Argo CD y resolución de problemas. Manifiestos en gitops/.

Documentación relacionada:

Dos repos, dos responsabilidades

Repo Qué instala Herramienta
homelab K3s binario, kube-vip CP, controller ArgoCD, red SO Ansible
gitops MetalLB, Gateway API, storage, vCluster, CAPN, … Argo CD
flowchart LR
  A[Ansible bootstrap] --> B[ArgoCD controller]
  B --> C[ApplicationSet homelab-root]
  C --> D[Apps descomentadas, por olas -1 a 3]
  D --> E[Apps manual]

Catálogo de componentes GitOps

Cada fila es una Application de ArgoCD (salvo manifiestos auxiliares). Sync auto = la sincroniza homelab-root (si está descomentada en root-appset.yaml); manual = queda comentada hasta que la actives.

Bootstrap

Manifiesto Sync Para qué sirve
bootstrap/root-appset.yaml Una vez, a mano ApplicationSet: genera la Application raíz homelab-root con las apps descomentadas de su lista, desplegadas por olas. Es el único kubectl apply GitOps tras tener el controller; ArgoCD no lo gestiona, así que se vuelve a aplicar con kubectl apply -f cada vez que cambia la lista.

Wave 0 — Fundamentos (storage + LB controller)

Application Producto Para qué sirve
sealed-secrets Sealed Secrets Controller que descifra SealedSecret en el clúster.
openebs OpenEBS Storage local por nodo (LocalPV).
homelab-storage — StorageClasses openebs-hostpath (default) y longhorn-mixto.
metallb MetalLB Controller LoadBalancer en LAN. No es kube-vip.
gateway-api Gateway API CRDs Gateway, HTTPRoute, etc. (canal standard).
cert-manager cert-manager Emisión de certificados TLS.

Wave 1 — Red de servicios + storage HA

Application Producto Para qué sirve
metallb-config MetalLB Pool L2 192.168.23.200–192.168.23.220 (reservado fuera del DHCP del router).
cert-manager-config cert-manager CA propia del HomeLab (ClusterIssuer homelab-ca).
kong (o traefik, nginx-gateway) Kong Ingress Controller Controlador de Gateway API y Gateway homelab (HTTP/HTTPS, *.homelab.local). Se activa solo uno; ver Cambiar el controlador de Gateway.
longhorn Longhorn Storage replicado cross-arch.

Wave 2 — ArgoCD accesible + Dex

Application / carpeta Producto Para qué sirve
argocd-route Gateway API HTTPRoute: UI en https://argocd.homelab.local.
argocd/config/ (argocd) Dex Connector GitHub + staticClients vCluster e Incus UI.
argocd/secrets/ 1Password SDK OAuth desde app local

Wave 3 — Operaciones

Application Producto Para qué sirve
k3s-upgrade system-upgrade-controller Upgrades K3s escalonados.

Sync manual (tú decides cuándo)

Application Producto Para qué sirve
vcluster-platform vCluster Platform UI: kubeconfig del host K3s (connected) + vclusters.
capn-demo CAPN Cluster API sobre Incus.
calico-operator + calico-config Calico CNI Calico (operator + Installation CR). Aplicar ambas en orden.
canal Canal CNI Canal (Flannel + políticas Calico).
cilium Cilium CNI Cilium vía Helm.

CNI: Fase 3, no Fase 4

El CNI (Container Network Interface) se elige en Fase 3 — K3s (k3s_install.core.cni). Por defecto Flannel embebido (Ansible, sin Application). Las apps anteriores son alternativa GitOps si K3s (distribución ligera de Kubernetes) ya tiene --flannel-backend=none. Ver playbook-options — CNI.

Manifiestos de soporte (no son Applications)

Ruta Para qué sirve
storage/ StorageClasses vía homelab-storage.
metallb/ Pool + L2Advertisement.
k3s-upgrade/ CRs Plan SUC.
vcluster/values/platform.yaml Helm values Platform + OIDC Dex.
capn/clusters/ Clusters generados con clusterctl.
cni/calico/ Installation CR Calico (calico-config Application).

kube-vip (Ansible) vs MetalLB (GitOps)

kube-vip MetalLB
Quién lo instala Ansible (k3s_kube_vip) ArgoCD
Qué VIPea Solo API server :6443 Services LoadBalancer
Config clave svc_enable=false Pool 192.168.23.200–.220

Resolución de problemas rápida

Síntoma Revisar
Application Degraded kubectl describe application -n argocd <nombre>
arc-runners OutOfSync y el pod del listener se reinicia cada pocos minutos ArgoCD poda en bucle los recursos que crea el controlador de ARC (AutoscalingListener, Role, RoleBinding: copian la etiqueta app.kubernetes.io/instance). Se corrige con application.resourceTrackingMethod: annotation en argocd-cm (ya está en gitops/argocd/config). Comprueba: kubectl -n argocd get cm argocd-cm -o jsonpath='{.data.application\.resourceTrackingMethod}' → annotation; si no, sincroniza argocd y reinicia el controlador: kubectl -n argocd rollout restart statefulset argocd-application-controller
Gateway sin dirección metallb-config sync, pool libre en LAN
SSO vCluster falla playbook-dex-oauth-secrets.yml --tags ensure,argocd,vcluster; restart Dex
Incus UI SSO falla INCUS_CLIENT_SECRET en argocd-secret; incus config set oidc.*; restart Dex
Dex login sin GitHub Secretos GitHub en argocd-secret; Redirect URIs de la OAuth App correcto
GitHub login rechazado Usuario debe pertenecer al team devops de la org symintel
Longhorn pod pending Etiquetas node.longhorn.io/create-default-disk (playbook labels)
Pods CNI no Ready K3s con --flannel-backend=none antes de sync; solo una app CNI activa (CNI)

Manifiestos fuente: gitops/argocd/apps/.

Guía ejecutable: Fase 4 — GitOps.