|

GitOps con GitLab: agente, Flux y CI sin kubeconfig

En pocas palabras: El GitOps de producción con GitLab se hace con agentk, el agente que corre dentro del clúster y se conecta hacia afuera con KAS, sin puertos entrantes ni kubeconfig guardado en el CI. GitLab recomienda sumar Flux para sincronizar, y con ci_access podés autorizar hasta 500 proyectos.

GitOps con GitLab se apoya en el agente para Kubernetes (agentk), que corre dentro del clúster y se conecta hacia afuera con KAS, sin puertos entrantes ni kubeconfig en el CI. Según la documentación de GitLab consultada el 2026-10-16, para sincronizar se recomienda Flux junto con agentk.

El agente de GitLab para Kubernetes es un componente que se instala en cada clúster (agentk) y mantiene un canal seguro con el servidor KAS de GitLab. Según la documentación oficial, sirve para comunicarse con clústeres detrás de firewall o NAT, acceder a la API en tiempo real y mostrar el estado del clúster en la interfaz de GitLab. GitOps es la práctica de usar Git como fuente única de verdad del sistema.

En este artículo:

En 30 segundos

  • El modelo push guarda un kubeconfig o token en el CI y expone la API del clúster (puerto 6443 en el ejemplo de la guía); el modelo pull con agentk solo necesita conexión saliente hacia KAS.
  • La documentación de GitLab consultada el 2026-10-16 recomienda Flux junto con agentk para el GitOps pull.
  • Con ci_access podés autorizar hasta 500 proyectos o 500 grupos a usar el agente, y el contexto de kubectl tiene el formato ruta/proyecto-del-agente:nombre-del-agente.
  • La guía de dev.to usa la imagen v17.5.0 y bitnami/kubectl:latest: son valores de ejemplo que conviene verificar y fijar antes de copiarlos.

¿Por qué desplegar con kubeconfig desde el CI es un riesgo?

Porque el modelo push deja credenciales de larga duración en el CI y obliga a exponer la API del clúster. Según la guía publicada en dev.to el 16 de octubre de 2026, el flujo clásico crea un kubeconfig o token de ServiceAccount, lo pega en la configuración del repositorio y deja que el runner llegue por el puerto 6443 a correr kubectl apply.

De ahí salen tres problemas. La API queda alcanzable desde internet o desde runners públicos. Las credenciales de cluster-admin viven en variables de CI (un blanco jugoso si se compromete una dependencia). Y el drift aparece cuando alguien hace kubectl edit a mano y el clúster se aleja de Git sin avisar.

La documentación de GitLab es más tajante sobre el flujo CI/CD. Dice (traducción nuestra): “Este flujo tiene un modelo de seguridad más débil. No deberías usar un flujo CI/CD para despliegues en producción”. Lo dice la página principal del agente, y vale también para el esquema con ci_access que vemos más abajo.

¿Cómo se conecta el agente de GitLab al clúster sin abrir puertos?

agentk corre como pod dentro del clúster y abre un canal bidireccional saliente hacia KAS, el componente de GitLab que maneja la integración. Como la conexión nace desde adentro, no hay que abrir puertos entrantes en el firewall. La guía de dev.to lo describe como gRPC o WebSocket seguro (wss).

El flujo que muestra la guía tiene tres pasos:

  1. Crear el archivo de configuración. Va en .gitlab/agents/<nombre-del-agente>/config.yaml dentro del repositorio.
  2. Registrar el agente en la interfaz. En el proyecto, Operar > Clústeres de Kubernetes > Conectar un clúster (agente). GitLab muestra un token de registro y un comando de Helm.
  3. Instalar con Helm. Se usa el chart gitlab/gitlab-agent con el token y el valor config.kasAddress.
helm repo add gitlab https://charts.gitlab.io
helm repo update
helm upgrade --install production-agent gitlab/gitlab-agent \
 --namespace gitlab-agent-production --create-namespace \
 --set image.tag="v17.5.0" \
 --set config.token="YOUR_AGENT_REGISTRATION_TOKEN" \
 --set config.kasAddress="wss://kas.gitlab.com"

