Audiencia: freelancers y equipos pequeños que necesitan un ciclo de entrega fiable y barato hacia Kubernetes. Esta guía práctica va paso a paso con instrucciones claras y justificadas para que puedas copiar la estrategia y adaptarla a tu contexto.
Resumen rápido TLDR
- Construye imágenes Docker en GitHub Actions, etiqueta cada imagen con el SHA del commit, publica en GitHub Container Registry usando GITHUB_TOKEN con permisos mínimos y despliega con Helm. Mantienes todo dentro de GitHub y reduces coste y complejidad. Consulta la guía oficial en GitHub Docs.
- Confía en Deployments de Kubernetes para actualizaciones rolling, añade readiness y liveness probes para que los pods solo reciban tráfico cuando estén listos y se reinicien si se quedan colgados. Haz que la tubería espere con helm --wait --atomic y kubectl rollout status. Más info en Kubernetes y Helm.
- Tres fallos frecuentes: usar la etiqueta latest, no esperar al rollout y dar cluster-admin al CI. Soluciones: etiquetar por SHA o fijar por digest, esperar al rollout y aplicar RBAC mínimo por namespace. Referencia en Kubernetes.
Índice
1 Por qué este stack encaja con freelancers. 2 Arquitectura de alto nivel. 3 Preparación única y contexto. 4 Mini app de ejemplo. 5 Dockerfile multietapa. 6 Estructura del chart de Helm. 7 CI con GitHub Actions para build y push con caché. 8 CD con Helm upgrade y verificación de rollout. 9 Probes de salud. 10 Errores comunes. 11 RBAC mínimo para CI. 12 Registros privados e imagePullSecrets. 13 Rollbacks y comprobaciones. 14 Estructura de repo y checklist de secretos. 15 Alternativa con Kustomize. 16 Apéndice de CI extra. 17 Referencias.
1 Por qué este stack encaja con freelancers
- GitHub Actions y GHCR: el código, el CI, el registro y los permisos viven en el mismo perímetro de confianza. Con permisos de workflow adecuados, GITHUB_TOKEN basta para publicar imágenes, sin tokens extra ni cuentas adicionales. Guía en GitHub Docs. - Helm: clientes lo esperan, valores por defecto claros en values.yaml y overrides por entorno. Documentación en Helm. - Kubernetes Deployments: rolling update por defecto con éxito declarado cuando los pods nuevos están listos, siempre que conectes probes y esperes el rollout. Conceptos en Kubernetes.
2 Arquitectura en una imagen mental
El flujo es código en GitHub, Actions construye y etiqueta por SHA, publica en GHCR, Helm actualiza el release en Kubernetes y el pipeline se bloquea hasta que el Deployment está saludable o se agota el tiempo. Esto alinea pipeline en verde con aplicación saludable y no solo con manifiestos aplicados. Referencia de estado de rollout en Kubernetes.
3 Preparación única y contexto
- Instala kubectl acorde al skew soportado por tu clúster, normalmente mas o menos una minor. Kubernetes. - Instala Helm v3 en el runner, script oficial recomendado. Helm. - Activa GHCR en tu organización o repo y añade la etiqueta OCI org.opencontainers.image.source en la imagen para vincularla al repositorio. GitHub Docs. Mantén versiones compatibles para evitar errores sutiles de cliente servidor.
4 Mini app de ejemplo
Imagina una app Node que expone dos endpoints: livez para liveness y healthz para readiness. La app tarda unos segundos en calentarse simulando conexión a base de datos y cacheo. Así conectaremos probes que reflejen el estado real antes de recibir tráfico. Semántica de probes en Kubernetes.
5 Dockerfile multietapa
Separa etapas de build y runtime. En build instalas dependencias de producción, construyes y haces prune. En runtime usas una imagen base ligera, copias el artefacto y defines el comando de arranque y el puerto. Añade la etiqueta OCI org.opencontainers.image.source para vincular en GHCR. Multietapa recomendada en Docker. Si necesitas multi arquitectura, Buildx y QEMU permiten plataformas como linux amd64 y linux arm64 en un solo workflow, guía en Docker.
6 Helm chart y valores
Estructura típica con Chart.yaml, values.yaml y plantillas en templates. Valores por defecto que luego sobreescribes por entorno. En values define image repository en GHCR, tag inicial cambiame que el CI sustituirá por el SHA, pullPolicy, service con puerto 80 hacia el target 3000, replicaCount y recursos. En deployment añade probes de readiness a path healthz y liveness a path livez, así como strategy RollingUpdate. Puedes añadir imagePullSecrets si usas imágenes privadas. Buenas prácticas de charts en Helm.
7 CI con GitHub Actions para construir, etiquetar y publicar con caché
Pasos clave: checkout, setup-node opcional para tests rápidos, setup-buildx, login a GHCR con el GITHUB_TOKEN y permisos packages write, build y push con docker build push action usando caché tipo gha y tag ghcr.io propietario repositorio nombre imagen dos puntos SHA del commit. Control de permisos del token en GitHub Docs y acciones oficiales en Docker. Etiquetar por SHA evita ambigüedades propias de latest y facilita trazabilidad; también puedes fijar por digest con referencia image arroba sha256.
8 CD con Helm upgrade, timeouts seguros y verificación de rollout
Tras publicar la imagen, ejecuta helm upgrade --install nombre release ruta chart con namespace objetivo y create namespace si no existe, establece image.tag con el SHA, añade --wait, --timeout adecuado y --atomic para rollback automático en fallo. Como refuerzo, usa kubectl rollout status sobre el Deployment para ver progreso en el log y fallas con claridad. Para autenticarte, inyecta KUBECONFIG_DATA en secreto y crea el archivo de configuración en el runner. Referencias en Helm y Kubernetes.
9 Probes de salud que evitan caídas inesperadas
Readiness impide que un pod reciba tráfico hasta que de verdad esté listo. Liveness reinicia contenedores que se quedan bloqueados. Ajustes prácticos: sube initialDelaySeconds de readiness si tu app necesita más tiempo para calentar; usa liveness http o tcp contra un endpoint trivial; si el arranque es lento, añade startup probe para retrasar liveness. Guía oficial en Kubernetes.
10 Errores comunes y cómo evitarlos
- Enviar latest: crea incertidumbre sobre lo que corre. Solución: etiquetar por SHA o usar digest. - No esperar el rollout: el pipeline marca éxito y los usuarios ven errores. Solución: usar --wait --timeout y kubectl rollout status más --atomic. - CI con cluster-admin: rotura completa si se filtra. Solución: RBAC mínimo por namespace con solo los verbs y resources necesarios. RBAC en Kubernetes.
11 RBAC mínimo para CI
Crea un ServiceAccount llamado helm-deployer en el namespace destino por ejemplo prod, un Role con permisos get list watch create update patch sobre deployments y replicasets en el grupo apps, sobre services configmaps y secrets en el grupo base y sobre ingresses en networking.k8s.io, y un RoleBinding que vincule el Role al ServiceAccount en ese namespace. Principio de mínimo privilegio para contener el impacto de un token expuesto.
12 Registros privados e imagePullSecrets con GHCR
Si el paquete en GHCR es público no necesitas secreto de pull. Si es privado crea un secret de tipo docker registry por ejemplo ghcr-pull en el namespace de despliegue con servidor ghcr.io y credenciales válidas, y referencia ese secret en imagePullSecrets del pod o en el ServiceAccount. Guía en Kubernetes.
13 Rollbacks y comprobación rápida de salud
Dos niveles: historia y rollback de Helm con helm history y helm rollback, e historia del Deployment con kubectl rollout undo y estado con kubectl rollout status. Recuerda que --atomic ya revierte automáticamente si el upgrade falla.
14 Estructura de repositorio y checklist de secretos
Estructura sugerida: carpeta app para el código, Dockerfile en la raíz, chart de Helm con Chart.yaml, values por entorno y plantillas, carpeta rbac con manifiestos para el ServiceAccount y roles, y workflow en .github workflows. Secretos clave: KUBECONFIG_DATA con kubeconfig base64 del ServiceAccount de despliegue y GITHUB_TOKEN con permisos packages write configurados en el workflow o en la configuración del repositorio.
15 Alternativa con Kustomize
Si prefieres overlays sin plantillas, Kustomize viene integrado en kubectl. Flujo: build y push de imagen, kubectl apply -k sobre overlays del entorno y kubectl rollout status. Encaja muy bien con repos de un solo servicio y ajustes ligeros; Helm destaca cuando necesitas empaquetado y reutilización de charts. Más info en Kubernetes.
16 Apéndice de CI adicional
- Smoke test rápido tras el despliegue: port forward del servicio a un puerto local, una llamada http al endpoint de health y cierre del túnel. - Fijación por digest: inspecciona el digest de la imagen publicada y úsalo en el despliegue con referencia image arroba sha256, lo más determinista. - Multi arquitectura: añade platforms linux amd64 y linux arm64 en build push action y habilita QEMU si procede.
17 Referencias
- Kubernetes: Deployments, rolling updates, probes, imágenes y RBAC en la documentación oficial en kubernetes.io. - Helm: flags de upgrade y estructura de charts en helm.sh. - GitHub Actions y GHCR: publicación de imágenes y permisos del token en docs.github.com. - Docker: multietapa, mejores prácticas y CI con Buildx en docs.docker.com.
Consejos finales
Un chart, un workflow y un registro mantienen la simplicidad. Imágenes inmutables por SHA o digest, probes que reflejen la salud real y rollouts que esperan convierten cada despliegue en un paso seguro. Añade RBAC mínimo para que tu CI no sea un riesgo. Si operas en nubes públicas, valora apoyarte en una base bien gestionada de servicios cloud como AWS o Azure para red, identidad, registro y observabilidad; si te interesa optimizar esa capa, revisa nuestro enfoque en servicios cloud AWS y Azure. Y si quieres orquestar CI CD y operaciones repetibles extremo a extremo, la automatización de procesos te dará velocidad y control.