Audiencia: freelancers y equipos pequeños que necesitan entregar con fiabilidad en Kubernetes sin gastar de más. Guía práctica, paso a paso, con explicaciones claras para reproducir el flujo de CI CD con GitHub Actions, GHCR y Helm.
Resumen en corto
Construye imágenes Docker en GitHub Actions, etiqueta cada imagen con el SHA del commit, publícalas en GitHub Container Registry con el token integrado GITHUB_TOKEN y despliega a Kubernetes con Helm. Mantienes todo dentro de GitHub, simplificando infraestructura y costes.
Apóyate en Deployments para actualizaciones continuas tipo rolling, cablea readiness y liveness para que los pods no reciban tráfico antes de estar listos y se reinicien si se quedan colgados. Haz que la tubería espere con helm con flags wait y atomic, y valida con kubectl rollout status para que verde signifique aplicación sana.
Errores comunes y soluciones rápidas: enviar latest, no esperar el rollout y dar a CI permisos de cluster admin. Soluciónalo con etiquetas o digests inmutables, espera al rollout y usa RBAC acotado por namespace.
Por qué este stack encaja con freelancers
Cuando trabajas solo o con un equipo pequeño, lo que no inviertes uniendo herramientas lo inviertes en entregar valor. GitHub Actions más GHCR eliminan cuentas extra y rotación de credenciales, Helm es el estándar que tus clientes esperan y Kubernetes Deployment te da rolling updates con casi cero downtime si configuras probes y esperas el rollout.
Arquitectura de alto nivel
Flow básico: commit en main dispara CI, se construye la imagen con Buildx y se etiqueta con el SHA, se empuja a GHCR, luego Helm upgrade install aplica la release y el pipeline queda bloqueado hasta que la estrategia rolling del Deployment confirma que los pods nuevos están listos. Si algo falla dentro del tiempo configurado, Helm con atomic revierte automáticamente.
Preparación única necesaria
kubectl instalado con la versión dentro del rango de compatibilidad de tu cluster. Helm v3 en el runner. GHCR habilitado y etiqueta OCI para asociar el paquete al repo. Configura permisos de workflow para permitir packages write al GITHUB_TOKEN.
Mini app de ejemplo
Servicio Node que expone dos rutas pensadas para Kubernetes: livez para liveness y healthz para readiness. La aplicación se declara lista tras unos segundos de warm up para simular conexiones a base de datos o cacheo. Un package.json mínimo permite ejecutar tests rápidos en CI. La idea clave: readiness gobierna cuándo un pod entra al balanceo, liveness reinicia procesos atascados.
Dockerfile multietapa
Separa build de runtime para lograr imágenes más pequeñas, rápidas y seguras. En la etapa de build instalas dependencias y prunes de desarrollo; en la runtime usas una base ligera tipo node 20 slim, copias solo lo necesario, expones el puerto y declaras el comando. Añade la etiqueta OCI org.opencontainers.image.source para que GHCR enlace el paquete con tu repositorio.
Estructura del chart de Helm
Valores por defecto en values.yaml con repositorio de imagen en GHCR, tag pendiente de reemplazar por el SHA, política de pull y puertos. Deployment template con probes de readiness y liveness apuntando a las rutas descritas, estrategia RollingUpdate y posibilidad de incluir imagePullSecrets cuando uses imágenes privadas. Service ClusterIP con selector por etiquetas standard. Puedes añadir helpers para nombres y etiquetas siguiendo buenas prácticas.
CI con GitHub Actions para construir, etiquetar y publicar con caché
Pasos típicos: checkout, setup de Node para tests, setup de Buildx, login en GHCR usando el GITHUB_TOKEN con permisos mínimos y build push a ghcr.io organizacion repositorio app dos puntos SHA. Activa cache from y cache to usando el backend de GitHub Actions para acelerar builds. Evita usar latest; usa el SHA del commit o incluso digest de la imagen para reproducibilidad total.
CD con Helm upgrade install, tiempos seguros y verificación de rollout
Después del push, instala kubectl y Helm en el runner, configura kubeconfig mediante un secreto codificado en base64 y ejecuta helm upgrade install con namespace objetivo y creación si no existe, setea image.tag con el SHA, añade wait y timeout, y activa atomic para rollback automático. Compleméntalo con kubectl rollout status para tener trazas claras del progreso.
Probes de salud que evitan caídas inesperadas
Readiness impide que el Service dirija tráfico a pods no preparados. Liveness reinicia contenedores cuando el proceso está colgado. Ajusta initialDelaySeconds y periodSeconds a los tiempos reales de tu app. Si el arranque es muy lento usa un startup probe para aplazar liveness hasta que el boot haya terminado.
Trampas frecuentes y cómo evitarlas
Enviar latest complica saber qué binarios corren y puede saltarse pulls. Etiqueta por SHA o referencia por digest. No esperar al rollout deja pipelines en verde mientras usuarios reciben errores; añade wait, timeout y valida con rollout status. Evita cluster admin para CI; crea RBAC mínimo por namespace con los recursos y verbos que tu chart necesita.
RBAC mínimo para CI
Crea un ServiceAccount en el namespace de despliegue, un Role con permisos sobre deployments, replicasets, services, configmaps, secrets e ingresses con verbos get list watch create update patch, y su RoleBinding correspondiente. Entrega a CI un kubeconfig asociado a ese ServiceAccount y reduce drásticamente la superficie de riesgo.
Registros privados e imagePullSecrets con GHCR
Si tus paquetes en GHCR son públicos, no necesitas secreto de pull. Si son privados, crea un Secret de tipo docker registry con servidor ghcr.io y referencia ese secreto en el spec del pod o en el ServiceAccount. En valores de Helm, declara imagePullSecrets con el nombre del secreto usado en el namespace de producción.
Rollbacks y verificación de estado
Tienes dos niveles. A nivel Helm, revisa el historial con history y vuelve atrás con rollback. A nivel Kubernetes, usa kubectl rollout status para confirmar convergencia del Deployment y kubectl rollout undo para deshacer cambios del ReplicaSet si fuera necesario. Con atomic, los fallos durante upgrade revierten solos.
Estructura de repositorio sugerida
Un directorio para el código de la app, Dockerfile en la raíz, chart con Chart.yaml, values por entorno y plantillas, rbac con manifiestos de permisos y el workflow de CI en la carpeta de GitHub. Secretos mínimos en GitHub Actions: KUBECONFIG_DATA y el GITHUB_TOKEN con permisos de packages write definidos en el workflow o en la configuración del repositorio.
Alternativa con Kustomize
Si prefieres overlays sin plantillas, usa kustomize integrado en kubectl. La cadena sería build, push, kubectl apply con el overlay de entorno y kubectl rollout status. Resulta muy práctico para repos pequeños de un servicio y personalizaciones simples, mientras que Helm brilla cuando necesitas empaquetado o tu cliente ya trabaja con charts.
Extras útiles para CI
Prueba de humo tras el despliegue con un port forward temporal que consulte la ruta de salud y falle el job si no devuelve ok. Digest pinning aún más estricto que tags: inspecciona la imagen publicada para obtener sha256 y referencia la imagen como repositorio arroba sha256. Si necesitas multi arquitectura, añade plataformas linux amd64 y linux arm64 en build push y habilita QEMU.
Referencias recomendadas
Documentación oficial de Kubernetes para Deployments, rollouts, probes, RBAC e imágenes con tags, digests e imagePullSecrets. Documentación de Helm para upgrade con flags install, wait y atomic, estructura de charts y buenas prácticas. Guías de GitHub Actions y Docker para Buildx, login, build push y caché en CI.
Cierre
Este circuito es el que usamos cuando un cliente necesita despliegues fiables esta semana sin reconstruir su plataforma. Escala de un servicio a varios, se explica fácil a equipos no plataformas y mantiene los costes a raya: un chart, un workflow, un registro, imágenes inmutables etiquetadas por SHA o con digest, probes que reflejan salud real, rollouts que esperan y permisos de despliegue acotados con RBAC en lugar de cluster admin.
Q2BSTUDIO: tu aliado para entregar valor continuo
En Q2BSTUDIO diseñamos e implementamos pipelines CI CD productivos sobre Kubernetes, GitHub Actions y Helm, integrados con servicios cloud aws y azure, para que puedas lanzar cambios pequeños con frecuencia sin sacrificar calidad. Creamos aplicaciones a medida y software a medida con foco en rendimiento, observabilidad y seguridad, y contamos con un equipo experto en inteligencia artificial, ia para empresas y agentes IA para automatizar procesos y acelerar tu time to market. También ofrecemos ciberseguridad de extremo a extremo y auditorías, además de servicios inteligencia de negocio y cuadros de mando con power bi.
Si estás explorando plataformas nativas cloud y deseas una infraestructura preparada para crecer, descubre nuestros servicios en la nube en este enlace: servicios cloud aws y azure. Y si buscas un equipo que te acompañe desde la idea hasta la operación con productos robustos, aquí puedes ver cómo abordamos aplicaciones a medida y software a medida.
Palabras clave para ayudarte a encontrarnos: aplicaciones a medida, software a medida, inteligencia artificial, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio, ia para empresas, agentes IA, power bi.