~ / posts / oci-kubernetes / bootstrap-de-argocd.md
2026-11-22 · 13 min de lectura

P7 - ArgoCD en OKE: una sola instalación a mano, y el resto del cluster sale de git

Cómo arranco un cluster vacío: ArgoCD con Helm y austero, un app-of-apps que toma el repo de GitOps, AppProjects que acotan cada producto y ApplicationSets que generan una Application por carpeta. Y lo que no hacen las sync waves si no se lo pedís.

tiendisocikubernetesawsgitopsargocd

Serie «Kubernetes en OCI al menor costo» — parte 7. En la parte 6 vimos cómo llegan los secretos del Vault a los pods. Acá va cómo llega todo lo demás: desde un cluster vacío hasta 52 Applications sincronizadas desde git.

Soy Matías Galiano, arquitecto de plataforma: llevo 18 años escribiendo software y 7 diseñando y operando sistemas distribuidos sobre Kubernetes, con Terraform y GitOps.

Cuando Terraform termina, el cluster de la parte 4 está vacío: nodos, red y permisos, pero ni un operador ni una aplicación. Todo lo que corre arriba lo instala ArgoCD, una herramienta de GitOps: en vez de aplicar cambios con kubectl o helm desde mi máquina, los escribo en un repo, y ArgoCD compara todo el tiempo lo que dice el repo con lo que hay en el cluster y corrige la diferencia.

La idea es que la instalación a mano sea una sola, ArgoCD, y que a partir de ahí el cluster se arme solo. Todo sale del repo de GitOps del cluster de producción de Tiendis.

El repo: tres carpetas#

base/      # ArgoCD sobre sí mismo: el bootstrap, los AppProjects y los ApplicationSets,
           # y una Application por cada pieza de plataforma
runtime/   # los values y manifiestos de la plataforma: External Secrets, cert-manager,
           # external-dns, APISIX, Postgres, NATS, observabilidad, runners de CI
apps/      # los workloads: apps/<producto>/<entorno>/<app>/

La división tiene una razón: base/ y runtime/ cambian poco y los toco yo; apps/ cambia varias veces por día, y casi siempre lo cambia el CI cuando sube una imagen nueva. Tenerlos separados hace que un error en una app no pueda romper la plataforma.

Instalar ArgoCD#

ArgoCD se instala con su chart de Helm, con valores pensados para un cluster chico:

global:
  nodeSelector:
    kubernetes.io/arch: arm64     # todo el cluster es ARM

configs:
  params:
    server.insecure: true         # el TLS lo termina el gateway, no ArgoCD

server:
  service:
    type: ClusterIP               # sin load balancer propio: entra por el gateway

redis-ha:
  enabled: false                  # sin alta disponibilidad: una réplica de cada cosa
controller:
  replicas: 1
repoServer:
  replicas: 1
kubectl create namespace argocd
helm install argocd argo/argo-cd -n argocd -f argocd-values.yaml

La interfaz de ArgoCD sale a internet por el mismo gateway que las apps, APISIX, pero con una limitación: solo responde a la IP de mi casa. Desde esa pantalla se puede cambiar o borrar cualquier cosa del cluster, así que no tiene sentido que esté abierta al mundo aunque tenga login. La regla va en la ruta, con el plugin ip-restriction de APISIX:

apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  name: argocd-ip-allowlist
  namespace: argocd
spec:
  plugins:
    - name: ip-restriction
      config:
        whitelist: ["<mi IP>/32"]
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: argocd-server
  namespace: argocd
spec:
  hostnames: ["argocloud.mgaliano.tech"]
  rules:
    - filters:
        - type: ExtensionRef
          extensionRef: { group: apisix.apache.org, kind: PluginConfig, name: argocd-ip-allowlist }
      backendRefs:
        - { name: argocd-server, port: 80 }

