GitOps en casa: despliega tu homelab con ArgoCD (2026)

Si tienes un clúster Kubernetes y sigues aplicando cambios a mano con kubectl apply, este artículo es para ti. Te voy a contar cómo montar un pipeline GitOps completo con ArgoCD, el estándar de facto para despliegue declarativo en Kubernetes.

¿Qué es GitOps y por qué te interesa?

GitOps es un modelo de operaciones donde tu repositorio de Git es la fuente de verdad única para todo lo que se ejecuta en tu clúster. Cada cambio que haces en el repo se refleja automáticamente en Kubernetes. Esto significa:

✅ Historial completo de cada cambio (como en cualquier repo Git)
✅ Rollback instantáneo: solo hace falta hacer revert de un commit
✅ Auto-reparación: si alguien borra algo del clúster, ArgoCD lo restaura
✅ Auditabilidad: sabes exactamente quién cambió qué y cuándo
✅ Entornos reproducibles: el mismo repo, el mismo cluster

Instalando ArgoCD en K3s

ArgoCD se instala en su propio namespace. Es tan sencillo como:

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

En mi clúster K3s tuve que usar --server-side=true porque ArgoCD tiene CRDs con anotaciones que superan el límite de 262KB de K3s. Es un detalle importante si montas el cluster en Raspberry Pis.

Acceso a la UI de ArgoCD

Por defecto, el servidor de ArgoCD no está expuesto. La forma más rápida de acceder:

# Obtener la contraseña inicial
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

# Port-forward para acceder a la UI
kubectl port-forward -n argocd svc/argocd-server 8080:443

Usuario: admin. La UI es potente: puedes ver el estado de cada aplicación, sincronizar manualmente, ver diferencias entre Git y el clúster, y hacer rollbacks con un click.

Patrón App of Apps

El patrón App of Apps es la forma correcta de organizar un repo GitOps. En lugar de tener una Application de ArgoCD por cada servicio, tienes una Application raíz que despliega todas las demás:

k8s-repo/
├── applications/       # Apps de ArgoCD (1 por servicio)
│   ├── root.yaml       # App raíz que despliega las demás
│   ├── authelia.yaml
│   ├── wordpress.yaml
│   ├── vault.yaml
│   ├── nextcloud.yaml
│   └── ...
├── manifests/          # Manifiestos YAML de cada app
│   ├── authelia/
│   ├── wordpress/
│   ├── vault/
│   └── ...
├── values/             # Valores de Helm (para charts multi-source)
└── namespaces/         # Namespaces declarativos

La App raíz se parece a esto:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: root
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/tu-user/tu-repo.git
    targetRevision: HEAD
    path: applications
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Cada Application hija apunta a su propio directorio de manifests:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: wordpress
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/tu-user/tu-repo.git
    targetRevision: HEAD
    path: manifests/wordpress
  destination:
    server: https://kubernetes.default.svc
    namespace: wordpress
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Helm multi-source en ArgoCD

ArgoCD 2.6+ soporta fuentes múltiples. Esto es perfecto para apps que usan charts de Helm con valores personalizados:

spec:
  sources:
    - repoURL: https://charts.bitnami.com/bitnami
      chart: wordpress
      targetRevision: 18.*
      helm:
        valueFiles:
          - $values/values/wordpress.yaml
    - repoURL: https://github.com/tu-user/tu-repo.git
      ref: values

Auto-reparación: la magia de GitOps

Lo mejor de ArgoCD es el auto-healing. Si alguien entra al clúster y borra un pod o modifica un deployment, ArgoCD lo detecta y lo restaura al estado definido en Git en cuestión de segundos. Esto da una tranquilidad enorme.

Conclusión

GitOps con ArgoCD cambia la forma de gestionar un clúster. Pasas de operar a base de comandos a operar a base de commits. Y en un homelab con recursos limitados como un clúster de Raspberry Pis, tener un sistema que se auto-repare y gestione los despliegues por ti es una bendición.

En mi setup, cada servicio está en su propio directorio de manifests, con su Application de ArgoCD, todo versionado en GitHub. Y lo mejor: puedo hacer cambios desde el móvil con un commit y ArgoCD lo aplica solo. Eso es libertad.