Ojo con los valores. El kas.gitlab.com sirve para GitLab.com; en una instalación self-managed la dirección de KAS es la de tu propia instancia. La imagen v17.5.0 es la del ejemplo del autor y no pudimos confirmar que siga vigente a 2026-10-16: probablemente esté desactualizada. Revisá en la página de soporte de Kubernetes de GitLab qué versiones del agente corresponden a tu instancia y chequeá la versión vigente en la documentación antes de instalar. Si querés comparar herramientas de CI/CD, tenemos una comparativa de herramientas de CI/CD.

Dos datos de la documentación del agente para dimensionar. Cada agente mantiene hasta 500 streams gRPC lógicos, y cada conexión dura como máximo dos horas, con una hora de gracia. GitLab recomienda un solo agente por clúster y un agente separado por cada clúster que conectes.

Dónde corre el clúster casi no importa: un cloud público, un servidor propio o un proveedor local como donweb.com sirven mientras tengan salida hacia KAS. Hay una excepción para el caso inverso. Los agentes receptivos (GitLab 17.4, Ultimate, self-managed) dejan que GitLab se conecte al agente cuando el clúster no puede llegar a la instancia.

¿Cómo funciona GitOps con GitLab a octubre de 2026: agente nativo o Flux?

Según la documentación consultada el 2026-10-16, GitLab integra Flux para el GitOps pull. La documentación de GitOps pide usar Flux y agentk juntos: Flux mantiene el clúster sincronizado con la fuente, y agentk simplifica la configuración de Flux, gestiona el acceso del clúster a GitLab y muestra el estado en la interfaz.

Acá se pisa la guía de dev.to. Su config.yaml usa gitops.manifest_projects, prune y reconcile_timeout, que son justo la parte nativa. Tomalo con pinzas: la documentación de GitOps consultada el 2026-10-16 habla de Flux, y las fuentes no precisan desde qué versión de GitLab se prioriza Flux. Por eso no podés dar por hecho que ese YAML funciona tal cual en tu versión, sobre todo si es posterior a la v17.5.0 que usa la guía. Verificalo en la documentación de la versión que tengas instalada.

OpciónModeloEstado según las fuentesCuándo usarla
Flux + agentkPullRecomendada en la doc actualDespliegue continuo en producción
GitOps nativo del agente (manifest_projects)PullNo figura en la doc actual de GitOpsSolo mantener instalaciones viejas
Flujo CI/CD con ci_accessPushVigente, con modelo de seguridad más débilTareas de pipeline puntuales o migración al agente
GitOps con GitLab diagrama explicativo

Del lado de Flux, la doc da recomendaciones concretas:

  • Usá OCI como fuente. GitLab recomienda imágenes OCI (el registro de contenedores las soporta) en lugar de un repositorio Git, porque son inmutables y la rama por defecto no dispara un sync al guardar estado.
  • Un repositorio de entrega por equipo. Se puede empaquetar en varias imágenes OCI, una por aplicación.
  • No confíes solo en el Receiver. La reconciliación inmediata tras un push reduce la demora, pero no garantiza recibir cada evento. Seguí configurando GitRepository.spec.interval.

Una limitación más: el agente solo accede al proyecto de configuración y a los proyectos públicos, así que no reconcilia de inmediato proyectos privados. Si necesitás una migración desde el GitOps nativo, la guía oficial es el camino.

¿Cómo usar el agente de GitLab en un pipeline de CI/CD con ci_access?

Autorizás proyectos o grupos en el config.yaml del agente con la clave ci_access, y cada job recibe un archivo kubeconfig con un contexto por agente compartido, en la variable $KUBECONFIG. Sin tokens pegados a mano. Los detalles están en la doc del flujo CI/CD.

# .gitlab/agents/production-agent/config.yaml
ci_access:
 projects:
 - id: my-org/microservices-app

