Cómo configurar ArgoCD o FluxCD para GitOps en Kubernetes 2026

agosto 21, 2026 Alfonso Moreno | Sysadmin Senior 82 Visitas 11 min de lectura

Si ya tienes un cluster de Kubernetes corriendo y empezaste a aplicar manifests a mano con kubectl apply -f, este artículo es el siguiente paso natural. GitOps reemplaza ese flujo manual por un loop automatizado: el repositorio Git es la fuente de verdad, y un agente dentro del cluster se encarga de sincronizar lo que está desplegado con lo que está commiteado. ArgoCD y FluxCD son las dos implementaciones maduras de esa idea, ambas graduadas por la CNCF y las dos funcionan en producción. La diferencia está en cómo se instalan, cómo se modelan los despliegues y cuánto control de bajo nivel te dan.

La idea detrás de GitOps es directa: si tu aplicación, tu configuración y tu infraestructura están todas descritas en archivos dentro de un repositorio Git, entonces “desplegar” se reduce a hacer un commit. No hay un script bash que copia YAML, no hay un SSH al cluster para correr comandos. El historial de cambios queda en Git, los rollbacks son git revert, y los nuevos integrantes del equipo pueden entender el estado del cluster leyendo los archivos. Eso baja el costo operativo y elimina el “qué hay desplegado en producción” como pregunta abierta.

TL;DR — Lo que vas a tener al final

Tiempo de setup: Cluster mínimo en 2 horas, producción en 1 día.
Requisitos: CPU con VT-x, 8+ GB RAM, 3+ nodos para HA.
Resultado: Kubernetes con HA, escalado automático, service discovery.
Troubleshooting: kubectl logs, kubectl describe, dashboards Grafana oficiales.

TL;DR comparativo

Aspecto	ArgoCD	FluxCD
Modelo mental	Aplicaciones (App of Apps)	Kustomizations + Sources
UI web	Sí, completa	No oficial, solo CLI y dashboards externos
Instalación	`kubectl apply` o Helm chart	Helm chart oficial `flux2`
Multi-tenant / RBAC	Built-in projects y policies	Configurable via Helm release
Curva de aprendizaje	Más rápida para empezar	Más empinada pero más componible
Mejor para	Equipos que quieren ver el estado en una UI	Equipos que prefieren GitOps puro declarativo
Helm support	Sí (vía Application + values)	Sí (HelmRelease CRD)
Repo driver principal	Git directo o Helm	Source controllers (Git, Helm, Bucket, OCI)

Si quieres ver el estado del cluster en una pantalla bonita, ArgoCD. Si quieres componer el pipeline declarativamente con CRDs y no quieres una UI, FluxCD. Las dos son válidas; lo importante es que tu equipo entienda el modelo antes de instalar.

Requisitos antes de instalar cualquier GitOps tool

Antes de tocar nada, valida que tu cluster cumple los mínimos. Ambos proyectos asumen que tienes kubectl apuntando al cluster correcto y que el ingress está saneado.

# Verificar versión de Kubernetes (>= 1.26 recomendado en 2026)
kubectl version
# Confirmar que tienes acceso admin al namespace donde vas a instalar
kubectl auth can-i create namespace --as=system:serviceaccount:default:default
# Verificar que cert-manager está disponible (ArgoCD lo usa)
kubectl get pods -n cert-manager -l app=cert-manager

Por qué importa: el manifest install.yaml de ArgoCD no incluye Ingress por defecto (solo services ClusterIP, deployments y CRDs), así que después de aplicarlo vas a tener que crear el Ingress a mano o usar el chart Helm argo-cd. Si quieres TLS automático en ese Ingress, ahí sí entra cert-manager: sin él, el Ingress queda con certificado auto-firmado y el navegador te bloquea. FluxCD no requiere cert-manager porque tampoco expone nada por Ingress (todo se reconcilia desde el cluster), pero si quieres webhooks de GitHub o GitLab para disparar reconciliaciones, también lo vas a terminar instalando. Otra dependencia común: un ingress controller funcional. Si usaste kubeadm pelado sin instalar ingress-nginx o Traefik, no vas a tener URL pública ni para ArgoCD ni para cualquier otra cosa que expongas.

Para evitar el ciclo clásico de “instalé y no carga”, verifica primero que puedas exponer un servicio cualquiera por ingress. Un hello-world Deployment + Service + Ingress funcionando te dice que el camino está abierto.

Instalar ArgoCD con el manifest oficial

El chart de ArgoCD mantenido por el proyecto está en argo-cd/stable. En producción real prefiero Helm porque te deja parametrizar el ingress y los recursos, pero para empezar el manifest plano es más rápido de leer.

# Crear namespace dedicado (no instalar en default)
kubectl create namespace argocd
# Aplicar el manifest consolidado de la versión estable
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
# Esperar a que los pods estén Ready
kubectl get pods -n argocd -w

