Cómo instalar Argo CD en Kubernetes para despliegues GitOps

Argo CD es una herramienta de entrega continua para Kubernetes basada en GitOps: el estado deseado de tus aplicaciones vive en un repositorio Git y Argo CD se encarga de que el clúster coincida con él, aplicando los cambios y avisando cuando algo se desvía. En este tutorial instalarás Argo CD en un clúster de Kubernetes, accederás a su interfaz web y a su CLI desde una máquina Linux, y desplegarás una aplicación de ejemplo primero de forma manual y después de forma declarativa con sincronización automática.

Requisitos previos

Para seguir esta guía necesitas:

Un clúster de Kubernetes en una versión mantenida, con al menos 2 vCPU y 4 GB de RAM libres para los componentes de Argo CD. Puede ser un clúster gestionado o uno propio, por ejemplo k3s en un VPS de CubePath.
kubectl instalado en tu máquina (Ubuntu 24.04 en los ejemplos) y configurado con un kubeconfig con permisos de administrador del clúster.
Acceso a GitHub para clonar el repositorio público de ejemplos de Argo CD.

Comprueba que kubectl llega al clúster y que los nodos están listos:

kubectl get nodes

NAME      STATUS   ROLES                  AGE   VERSION
node-1    Ready    control-plane,master   12d   v1.33.4+k3s1

Paso 1: Instalar Argo CD en el clúster

Argo CD se instala en su propio espacio de nombres. Créalo:

kubectl create namespace argocd

Aplica el manifiesto oficial de la versión estable. Incluye las definiciones de recursos (CRD), las cuentas de servicio, los permisos RBAC y todos los componentes:

kubectl apply -n argocd --server-side --force-conflicts \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

La opción --server-side evita el error metadata.annotations: Too long que produce el kubectl apply clásico con las CRD de Argo CD, que son muy grandes.

Espera a que todos los pods estén listos:

kubectl wait --for=condition=Ready pods --all -n argocd --timeout=300s
kubectl get pods -n argocd

NAME                                                READY   STATUS    RESTARTS   AGE
argocd-application-controller-0                     1/1     Running   0          2m
argocd-applicationset-controller-6d7f9c8b4d-7xk2p   1/1     Running   0          2m
argocd-dex-server-5c9b8d7f6c-q2lwn                  1/1     Running   0          2m
argocd-notifications-controller-7b8c6d5f4-hm9zt     1/1     Running   0          2m
argocd-redis-6f8b7c5d9d-rk4vx                       1/1     Running   0          2m
argocd-repo-server-7d9f8b6c5-nq8wd                  1/1     Running   0          2m
argocd-server-5b7c9d8f6-lt2mz                       1/1     Running   0          2m

Cada componente tiene una función concreta:

Componente	Función
`argocd-server`	API, interfaz web y punto de conexión de la CLI
`argocd-repo-server`	Clona los repositorios y genera los manifiestos (YAML, Helm, Kustomize)
`argocd-application-controller`	Compara el estado del clúster con Git y aplica los cambios
`argocd-applicationset-controller`	Genera aplicaciones a partir de plantillas
`argocd-dex-server`	Inicio de sesión único (SSO) con proveedores externos
`argocd-redis`	Caché interna

Paso 2: Instalar la CLI de Argo CD

La CLI argocd permite iniciar sesión, crear aplicaciones y sincronizarlas desde la terminal. Descarga el binario de la última versión desde GitHub:

curl -fsSL -o argocd-linux-amd64 https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
sudo install -m 555 argocd-linux-amd64 /usr/local/bin/argocd
rm argocd-linux-amd64

En un equipo ARM usa argocd-linux-arm64. Comprueba la instalación:

argocd version --client

La salida muestra la versión del cliente, con el formato argocd: v3.x.y+<commit>.

Paso 3: Acceder a la interfaz y a la API

El servicio argocd-server se crea como ClusterIP, así que no es accesible desde fuera del clúster. Para empezar, reenvía un puerto local con kubectl. Ejecuta este comando en una terminal aparte y déjalo abierto:

kubectl port-forward svc/argocd-server -n argocd 8080:443

Forwarding from 127.0.0.1:8080 -> 8080
Forwarding from [::1]:8080 -> 8080

Durante la instalación, Argo CD genera una contraseña aleatoria para el usuario admin y la guarda en un secreto. Léela con la CLI:

argocd admin initial-password -n argocd

Inicia sesión en la API a través del reenvío de puertos. La opción --insecure es necesaria porque Argo CD usa de momento un certificado autofirmado:

argocd login localhost:8080 --username admin --insecure

Password:
'admin:login' logged in successfully
Context 'localhost:8080' updated

Cambia la contraseña inicial por una propia y, cuando lo hayas hecho, borra el secreto que la contenía:

argocd account update-password
kubectl delete secret argocd-initial-admin-secret -n argocd

También puedes abrir https://localhost:8080 en el navegador de la misma máquina, aceptar el aviso del certificado e iniciar sesión como admin con la nueva contraseña.

Nota

para uso permanente, publica argocd-server con un Ingress y un certificado válido en lugar del reenvío de puertos. La configuración depende del controlador de Ingress de tu clúster (Traefik, NGINX, etc.); consulta la sección "Ingress Configuration" de la documentación oficial de Argo CD para el tuyo.

Paso 4: Desplegar una aplicación desde Git con la CLI