deploy_migration:
 stage: deploy
 script:
 - kubectl config get-contexts
 - kubectl config use-context my-org/cloud-infrastructure:production-agent

El formato del contexto es <ruta/proyecto-del-agente>:<nombre-del-agente>. Si dudás de cuál es, corré kubectl config get-contexts dentro del job. Los límites que da la doc:

  • Hasta 500 proyectos o 500 grupos autorizados por agente (el límite de conexiones compartidas pasó de 100 a 500 en GitLab 17.0).
  • Misma jerarquía por defecto. Los proyectos deben compartir el grupo de nivel superior del agente, salvo que habilites la autorización a nivel instancia (self-managed, desde la 17.11). Desde la 18.1 se pueden autorizar grupos de distintos grupos de nivel superior.
  • Propagación lenta. Un cambio de autorización puede tardar uno o dos minutos.

Ponele que el agente tiene el service account con el que lo instalaste y autorizás a todo el grupo. Por defecto, el job de cualquier proyecto hereda esos permisos. Para acotar eso, en Premium y Ultimate existe la impersonation con access_as: con ci_job: {} el agente actúa como gitlab:ci_job:<id del job>, con grupos que incluyen proyecto y entorno, y vos escribís las reglas RBAC mínimas. En gestionar Kubernetes con ArgoCD profundizamos sobre esto.

Mi recomendación editorial (no viene de la doc): usá este flujo para tareas acotadas como una migración de base de datos o un smoke test, limitá el acceso a entornos y ramas protegidas, y dejá el despliegue de producción al esquema pull. Otro detalle de la guía: usa bitnami/kubectl:latest. Eso rompe la reproducibilidad, así que fijá la versión; la doc oficial, por ejemplo, define KUBECTL_VERSION: v1.34.

¿Qué ventajas y límites tiene GitOps con GitLab en producción?

La ventaja principal es que el clúster no necesita ningún puerto entrante, y cada cambio queda registrado como commit en Git. Lo que sigue es lo que dice la guía, con el matiz que le falta a cada punto.

  • Superficie de ataque entrante cero. El agente se conecta hacia afuera. El límite: el clúster igual necesita salida hacia KAS.
  • Auditoría en commits. Cada cambio de configuración deja huella en Git. La guía habla de firmas criptográficas, pero firmar commits no es automático: hay que configurarlo y exigirlo (hablar de auditoría “inmutable” sin eso es optimista).
  • Auto-reparación del drift. En el ejemplo de la guía, un kubectl scale a 1 réplica vuelve a 3. El límite: en el esquema actual la sincronización la hace Flux, y el reconcile_timeout del ejemplo pertenece a la parte nativa del agente.

Imaginá el día a día: subís el manifiesto a main, Flux lo aplica, alguien hace kubectl scale a 1 réplica porque quería probar algo, el clúster vuelve solo a 3 y nadie se entera salvo que mire el historial, lo cual está buenísimo hasta que esa persona necesitaba justamente la réplica sola para depurar.

Una propuesta de verificación, presentada como criterio editorial y no como prueba nuestra: antes de producción, repetí el escenario en staging. Escalá a 1 réplica, medí cuánto tarda en volver a 3 y compará con tu intervalo de Flux. Después corré kubectl config get-contexts en un job y confirmá que aparecen solo los agentes que autorizaste. Para más detalles técnicos, mirá runners de GitLab en un CI híbrido.

Qué está confirmado y qué no

Confirmado en la documentación oficial de GitLab (consultada el 2026-10-16):

  • GitLab integra Flux para GitOps y recomienda usarlo junto con agentk.
  • El flujo CI/CD es push y tiene un modelo de seguridad más débil; no se recomienda para producción.
  • ci_access admite hasta 500 proyectos o grupos, y la impersonation está en Premium y Ultimate.
  • La página de soporte lista Kubernetes 1.34, 1.35 y 1.36.