Desde cualquier otra IP, la respuesta es un 403. Funciona porque el load balancer de entrada deja pasar la IP real del cliente hasta APISIX; si la reemplazara por la suya, todos los pedidos parecerían venir del mismo lugar y la regla no serviría. El costo es que, cuando mi proveedor de internet me cambia la IP, tengo que actualizar la lista antes de poder entrar. Nada se rompe mientras tanto: ArgoCD sigue sincronizando, solo que no veo la interfaz.

Sin HA, ArgoCD entero usa alrededor de 1 GB de memoria, casi todo del controlador que compara git con el cluster. Si se cae un rato, lo único que pasa es que los cambios en git tardan en aplicarse: lo que ya corre en el cluster sigue corriendo. Lo que sí pierdo es la forma normal de desplegar: mientras ArgoCD no vuelve, un arreglo urgente no llega a producción por git. Es un riesgo que estoy dispuesto a asumir en un cluster de este tamaño, a cambio de no pagar en memoria las réplicas de más que pide la alta disponibilidad.

ArgoCD se puede gestionar a sí mismo. Alcanza con una Application más en el repo que apunte al mismo chart, con los mismos values, en el mismo namespace y con el mismo nombre de release:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: argocd
  namespace: argocd
spec:
  project: default
  sources:
    - repoURL: https://argoproj.github.io/argo-helm
      chart: argo-cd
      targetRevision: <versión del chart>
      helm:
        releaseName: argocd
        valueFiles: [$values/base/bootstrap/argocd-values.yaml]
    - repoURL: https://github.com/mgaliano-lab/argocd-cloud.git
      targetRevision: main
      ref: values
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated: { prune: false, selfHeal: true }

ArgoCD adopta los recursos que instaló Helm, y a partir de ahí actualizarlo es cambiar la versión en git, como cualquier otra pieza.

Yo elijo no hacerlo: prefiero tenerlo controlado y manejarlo por mi cuenta. Lo actualizo con helm upgrade a mano, porque si una versión nueva viene rota y es ArgoCD el que se actualiza, me quedo sin la herramienta con la que lo arreglaría. Es una actualización cada un par de meses, la hago mirando, y si algo sale mal vuelvo a la versión anterior con helm rollback, sin depender de que ArgoCD funcione.

La credencial del repo: el huevo y la gallina#

El repo de GitOps es privado, así que ArgoCD necesita una credencial para leerlo. Uso una GitHub App con permiso de solo lectura, y su llave privada vive en el Vault, como todos los secretos de la parte 6. Pero el que lee el Vault es External Secrets, y a External Secrets lo instala ArgoCD. ArgoCD no puede leer el repo que le dice que instale lo que le daría acceso al repo.

La salida es cargar la credencial a mano una sola vez, la primera, sacando el valor del Vault. Lo hago con un solo pipe, para que la llave privada no pase nunca por el disco ni quede en una variable de la terminal: el Vault la entrega, jq arma el Secret y kubectl lo crea, todo en memoria.

oci secrets secret-bundle get-secret-bundle-by-name --vault-id <ocid> --secret-name github-app \
  --query 'data."secret-bundle-content".content' --raw-output \
| base64 -d \
| jq '{apiVersion: "v1", kind: "Secret",
       metadata: {name: "github-app-bootstrap", namespace: "argocd",
                  labels: {"argocd.argoproj.io/secret-type": "repo-creds"}},
       stringData: {type: "git", url: "https://github.com/mgaliano-lab",
                    githubAppID: (.appID | tostring),
                    githubAppInstallationID: (.installationID | tostring),
                    githubAppPrivateKey: .privateKey}}' \
| kubectl create -f -

Va kubectl create y no kubectl apply a propósito: apply guarda una copia del manifiesto en una anotación del propio objeto, y esa copia incluiría la llave en texto plano.

Es un repo-creds: una credencial que ArgoCD usa para cualquier repo cuya URL empiece con ese prefijo, así que sirve para todos los repos de la organización. En el repo hay un ExternalSecret que arma la misma credencial desde el Vault con otro nombre. Cuando External Secrets ya está andando, esa credencial aparece sola, y la de bootstrap se borra:

kubectl -n argocd delete secret github-app-bootstrap

A partir de ahí, si roto la llave de la GitHub App, la cambio en el Vault y ArgoCD la toma en menos de una hora, sin que nadie toque el cluster.

El app-of-apps#

Lo segundo y último que aplico a mano es una Application, root, que apunta a la carpeta base/ del repo. Una Application es el objeto de ArgoCD que dice «esta carpeta del repo va en este lugar del cluster». Y root tiene adentro más Applications: es el patrón app-of-apps.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: root
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/mgaliano-lab/argocd-cloud.git
    targetRevision: main
    path: base
    directory:
      recurse: true
      exclude: "bootstrap/*"      # este archivo y los values de ArgoCD: no se aplican solos
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated: { prune: true, selfHeal: true }
    syncOptions:
      - SkipDryRunOnMissingResource=true
    retry:
      limit: 10
      backoff: { duration: 20s, maxDuration: 5m, factor: 2 }

Tres opciones hacen todo el trabajo:

Con eso, el bootstrap completo de un cluster vacío son tres comandos y un borrado.

AppProjects: cada producto en su carril#

Un AppProject limita qué puede hacer una Application: de qué repos puede leer, en qué namespaces puede escribir y qué recursos de todo el cluster puede crear. Tengo uno para la plataforma y uno por producto:

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: tiendis
  namespace: argocd