Una Application de Argo CD une un origen (repositorio, rama y ruta) con un destino (clúster y espacio de nombres). Usarás la aplicación guestbook del repositorio público de ejemplos de Argo CD:

argocd app create guestbook \
  --repo https://github.com/argoproj/argocd-example-apps.git \
  --path guestbook \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default

https://kubernetes.default.svc es el propio clúster en el que está instalado Argo CD. Consulta el estado de la aplicación:

argocd app get guestbook

Name:               argocd/guestbook
Project:            default
Server:             https://kubernetes.default.svc
Namespace:          default
Repo:               https://github.com/argoproj/argocd-example-apps.git
Target:
Path:               guestbook
Sync Policy:        Manual
Sync Status:        OutOfSync from  (...)
Health Status:      Missing

OutOfSync significa que lo que hay en Git todavía no está en el clúster. Sincroniza la aplicación para aplicarlo:

argocd app sync guestbook

Al terminar, el estado debe ser Synced y Healthy:

argocd app get guestbook

...
Sync Status:        Synced to  (...)
Health Status:      Healthy

Comprueba los recursos creados en el clúster:

kubectl get deploy,svc guestbook-ui -n default

NAME                           READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/guestbook-ui   1/1     1            1           40s

NAME                   TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)   AGE
service/guestbook-ui   ClusterIP   10.43.51.200   <none>        80/TCP    40s

Elimina esta aplicación de prueba, junto con sus recursos, antes de pasar al método declarativo:

argocd app delete guestbook --yes

Paso 5: Definir la aplicación de forma declarativa

En GitOps, la propia definición de la aplicación también debería estar en Git. Argo CD guarda cada aplicación como un recurso Application de Kubernetes, así que puedes escribirla en YAML. Crea el archivo:

nano guestbook-app.yaml

Añade este contenido:

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

Qué cambia respecto al paso anterior:

automated: Argo CD sincroniza solo, sin argocd app sync, cada vez que detecta un cambio en Git.
prune: true: si borras un manifiesto del repositorio, Argo CD borra el recurso del clúster.
selfHeal: true: si alguien modifica un recurso a mano con kubectl, Argo CD lo devuelve al estado de Git.
CreateNamespace=true: crea el espacio de nombres guestbook si no existe.

Aplica el recurso:

kubectl apply -f guestbook-app.yaml

application.argoproj.io/guestbook created

Como la sincronización es automática, en unos segundos la aplicación estará desplegada:

argocd app list

NAME              CLUSTER                         NAMESPACE  PROJECT  STATUS  HEALTH   SYNCPOLICY  ...
argocd/guestbook  https://kubernetes.default.svc  guestbook  default  Synced  Healthy  Auto-Prune  ...

Paso 6: Comprobar la autocorrección

Para ver selfHeal en acción, cambia a mano el número de réplicas del despliegue:

kubectl scale deployment guestbook-ui -n guestbook --replicas=3

Argo CD detecta la diferencia con Git y deshace el cambio. Tras unos segundos, vuelve a consultar el despliegue:

kubectl get deployment guestbook-ui -n guestbook

NAME           READY   UP-TO-DATE   AVAILABLE   AGE
guestbook-ui   1/1     1            1           3m

La forma correcta de escalar es cambiar replicas en el manifiesto del repositorio y hacer push. Argo CD comprueba los repositorios cada tres minutos por defecto; para que reaccione al instante, configura en tu proveedor Git un webhook que apunte a https://your_argocd_domain/api/webhook una vez que Argo CD esté publicado con un Ingress.

Paso 7: Conectar un repositorio privado

El ejemplo usa un repositorio público. Para tus propias aplicaciones, lo habitual es un repositorio privado. Crea en GitHub un token de acceso personal fine-grained con permiso de solo lectura sobre el contenido del repositorio y regístralo en Argo CD:

argocd repo add https://github.com/your_user/your_repo.git \
  --username your_user \
  --password your_github_token

Comprueba que Argo CD puede acceder a él:

argocd repo list

La columna STATUS del repositorio debe mostrar Successful.

A partir de aquí, crea un Application como el del paso 5 con tu repoURL y la ruta de tus manifiestos. Guarda esos archivos Application en otro repositorio Git para que toda la configuración del clúster quede versionada.

Solución de problemas

La aplicación queda en Unknown con repository not found o authentication required: Argo CD no puede leer el repositorio. Revisa argocd repo list y vuelve a añadirlo con credenciales válidas.

ComparisonError o manifiestos que no se generan: revisa los registros del componente que clona y renderiza los repositorios:

kubectl logs -n argocd deploy/argocd-repo-server --tail=50

La aplicación está Synced pero Progressing o Degraded: Argo CD aplicó los manifiestos, pero los pods no arrancan. Revisa los eventos del espacio de nombres de destino con kubectl get events -n guestbook --sort-by=.lastTimestamp.

Cambios en Git que tardan en aplicarse: fuerza una comprobación con argocd app get guestbook --refresh o configura el webhook descrito en el paso 6.

Conclusión

Tienes Argo CD instalado en tu clúster de Kubernetes, con acceso por CLI e interfaz web, y una aplicación que se despliega desde Git con sincronización automática, borrado de recursos huérfanos y autocorrección. Como siguientes pasos puedes publicar Argo CD con un Ingress y HTTPS, crear proyectos (AppProject) para limitar qué repositorios y espacios de nombres usa cada equipo, o gestionar tus aplicaciones con Helm o Kustomize desde el mismo flujo.

En esta página