---
title: "Cómo instalar Argo CD en Kubernetes para despliegues GitOps"
description: "Instala Argo CD en Kubernetes, accede con su CLI y despliega una aplicación desde un repositorio Git con sincronización automática y autocorrección de cambios."
category: "CI/CD DevOps"
language: es
source: https://cubepath.com/es/docs/ci-cd-devops/instalacion-de-argocd-para-implementaciones-gitops
updated: 2026-09-25
---

# 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:

```bash
kubectl get nodes
```

```output
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:

```bash
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:

```bash
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:

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

```output
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:

```bash
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:

```bash
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:

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

```output
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:

```bash
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:

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

```output
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:

```bash
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:

```bash
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:

```bash
argocd app get guestbook
```

```output
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:

```bash
argocd app sync guestbook
```

Al terminar, el estado debe ser `Synced` y `Healthy`:

```bash
argocd app get guestbook
```

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

Comprueba los recursos creados en el clúster:

```bash
kubectl get deploy,svc guestbook-ui -n default
```

```output
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:

```bash
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:

```bash
nano guestbook-app.yaml
```

Añade este contenido:

```yaml
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:

```bash
kubectl apply -f guestbook-app.yaml
```

```output
application.argoproj.io/guestbook created
```

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

```bash
argocd app list
```

```output
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:

```bash
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:

```bash
kubectl get deployment guestbook-ui -n guestbook
```

```output
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:

```bash
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:

```bash
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:

```bash
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.