El comando kubectl apply -f tira todos los CRDs, deployments y services de ArgoCD de una sola vez. Por qué importa: ArgoCD introduce Custom Resources (Application, AppProject, ApplicationSet) que el resto del cluster va a usar para definir despliegues. Si los CRDs no están aplicados, el resto del flujo falla con errores tipo “no matches for kind Application”. Después de kubectl apply, espera hasta que los pods del namespace argocd estén Running antes de seguir.

Troubleshooting típico: si los pods quedan en CrashLoopBackOff, lo más probable es que falten recursos. ArgoCD pide al menos 2GB de RAM en el nodo donde corre. Para un cluster de pruebas con 4GB totales puedes bajar los límites con kubectl edit deployment argocd-server -n argocd y poner resources.requests.memory: 256Mi, limits.memory: 512Mi.

Exponer la UI de ArgoCD y obtener la contraseña inicial

Por defecto ArgoCD solo escucha en localhost. Para acceder desde otra máquina hay que hacer port-forward o configurar un ingress. Port-forward es lo más rápido para probar; ingress es lo que vas a querer en producción.

# Opción rápida: port-forward (para pruebas locales)
kubectl port-forward svc/argocd-server -n argocd 8080:443
# La contraseña inicial del usuario 'admin' está en el secret argocd-initial-admin-secret
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d && echo

Por qué importa: el port-forward te deja entrar a https://localhost:8080 desde tu máquina aunque el cluster esté en otro lado. La contraseña inicial es autogenerada y está hasheada en el secret; después del primer login ArgoCD te pide cambiarla. Si vas a usar ingress, lo mínimo que necesitas es un Ingress con TLS apuntando al service argocd-server en el puerto 443.

Troubleshooting típico: si el port-forward cierra inmediatamente, normalmente es porque el service argocd-server no tiene endpoint. Corre kubectl get endpoints argocd-server -n argocd y verifica que tenga al menos una IP. Si está vacío, los pods no están healthy todavía.

Crear tu primera Application en ArgoCD

Una Application en ArgoCD conecta un repo Git con un namespace del cluster. Es el recurso que el controller reconcilia constantemente para mantener el cluster sincronizado con Git.

# Crear la primera Application vía CLI (más rápido que la UI la primera vez)
argocd app create guestbook 
  --repo https://github.com/argoproj/argocd-example-apps.git 
  --path guestbook 
  --dest-server https://kubernetes.default.svc 
  --dest-namespace default
# Forzar sincronización inicial
argocd app sync guestbook
# Ver el estado
argocd app get guestbook

El parámetro --repo apunta al repo donde vive el YAML que quieres desplegar. --path es la carpeta dentro de ese repo que contiene los manifests. --dest-server https://kubernetes.default.svc es el cluster actual (cuando ArgoCD corre dentro del mismo cluster). --dest-namespace default es a dónde se van a aplicar los recursos.

Por qué importa: el comando argocd app create registra la app en el CRD de ArgoCD; el controller interno la toma, lee el repo, aplica los manifests al cluster y reporta el estado. Después de argocd app get guestbook deberías ver Status: Synced y Health: Healthy si todo salió bien.

Troubleshooting típico: si el status queda en OutOfSync o Degraded, abre la UI web (vía port-forward) y mira la pestaña “Diff”. Ahí vas a ver exactamente qué campos del cluster no coinciden con Git. Casi siempre es un namespace faltante, una imagen tag distinta o un ConfigMap que alguien modificó a mano.

Instalar FluxCD con el CLI oficial

FluxCD tiene una filosofía más declarativa: todo se modela como CRDs dentro del cluster, y el CLI flux solo sirve para bootstrappear y debuggear. La instalación se hace con flux bootstrap, que crea un repo Git (si no existe) o usa uno existente.

# Instalar el CLI flux (Linux amd64)
curl -s https://fluxcd.io/install.sh | sudo bash
# Verificar versión
flux --version
# Pre-flight check: confirma que el cluster tiene lo necesario
flux check --pre

Por qué importa: el flux check --pre revisa version de Kubernetes, RBAC, capacidad de StorageClass, y si el repo donde vas a pushear está accesible. Si algo falla, te dice qué antes de que intentes el bootstrap. Saltarse este paso es la causa número uno de instalaciones a medias.

Troubleshooting típico: si curl ... install.sh falla con error de certificado, descargá el binario directo desde el release de GitHub. FluxCD no distribuye por snap, brew o apt — solo script y binarios.

Bootstrappear FluxCD contra un repo Git

El bootstrap es el equivalente FluxCD del “kubectl apply” de ArgoCD. Crea los CRDs, instala los controllers, y configura un GitRepository + Kustomization que se sincroniza solo.

# Bootstrap contra un repo existente en GitHub
flux bootstrap github 
  --owner=TU_USUARIO 
  --repository=flux-repo 
  --branch=main 
  --path=clusters/production 
  --personal