spec:
  sourceRepos:
    - https://github.com/mgaliano-lab/argocd-cloud.git
  destinations:
    - { server: https://kubernetes.default.svc, namespace: dev-tiendis }
    - { server: https://kubernetes.default.svc, namespace: prd-tiendis }
    # ...los namespaces del front
  clusterResourceWhitelist:
    - { group: "", kind: Namespace }   # lo único fuera de su namespace: crearlo
  namespaceResourceWhitelist:
    - { group: "*", kind: "*" }

El de la plataforma, runtime, es amplio a propósito: instala operadores que crean CRDs y recursos de todo el cluster, desde charts de muchos repos distintos. Los de producto, en cambio, solo pueden tocar sus namespaces. Un error en el manifiesto de una app de Emprenum no puede escribir en el namespace de producción de Tiendis, ni crear un ClusterRole, aunque el YAML lo pida: ArgoCD lo rechaza antes de aplicarlo.

ApplicationSets: una Application por carpeta#

Escribir a mano una Application por cada app y entorno no escala. Un ApplicationSet las genera a partir de un patrón. El mío busca un config.json en cada carpeta de app:

{ "name": "tiendis-prd-api", "namespace": "prd-tiendis", "project": "tiendis" }
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: tiendis-apps
  namespace: argocd
spec:
  goTemplate: true
  generators:
    - git:
        repoURL: https://github.com/mgaliano-lab/argocd-cloud.git
        revision: main
        files:
          - path: "apps/tiendis/*/*/config.json"
  template:
    metadata:
      name: "{{.name}}"
    spec:
      project: "{{.project}}"
      source:
        repoURL: https://github.com/mgaliano-lab/argocd-cloud.git
        targetRevision: main
        path: "{{.path.path}}"
      destination:
        server: https://kubernetes.default.svc
        namespace: "{{.namespace}}"
      syncPolicy:
        automated: { prune: true, selfHeal: true }
        syncOptions: [CreateNamespace=true]
        retry:
          limit: 10
          backoff: { duration: 20s, maxDuration: 5m, factor: 2 }

Sumar una app nueva es crear su carpeta con el config.json y los manifiestos. El proyecto sale del archivo, así que una app no puede ponerse en un proyecto más permisivo sin que se vea en el diff.

En las apps que escalan solas, el Deployment no lleva replicas. Las maneja el HPA (HorizontalPodAutoscaler): mira la CPU y la memoria de los pods y cambia replicas en el Deployment entre un mínimo y un máximo. Si git también dijera un número, ArgoCD lo vería como una diferencia y lo volvería a poner, y el HPA lo cambiaría otra vez. Sin el campo en git, el HPA es su único dueño. Las apps sin HPA sí lo llevan, porque ahí el número fijo es la decisión.

El retry va también en el template: ArgoCD, con sync automático, no reintenta un sync que falló para el mismo commit. Si una app se sincroniza antes de que exista su Secret, sin retry queda en error hasta el próximo commit.

Las sync waves no esperan entre Applications#

Para ordenar el arranque uso sync waves: una anotación con un número, y ArgoCD aplica primero los recursos de número más bajo. Las de la plataforma van así:

Wave Qué
-3 External Secrets (el chart, con sus CRDs)
-2 El ClusterSecretStore, cert-manager, metrics-server, los CRDs de Gateway API
-1 Los secretos de infraestructura, la config de cert-manager, external-dns, el autoscaler
0 El gateway, Postgres, NATS, la observabilidad
1+ Lo que depende de todo lo anterior

Lo que me costó entender es que esto no alcanza solo. ArgoCD, antes de pasar a la wave siguiente, espera a que los recursos de la actual estén sanos. Pero desde la versión 1.8 no sabe evaluar la salud de una Application: la da por sana apenas la crea. En un app-of-apps, entonces, las waves solo ordenan la creación de las Applications, y External Secrets puede estar todavía instalándose cuando cert-manager ya está pidiendo sus credenciales.

La documentación de ArgoCD lo dice, y la solución es devolverle ese chequeo con una regla en los values del chart:

configs:
  cm:
    resource.customizations.health.argoproj.io_Application: |
      hs = {}
      hs.status = "Progressing"
      hs.message = ""
      if obj.status ~= nil and obj.status.health ~= nil then
        hs.status = obj.status.health.status
        if obj.status.health.message ~= nil then
          hs.message = obj.status.health.message
        end
      end
      return hs

Con eso, una Application está sana recién cuando lo está todo lo que tiene adentro, y root no pasa a la wave -2 hasta que External Secrets responde. El arranque de un cluster vacío deja de depender de cuántos reintentos hagan falta.

Las waves solo ordenan lo que sincroniza una misma Application. Las apps que genera un ApplicationSet las crea el controlador del ApplicationSet, no root, así que una anotación de wave en su template no ordena nada. Para ellas, lo que funciona es el retry.

El día a día#

Con todo esto andando, casi no toco el cluster. Un deploy es un commit: el CI sube la imagen nueva al registry y cambia el tag en apps/<producto>/<entorno>/<app>/kustomization.yaml, ArgoCD ve el commit y actualiza el Deployment. Un rollback es revertir ese commit. Y la historia de git es, también, la historia de todo lo que cambió en el cluster.

Hoy son 52 Applications, todas Synced y Healthy, y la interfaz de ArgoCD es lo primero que miro cuando algo anda raro.

Referencias#

Lo mismo en AWS#

AWS OCI
ArgoCD Instalado con Helm, o administrado como EKS Capability Instalado con Helm
Costo de ArgoCD Cero instalado; administrado, por hora y por Application Cero: corre en los nodos
Credencial del repo La misma GitHub App La misma GitHub App
Secretos del bootstrap Secrets Manager con IRSA OCI Vault con instance principal

ArgoCD es de las pocas piezas de la serie que son iguales en las dos nubes: no sabe en qué nube corre. AWS ofrece además una versión administrada, que se cobra por hora y por cada Application que maneja. Con 52 Applications y un cluster chico, prefiero el giga de memoria que ocupa en mis nodos.

Lo que viene#

En la parte 8 van los operadores base: cert-manager y external-dns, que emiten los certificados y publican el DNS en Route 53 desde un cluster que está en otra nube, y el almacenamiento de los volúmenes.

Si te sirvió, el RSS es la mejor forma de enterarte del próximo post.