Ship más inteligente, no más difícil: Kubernetes CI/CD asequibles con GitHub Actions + Helm

Audiencia: Freelancers y pequeños equipos que necesitan una entrega fiable y barata a Kubernetes.Esta es una guía larga y práctica con un montón de códigos copiables y explicaciones adicionales. Título: DR Construye imágenes de Docker en Acciones de GitHub, etiqueta cada imagen con el SHA de comisión, pulsa en el Registro de contenedores de GitHub (GHCR) usando el GITHUB_TOKEN incorporado y implementa a Kubernetes con Helm. Confíe en las implementaciones de Kubernetes para las actualizaciones en movimiento, y las sondas de disponibilidad de cable + vida para que los pods no obtengan tráfico hasta que estén listos (y se reinicien si se colgan). Tres errores recurrentes que veo: (1) envío: ultimo, (2) no esperando a los lanzamientos, (3) dando CI cluster-admin. correcciones: etiqueta o digest-pin imágenes, espera en el lanzamiento, y los permisos de implementación de alcance con RBAC en el espacio de nombres de destino. (Kubernetes) Mesa de contenidos Por qué esta pila se adapta a los freelancers La arquitectura en una sola imagen Configuración y contexto que necesitarás Una pequeña aplicación de muestra (Node.js) que realmente se puede ejecutar Dockerfile: construcción en varias etapas, explicado Estructura y valores del gráfico del casco: qué está sucediendo y por qué CI: GitHub Acciones flujo de trabajo para construir/tag/push (con caché) CD: Actualización del casco, temporadas seguras y controles de implementación Health probes that prevent surprise downtime Las trampas que veo semanalmente (y cómo evitarlas) RBAC mínimo para CI (no más cluster-admin) Registros privados y imagePullSecrets (nota de GHCR) Rollbacks, quien hace qué, y un rápido “estoy sano?” Un diseño reutilizable de repo y una lista de verificación de secretos Opcional: el mismo ciclo con Customize Apéndice: pasos CI adicionales (pruebas, concurrencia, controles de humo) Referencias 1) Por qué esta pila se adapta a los freelancers Cuando estás solo o trabajando con un pequeño equipo, el tiempo que La combinación de abajo mantiene el radio de explosión pequeño y las partes en movimiento comprensibles: No se GitHub Actions + GHCR: ya almacenas tu código en GitHub; Actions ejecuta tus ediciones y GHCR mantiene tus imágenes en el mismo límite de confianza. Con los permisos de flujo de trabajo adecuados, el GITHUB_TOKEN integrado es suficiente para empujar las imágenes, sin tokens adicionales para rotar, sin cuentas adicionales para gestionar. (GitHub Docs) Helm: los clientes esperan gráficos de Helm. Los gráficos son sólo plantillas con un lugar claro para los estándares (values.yaml), y una manera sencilla de superponerlos por entorno. (Helm) Despliegue de Kubernetes: las actualizaciones de despliegue son por defecto – Kubernetes sustituye gradualmente los viejos pods por nuevos y solo declara éxito después de que el nuevo ReplicaSet esté listo. 2) La arquitectura en una sola imagen El último paso es importante: hasta que el Despliegue sea realmente saludable (o temporales), lo que significa que las tuberías verdes se alinean con una aplicación saludable, no sólo “manifiestan aplicadas”. ( ) your pipeline blocks Kubernetes 3) Configuración única y contexto que necesitarás Usar la instalación oficial para que las versiones coincidan con el desvío soportado por su clúster (normalmente ±1 menor). (Kubernetes) Helm v3 en el corredor. La página de instalación oficial documenta el guión que muchas personas usan en CI. (Helm) Agregue la etiqueta OCI org.opencontainers.image.source en su Dockerfile para que GHCR enlace automáticamente el paquete a su repo; use GITHUB_TOKEN con paquetes: escriba con permisos de flujo de trabajo. (GitHub Docs) Si tu si está demasiado lejos, perseguirás errores extraños.Los documentos oficiales llaman a la regla "dentro de uno menor". ( ) Why versions/skew matters: kubectl Kubernetes 4) Una pequeña aplicación de muestra (Node.js) que realmente se puede ejecutar Dos endpoints que mapean directamente a las sondas Kubernetes: // app/server.js import http from 'node:http'; const port = process.env.PORT || 3000; let ready = false; // Simulate warm-up work: DB connection, JIT, caches... setTimeout(() => (ready = true), 3000); const server = http.createServer((req, res) => { if (req.url === '/livez') return res.end('ok'); // liveness probe if (req.url === '/healthz') return res.end(ready ? 'ok' : 'starting'); // readiness probe res.writeHead(200, { 'content-type': 'text/plain' }); res.end('hello'); }); server.listen(port, () => console.log(`listening on ${port}`)); El mínimo Puede realizar las pruebas rápidamente: package.json { "name": "demo-app", "type": "module", "scripts": { "start": "node app/server.js", "test": "node -e \"const http=require('http');http.get('http://127.0.0.1:3000',r=>process.exit(r.statusCode===200?0:1))\"" }, "dependencies": {} } El punto de y Kubernetes los trata de manera diferente - tráfico de puertas; reiniciar los contenedores atrapados. En un instante conectaremos ambos en el Despliegue. ( ) /healthz /livez readiness liveness Kubernetes 5) Dockerfile: construcción de múltiples etapas, explicado ¿Por qué multietapas? Las herramientas de construcción (compiladores, bundlers) no son necesarias en el tiempo de ejecución. y Las etapas hacen que las imágenes sean más pequeñas, más rápidas y más seguras.Los documentos oficiales de Docker recomiendan explícitamente las construcciones multietapas para la producción. ( ) build runtime Docker Documentación # Dockerfile # -------- build stage -------- FROM node:20 AS build WORKDIR /app COPY package*.json ./ RUN npm ci --omit=dev COPY . . # leave only prod deps RUN npm prune --omit=dev # -------- runtime stage -------- FROM node:20-slim WORKDIR /app COPY --from=build /app ./ EXPOSE 3000 CMD ["node","app/server.js"] # helps GHCR link this image to your repo automatically LABEL org.opencontainers.image.source="https://github.com/your-org/your-repo" Si alguna vez necesita imágenes multi-arco (arm64 portátil, servidor amd64), y QEMU hacen que esto sea posible con un único flujo de trabajo. Nos aferraremos a un único arco para la velocidad. ( ) Buildx Docker Documentación 6) Estructura y valores del gráfico del casco: qué está sucediendo y por qué Los gráficos de casco son carpetas con un diseño específico; los estándares viven en Los templos viven bajo Puede sobrecargar los parámetros por entorno con o en línea En el ( ) values.yaml templates/ --values path.yaml --set key=value El helicóptero chart/Chart.yaml apiVersion: v2 name: app description: Minimal demo app type: application version: 0.1.0 # chart version appVersion: "0.1.0" # your app version (for humans; not enforced) (defaults que va a override en CI) chart/values.yaml image: repository: ghcr.io/your-org/your-repo/app tag: "CHANGE_ME" # CI will set this to the commit SHA pullPolicy: IfNotPresent service: type: ClusterIP port: 80 targetPort: 3000 replicaCount: 2 resources: requests: { cpu: 100m, memory: 128Mi } limits: { cpu: 500m, memory: 256Mi } # optional if using private images # imagePullSecrets: # - name: ghcr-pull (Proba + actualización de rodamiento) chart/templates/deployment.yaml apiVersion: apps/v1 kind: Deployment metadata: name: {{ include "app.fullname" . }} labels: app.kubernetes.io/name: {{ include "app.name" . }} spec: replicas: {{ .Values.replicaCount }} strategy: { type: RollingUpdate } selector: matchLabels: app.kubernetes.io/name: {{ include "app.name" . }} template: metadata: labels: app.kubernetes.io/name: {{ include "app.name" . }} spec: {{- if .Values.imagePullSecrets }} imagePullSecrets: {{- range .Values.imagePullSecrets }} - name: {{ .name }} {{- end }} {{- end }} containers: - name: app image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}" imagePullPolicy: {{ .Values.image.pullPolicy }} ports: - containerPort: {{ .Values.service.targetPort }} readinessProbe: httpGet: { path: /healthz, port: {{ .Values.service.targetPort }} } initialDelaySeconds: 5 periodSeconds: 5 livenessProbe: httpGet: { path: /livez, port: {{ .Values.service.targetPort }} } initialDelaySeconds: 15 periodSeconds: 10 chart/templates/service.yaml apiVersion: v1 kind: Service metadata: name: {{ include "app.fullname" . }} spec: type: {{ .Values.service.type }} selector: app.kubernetes.io/name: {{ include "app.name" . }} ports: - port: {{ .Values.service.port }} targetPort: {{ .Values.service.targetPort }} Si prefieres un enfoque más DRY, agrega un La guía de las mejores prácticas de Helm cubre cómo estructurar valores y ayudantes de forma limpia. ( ) _helpers.tpl El helicóptero CI: Acciones de GitHub para construir, etiquetar y empujar (con caché) Usaremos las Acciones oficiales de Docker: , de , y Hemos marcado la imagen con la Cada uno de ellos es inmutable e inmutable. por En el ( , de ) setup-buildx login build-push commit SHA packages: write GITHUB_TOKEN GitHub Docs de GitHub .github/workflows/ci.yml name: ci on: push: branches: [ "main" ] permissions: contents: read packages: write # allow pushing to GHCR (least privilege) jobs: build-and-push: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 # optional: speed up local tests - uses: actions/setup-node@v4 with: node-version: '20' cache: 'npm' - run: npm ci - run: npm test - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 - name: Log in to GHCR uses: docker/login-action@v3 with: registry: ghcr.io username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} - name: Build and push image uses: docker/build-push-action@v6 with: context: . push: true tags: ghcr.io/${{ github.repository }}/app:${{ github.sha }} cache-from: type=gha cache-to: type=gha,mode=max Aquí un par de gotchas: Los permisos de flujo de trabajo deben permitir la escritura de paquetes, o el GHCR rechazará los pushes.Puede establecer los estándares en la configuración de repo y aún restringir por flujo de trabajo/trabajo. (GitHub Docs) El etiquetado de imágenes con org.opencontainers.image.source ayuda a GHCR a conectar el paquete de nuevo a la interfaz de usuario de repo. (GitHub Docs) Buildx es la forma recomendada de construir imágenes en Acciones, con soporte de caché y multiarch documentado en la guía CI de Docker. (Docker Documentation) Kubernetes trata las referencias de imagen literalmente. Las etiquetas hacen que sea más difícil saber lo que está funcionando y pueden pasar por los estándares de la política de arrastre. (en el ) para una reproductibilidad perfecta—Kubernetes apoya los digestivos nativamente. ( ) Why SHA tags instead of :latest :latest digest image@sha256:... Kubernetes 8) CD: actualización del casco, temporadas seguras y controles de implementación Deploy right after a successful push. Tanto la primera vez como la repetición.Añadir (Bloquear hasta que esté listo) (No esperes para siempre) y (Rollback automático en caso de fallo). Luego, como una red de seguridad adicional, para transmitir el progreso al log de trabajo. ( , de ) helm upgrade --install --wait --timeout --atomic kubectl rollout status El helicóptero Kubernetes deploy: needs: build-and-push runs-on: ubuntu-latest environment: production steps: - uses: actions/checkout@v4 - name: Install kubectl (official) run: | curl -LO "https://dl.k8s.io/release/$(curl -Ls https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" chmod +x kubectl && sudo mv kubectl /usr/local/bin/ - name: Install Helm run: curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash - name: Configure kubeconfig env: { KUBECONFIG_DATA: ${{ secrets.KUBECONFIG_DATA }} } run: | mkdir -p $HOME/.kube echo "$KUBECONFIG_DATA" | base64 -d > $HOME/.kube/config - name: Helm upgrade (create or update) run: | helm upgrade --install app ./chart \ --namespace prod --create-namespace \ --set image.tag=${{ github.sha }} \ --wait --timeout=10m --atomic - name: Rollout status (extra verification) run: kubectl rollout status deploy/app -n prod --timeout=180s y El Helm Aumentar el nivel de éxito / fracaso de la liberación; imprime el progreso por paso y da un feedback rápido y legible cuando algo está fuera. convierte fallos en un rollback automático – útil cuando prefieres estar seguro que “medio actualizado”. ( , de ) Why both --wait kubectl rollout status --wait kubectl rollout status --atomic El helicóptero Kubernetes 9) Sondeos de salud que evitan el tiempo de inactividad sorpresa Puede tener una actualización de rodamiento perfecta y todavía servir errores si la aplicación acepta tráfico antes de que se caliente. prevenir: abren los terminales de servicio hasta que su pod dice “listo”. ¿Cuáles son las cadenas de seguridad si la aplicación se rompe a sí misma; el kubelet reinicia el contenedor después de fallas repetidas.Los documentos oficiales cubren estas semánticas y cuándo utilizar las sondas de arranque para aplicaciones más lentas. ( ) readiness probes Liveness probes Kubernetes Guía de tuning práctico: Si su aplicación necesita 20s para calentarse, establezca inicial DelaySeconds en disponibilidad en consecuencia. Si su aplicación bloquea ocasionalmente (por ejemplo, deadlock), prefiere una sonda de vida HTTP o TCP que golpee un punto final o puerto trivial. Si su aplicación es lenta para comenzar, añade una sonda de arranque para retrasar la vida hasta que se completa el arranque. (Kubernetes) 10) Las trampas que veo semanalmente (y cómo evitarlas) 10.1 Navegación :latest Lo que va mal: La misma etiqueta apunta a bits diferentes a lo largo del tiempo; la caché de arrastre y las incógnitas de políticas hacen que no sea claro si un nodo realmente arrastra la nueva imagen. La solución: etiquetar imágenes por comit SHA o usar digestos (@sha256:...). Kubernetes admite referencias de digesto; siempre obtendrá la imagen exacta. 10.2 No esperar a los rollos Lo que va mal: Su tubería termina “verde”, pero los usuarios ven errores durante 30-60 segundos porque el Despliegue aún no se ha convertido. Solución: Agregue --wait --timeout (y opcionalmente --atomic) a Helm, y ejecute el estado de implementación de kubectl para que los errores aparezcan claramente en los registros. (Helm, Kubernetes) 10.3 CI sobre-privilegio (cluster-admin) Lo que va mal: Un token filtrado equivale a un compromiso de clúster completo. La solución: Cree un ServiceAccount + Role + RoleBinding esfero al espacio de nombres de destino, con sólo los verbos y recursos que su gráfico necesita. 11) RBAC mínimo para CI (copia/pasta) # rbac/deployer.yaml apiVersion: v1 kind: ServiceAccount metadata: name: helm-deployer namespace: prod --- apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: helm-deployer namespace: prod rules: - apiGroups: ["apps"] resources: ["deployments","replicasets"] verbs: ["get","list","watch","create","update","patch"] - apiGroups: [""] resources: ["services","configmaps","secrets"] verbs: ["get","list","watch","create","update","patch"] - apiGroups: ["networking.k8s.io"] resources: ["ingresses"] verbs: ["get","list","watch","create","update","patch"] --- apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: helm-deployer namespace: prod subjects: - kind: ServiceAccount name: helm-deployer namespace: prod roleRef: kind: Role name: helm-deployer apiGroup: rbac.authorization.k8s.io Esto sigue la Principio: el SA sólo puede tocar el espacio de nombres y los tipos de recursos que gestiona su gráfico. Si un token se escapa, el daño se limita a aquellos verbos / recursos en RBAC es el modelo de autorización soportado en Kubernetes. ( ) least privilege prod Kubernetes 12) Registros Privados & (en el GCR) imagePullSecrets Imágenes secretas Paquetes públicos del GHCR: cualquiera puede retirar de forma anónima; no se requiere secreto. Paquetes de GHCR privados: crea un secreto del registro de Docker y hace referencia a él en la especificación del pod (o lo une a su ServiceAccount). Kubernetes documenta tanto el tipo de secreto como el mecanismo de imagePullSecrets. (Kubernetes) Crear un secreto de puño y usarlo en : prod kubectl create secret docker-registry ghcr-pull \ --docker-server=ghcr.io \ --docker-username=YOUR_GITHUB_USERNAME \ --docker-password=YOUR_GHCR_TOKEN_OR_PAT \ --docker-email=you@example.com \ -n prod Luego en Para el prod: values.yaml imagePullSecrets: - name: ghcr-pull Los documentos oficiales muestran el mismo flujo para los registros privados; el GHCR utiliza el estándar Docker auth. ( ) Kubernetes 13) Rollbacks, quien hace qué, y un rápido “estoy sano?” Dos cuadros te pueden ayudar: Historia de lanzamiento de helm → helm history/rollback. history → . Deployment kubectl rollout undo/status Los comandos típicos: # See release history managed by Helm helm history app -n prod # Roll back to the previous release helm rollback app 1 -n prod # Verify the Deployment converges kubectl rollout status deploy/app -n prod --timeout=180s El Helm ya automáticamente vuelve a los fallos durante la actualización. En la actualidad, se utiliza para la fabricación de muebles de alta calidad en el interior de la ciudad o en el interior de la ciudad. ( , de ) --atomic kubectl rollout status El helicóptero Kubernetes 14) Un diseño reutilizable de repo y una lista de verificación de secretos repo-root/ app/ # your code Dockerfile chart/ Chart.yaml values.yaml values-staging.yaml values-prod.yaml templates/ deployment.yaml service.yaml _helpers.tpl rbac/ deployer.yaml .github/workflows/ci.yml Secrets (GitHub → Settings → Secrets and variables → Actions): KUBECONFIG_DATA – base64 kubeconfig para el desplegador de casco ServiceAccount. GITHUB_TOKEN – auto-injectado; establecer permisos de flujo de trabajo: paquetes: escribir para presionar a GHCR (usar repo/org por defecto o YAML). (Documentos de GitHub) 15) Opcional: el mismo ciclo con Custodia Custodia ¿Prefieres sobrepuestos sin templos? Está construido en Su tubería se convierte en: build → push → → Es excelente para reposo de servicio único y pequeñas personalizaciones; el casco tiende a ser más práctico cuando necesita packagability o su cliente ya utiliza gráficos. ( ) Kustomize kubectl kubectl apply -k overlays/prod kubectl rollout status Kubernetes Quick sketch: kustomize/ base/ deployment.yaml service.yaml kustomization.yaml overlays/ prod/ kustomization.yaml # patches image tag to $GIT_SHA 16) Apéndice: pasos CI adicionales (pruebas, concurrencia, controles de humo) (Port-forward para 1 solicitud): A tiny smoke check after deploy - name: Port-forward and smoke test run: | kubectl -n prod port-forward svc/app 8080:80 & PF_PID=$! sleep 3 curl -fsS http://127.0.0.1:8080/healthz | grep -q "ok" kill $PF_PID Digest pinning (even stricter than tags): # Check the pushed image's digest docker buildx imagetools inspect ghcr.io/${OWNER}/${REPO}/app:${GITHUB_SHA} # Then set in values-prod.yaml: # image: # repository: ghcr.io/${OWNER}/${REPO}/app # tag: "" # leave empty when using a digest # digest: "sha256:..." Si desea plantar el uso de digesto en Helm, ajuste su estanza de imagen y el modelo: # values.yaml (allow either tag OR digest) image: repository: ghcr.io/your-org/your-repo/app tag: "CHANGE_ME" digest: "" # templates/deployment.yaml (image reference) image: "{{ .Values.image.repository }}{{- if .Values.image.digest -}}@{{ .Values.image.digest }}{{- else -}}:{{ .Values.image.tag }}{{- end }}" Kubernetes entiende digiere directamente.Es la forma más determinista de desplomarse Lo que has construido) ) @sha256: Exactamente Kubernetes añadir Dos y incluye QEMU si es necesario. los documentos de Docker muestran ambos. ( ) Multi-arch builds (if you need arm64): platforms: linux/amd64,linux/arm64 build-push-action Docker Documentación 17) Referencias Kubernetes Deployments (rolling update behavior & concepts). (Kubernetes) Rolling updates overview (tutorial). (Kubernetes) kubectl status rollout (command reference). (Kubernetes) Probes (living, readiness, startup). (Kubernetes) Imágenes: tags, digests, and imagePullSecrets. (Kubernetes) autorización RBAC (oficial). (Kubernetes) Instalar kubectl y nota de desvío de versión. (Kubernetes) Actualización del casco del casco y banderas (--instalar, --esperar, --atomic). (Helm) Instalar el casco (script CI). (Helm) Estructura del gráfico y referencias de valores y mejores prácticas. (Helm) GitHub Actions & GHCR Publishing Docker images with Actions. (GitHub Docs) Uso de GITHUB_TOKEN con permisos menos privilegiados. (GitHub Docs) Trabajo con el registro de contenedores (GHCR) y etiquetas OCI. (GitHub Docs) Docker oficial GitHub Actions: setup-buildx, login, build-push. (GitHub) Docker's CI guide for GitHub Actions. (Docker Documentation) Docker Multi-stage builds (por qué/cómo), mejores prácticas, multiplataforma. (Docker Documentation) Cierra los pensamientos Este es el camino que llego cuando un cliente dice: Escala de un solo servicio a muchos, y cada parte de ella es explicable a las personas no de la plataforma: “Queremos implementaciones fiables esta semana, no una reconstrucción de la plataforma”. Un gráfico, un flujo de trabajo, un registro. Imágenes inmutables (etiquetas de SHA o digestos), sondas que reflejan la salud real de las aplicaciones y lanzamientos que esperan. Permisos de implementación específicos, no cluster-admin. Quédate conectado Si te ha gustado este artículo y quieres explorar más sobre el desarrollo web, no dudes en conectarte conmigo en varias plataformas: Dev. en HackerDía.com por hashnode.com En Twitter.com En Instagram.com La cartera V1 Sus comentarios y preguntas son siempre bienvenidos. Sigue aprendiendo, codificando y creando aplicaciones web increíbles.