--owner es tu usuario de GitHub. --repository es el repo donde FluxCD va a leer y escribir. --path es la carpeta donde vivirá el Kustomization principal. --personal le dice al CLI que use tu token personal en lugar de una GitHub App; para producción real vas a querer GitHub App con permisos scoped.

Por qué importa: el bootstrap deja FluxCD listo para reconciliar la carpeta clusters/production cada vez que hagas git push. Cualquier Kustomization o HelmRelease que pongas ahí adentro se va a aplicar automáticamente. El controller corre dentro del cluster como source-controller, kustomize-controller, helm-controller, notification-controller.

Troubleshooting típico: si el bootstrap se queda colgado en “waiting for GitRepository”, casi siempre es porque el token de GitHub no tiene permisos de escritura sobre el repo. Para --personal necesitas un PAT con scope repo. Para GitHub App necesitas contents:write y metadata:read.

Crear tu primer GitRepository + Kustomization en FluxCD

Una vez bootstrappeado, FluxCD espera que declares explícitamente qué repositorios quieres sincronizar y qué manifests aplicar.

# clusters/production/apps.yaml
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: podinfo
  namespace: flux-system
spec:
  interval: 10m0s
  url: https://github.com/stefanprodan/podinfo
  ref:
    branch: master
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: podinfo
  namespace: flux-system
spec:
  interval: 10m0s
  sourceRef:
    kind: GitRepository
    name: podinfo
  path: "./kustomize"
  prune: true
  wait: true
  timeout: 5m0s

GitRepository le dice al source-controller cada cuánto (10 minutos) tiene que ir a buscar el repo. Kustomization referencia esa fuente, le dice qué carpeta aplicar (./kustomize), y configura el comportamiento: prune: true borra recursos que ya no están en Git, wait: true espera a que los Deployments estén Ready antes de marcar la reconciliación como exitosa.

Por qué importa: este es el “loop” de GitOps en acción. Cada 10 minutos FluxCD revisa si el repo cambió; si cambió, descarga la nueva versión y aplica el diff al cluster. Si la reconciliación falla, FluxCD mantiene la versión anterior (no rompe el cluster) y reporta el error.

Troubleshooting típico: si flux get kustomizations muestra Ready: False, corre flux logs --follow --kind=Kustomization --name=podinfo para ver el error exacto. Casi siempre es un YAML mal formado o un namespace que no existe.

ArgoCD vs FluxCD: cuándo elegir cada uno

Después de haber instalado ambos en clusters de prueba, la decisión real no es técnica sino organizacional. ArgoCD tiene una UI que los managers y los nuevos integrantes pueden mirar sin aprender kubectl. FluxCD obliga a que todos lean manifests, pero a cambio te da un control declarativo más limpio cuando tienes decenas de clusters y equipos distintos desplegando cosas.

Si tu equipo es chico (3-5 personas) y nadie quiere aprender una herramienta más, ArgoCD. Si tu equipo es grande, tienes multi-tenancy real, y necesitas compliance auditable (tipo SOC 2), FluxCD. Y si tu decisión es puramente “cuál se ve más bonito en LinkedIn”, andá por ArgoCD: la UI la entiende cualquiera.

La buena noticia es que ninguno te deja encerrado. Si empezás con uno y te arrepentís, migrar a la otra herramienta lleva un fin de semana porque ambos leen manifests de Kubernetes. Los CRDs son distintos, pero el modelo mental (repo Git = fuente de verdad) es el mismo.

Preguntas frecuentes

¿Por qué Cómo configurar ArgoCD o FluxCD para GitOps en Kubernetes 2026 es relevante para sysadmins Linux?

Forma parte del flujo diario de administración. Los conceptos explicados se aplican directamente a servidores en producción y resuelven problemas reales que enfrentan sysadmins hispanohablantes.

¿Qué necesito para empezar con Cómo configurar ArgoCD o FluxCD?

Distribución Linux actualizada (Debian, Ubuntu, RHEL, Fedora o Arch), acceso root, y conexión a internet. Para producción: entorno de staging separado antes de aplicar cambios.

¿Cuáles son los errores más comunes con Cómo configurar ArgoCD o FluxCD?

Los tres más frecuentes: (1) saltar la lectura de logs, (2) aplicar cambios directos en producción sin probar, (3) olvidar permisos y ownership. La documentación y un plan de rollback siempre.

¿Cuándo usar Cómo configurar ArgoCD o FluxCD y cuándo una alternativa?

Esta solución es ideal para el caso descrito. Alternativas como Docker, Ansible o configuración manual pueden ser mejores según contexto: portabilidad, escala y reproducibilidad son los factores clave.

¿Cómo migro desde una configuración previa a Cómo configurar ArgoCD o FluxCD?

Documentar el estado actual, probar la nueva configuración en staging, validar funcionalmente, y aplicar en producción con rollback plan listo. Los posts de SoyLinux incluyen troubleshooting para los problemas más comunes.