No confirmado, o dependiente de tu versión:

  • Qué pasa con el GitOps nativo del agente en cada versión: las fuentes no lo detallan.
  • Desde qué versión de GitLab se prioriza Flux: las fuentes tampoco lo precisan.
  • Si el config.yaml de la guía de dev.to funciona hoy en tu instancia.
  • Si la imagen v17.5.0 sigue siendo compatible con la versión actual de tu GitLab.

¿Alguien lo probó de forma independiente con versiones de 2026? No encontramos evidencia en las fuentes. Tratá la guía de dev.to como ejemplo de arquitectura, no como receta.

Errores comunes

  • Copiar el config.yaml de la guía tal cual. Usa gitops.manifest_projects, la parte nativa que la documentación de GitOps consultada no menciona. Corrección: armá la sincronización con Flux y dejá en el config.yaml el acceso del agente.
  • Autorizar todo el grupo o la instancia sin impersonation. Cualquier job hereda los permisos del service account de instalación. Corrección: access_as con ci_job y RBAC mínimo.
  • Dejar imágenes sin fijar. bitnami/kubectl:latest o un tag de agente copiado de una guía generan despliegues distintos según el día. Corrección: fijá versiones y revisalas en la documentación.
  • Usar el flujo push para producción. La doc lo desaconseja. Corrección: reservalo para tareas puntuales.
  • Confiar solo en el Receiver de Flux. La doc aclara que no garantiza todos los eventos. Corrección: definí un spec.interval razonable.

Preguntas Frecuentes

¿Qué es el agente de GitLab para Kubernetes y para qué sirve?

Es un componente (agentk) que se instala en el clúster y mantiene una conexión saliente con KAS, el servidor de GitLab. Sirve para comunicarse con clústeres detrás de firewall o NAT, acceder a la API en tiempo real, empujar eventos y mantener una caché de objetos de Kubernetes.

¿Cuál es la diferencia entre despliegue push y pull en Kubernetes?

En el push, el pipeline de GitLab CI/CD envía los cambios al clúster con credenciales. En el pull, un componente dentro del clúster, como Flux, detecta cambios en Git u OCI y los aplica. El pull evita exponer la API del clúster al CI.

¿Sigue funcionando el GitOps nativo del agente de GitLab o hay que migrar a Flux?

La documentación consultada el 2026-10-16 recomienda Flux junto con agentk. Qué pasa con el GitOps nativo en cada versión no está confirmado en las fuentes, así que revisá la doc de tu versión antes de decidir. Cubrimos ese tema en detalle en contribuir al código de GitLab.

¿Cómo conecto un pipeline de GitLab CI a mi clúster sin guardar el kubeconfig?

Instalá el agente, autorizá tu proyecto con ci_access en el config.yaml y, en el job, elegí el contexto con kubectl config use-context ruta/proyecto-del-agente:nombre-del-agente. GitLab inyecta el kubeconfig en $KUBECONFIG, así que no guardás credenciales propias en las variables de CI.

¿Cuáles son las ventajas de GitOps para producción?

Las ventajas son cero puertos entrantes, historial de cambios en commits y corrección automática del drift cuando alguien modifica el clúster a mano. Tienen condiciones: el clúster necesita salida hacia KAS, la firma de commits hay que configurarla y la sincronización depende de Flux.

Conclusión

La idea de fondo de la guía es correcta: sacar el kubeconfig del CI y dejar que el clúster se conecte hacia afuera. Lo que cambió es el motor. Los ejemplos de dev.to usan la sincronización nativa del agente, y según la documentación de GitLab consultada el 2026-10-16 el esquema documentado es Flux más agentk.

Qué hacer: instalá el agente con la versión que indique la documentación vigente, armá la sincronización con Flux (idealmente con OCI), reservá ci_access para tareas puntuales con impersonation y RBAC mínimo, y probá el drift en staging antes de confiar en la auto-reparación. Si ya tenés un clúster con manifest_projects, empezá a planear la migración.

Fuentes

Te puede interesar...