Kubernetes con Claude Code: Deployment, Service, Ingress y rollback
Guía práctica para crear con Claude Code YAML seguro de Kubernetes con probes, recursos, CI y rollback.
Crear YAML revisable, no solo YAML generado
Kubernetes permite ejecutar aplicaciones en contenedores dentro de un clúster, pero el primer choque para principiantes es la cantidad de piezas que aparecen juntas: Deployment, Service, Ingress, ConfigMap, Secret, probes, requests, limits, rollout y rollback. Si pides a Claude Code “genera YAML de Kubernetes” sin contexto, puede crear algo que parece correcto pero usa latest, no define health checks, expone un Service demasiado abierto o coloca un Secret de ejemplo en el repositorio.
El objetivo de esta guía es usar Claude Code como ayudante para construir una base segura y revisable. El ejemplo usa nginx:1.27-alpine y una página HTML servida desde un ConfigMap, así que no necesitas una imagen privada para practicar. Puedes probarlo en kind, minikube, Docker Desktop Kubernetes o un clúster temporal. Después sustituyes la imagen, el path de salud y el Ingress por los de tu aplicación real.
Trabaja siempre con las referencias oficiales a mano: Deployments, Services, Ingress, probes, gestión de recursos, ConfigMap, Secret y kubectl rollout. Para seguir dentro de ClaudeCodeLab, revisa integración con Docker, CI/CD con Claude Code, code review y permisos.
Casos de uso reales
No empieces con una plataforma enorme. Empieza con una unidad pequeña que puedas desplegar, verificar, romper a propósito y recuperar. Eso enseña más que copiar un chart complejo sin entenderlo.
| Caso | Objetivo | Qué pedir a Claude Code |
|---|---|---|
| Primera app interna | Publicar una web detrás de un Service estable | Deployment, ClusterIP Service, probes, requests y limits |
| Taller o formación | Que todos ejecuten el mismo flujo | Manifest con namespace, comandos de prueba y fallo controlado |
| Revisión preproducción | Detectar riesgos antes del release | Selectors, Secret, probes, Ingress y rollback |
| Gate de Pull Request | Evitar que YAML peligroso llegue a main | dry-run en CI y checklist de revisión |
El tema también monetiza bien porque el lector no busca una definición académica: quiere evitar una caída real. Por eso esta guía enlaza con recursos gratuitos, plantillas y formación y consultoría de Claude Code para equipos que necesitan adaptar el flujo a su repositorio.
Prompt con límites claros
En Kubernetes, el prompt debe incluir lo que quieres y lo que no quieres. Si no marcas límites, Claude Code puede elegir LoadBalancer, escribir Secrets ficticios, añadir RBAC de clúster o asumir un Ingress Controller que no existe en tu entorno.
Crea un despliegue de Kubernetes para principiantes que se pueda probar localmente.
Requisitos:
- namespace claude-k8s-demo
- usar nginx:1.27-alpine, no una imagen privada
- incluir un ConfigMap con una página HTML
- Deployment con replicas 2, RollingUpdate, readinessProbe, livenessProbe y resources
- Service de tipo ClusterIP
- Ingress opcional con host claude-k8s.local
- explicar la política de Secret sin generar valores reales
- incluir comandos de apply, rollout status, port-forward, fallo y rollback
Restricciones:
- no usar NodePort ni LoadBalancer
- no escribir valores reales de Secret en YAML
- no crear ClusterRole, ClusterRoleBinding ni comandos destructivos
Este prompt hace que la revisión sea concreta: labels, selectors, puertos, probes, recursos y secretos. Si tu equipo repite esta tarea, mueve las reglas estables a CLAUDE.md; puedes conectarlo con buenas prácticas de CLAUDE.md.
Manifest listo para copiar
Guarda esto como k8s/claude-k8s-demo.yaml. El Ingress solo será navegable si tienes un controller instalado, pero el Service se puede verificar con port-forward.
apiVersion: v1
kind: Namespace
metadata:
name: claude-k8s-demo
---
apiVersion: v1
kind: ConfigMap
metadata:
name: demo-page
namespace: claude-k8s-demo
data:
APP_ENV: "demo"
index.html: |
<!doctype html>
<html lang="es">
<head><meta charset="utf-8" /><title>Claude Code Kubernetes Demo</title></head>
<body><h1>Claude Code Kubernetes Demo</h1><p>Deployment, Service, ConfigMap, probes are running.</p></body>
</html>
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: demo-web
namespace: claude-k8s-demo
labels:
app: demo-web
spec:
replicas: 2
revisionHistoryLimit: 5
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 1
maxUnavailable: 0
selector:
matchLabels:
app: demo-web
template:
metadata:
labels:
app: demo-web
spec:
containers:
- name: nginx
image: nginx:1.27-alpine
ports:
- name: http
containerPort: 80
resources:
requests:
cpu: "50m"
memory: "64Mi"
limits:
cpu: "250m"
memory: "128Mi"
readinessProbe:
httpGet:
path: /
port: http
initialDelaySeconds: 3
periodSeconds: 5
livenessProbe:
httpGet:
path: /
port: http
initialDelaySeconds: 10
periodSeconds: 10
volumeMounts:
- name: demo-page
mountPath: /usr/share/nginx/html/index.html
subPath: index.html
readOnly: true
volumes:
- name: demo-page
configMap:
name: demo-page
---
apiVersion: v1
kind: Service
metadata:
name: demo-web
namespace: claude-k8s-demo
spec:
type: ClusterIP
selector:
app: demo-web
ports:
- name: http
port: 80
targetPort: http
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: demo-web
namespace: claude-k8s-demo
spec:
ingressClassName: nginx
rules:
- host: claude-k8s.local
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: demo-web
port:
name: http
La comprobación crítica es que selector.matchLabels, las labels del template y el selector del Service coincidan. Si no coinciden, el Service no tendrá endpoints o el Deployment no controlará los Pods esperados.
Verificación local
Confirma primero el clúster con kubectl cluster-info y ejecuta:
kubectl apply -f k8s/claude-k8s-demo.yaml
kubectl -n claude-k8s-demo rollout status deployment/demo-web
kubectl -n claude-k8s-demo get pods -l app=demo-web
kubectl -n claude-k8s-demo get service demo-web
kubectl -n claude-k8s-demo port-forward service/demo-web 8080:80
En otra terminal:
curl http://localhost:8080/
Si usas Ingress, revísalo después de probar Pod y Service. Depurar DNS o annotations antes de comprobar el Service suele perder tiempo.
kubectl -n claude-k8s-demo get ingress demo-web
kubectl -n claude-k8s-demo describe ingress demo-web
ConfigMap, Secret y rollback
ConfigMap sirve para configuración no sensible. Secret es para valores sensibles, pero eso no significa que puedas commitearlo: base64 no es cifrado. En producción usa Secret Manager del proveedor cloud, External Secrets, Sealed Secrets, SOPS o el flujo aprobado por tu equipo.
Para práctica local, genera un archivo que no se sube a Git:
kubectl -n claude-k8s-demo create secret generic demo-api-secret \
--from-literal=API_TOKEN='replace-me-locally' \
--dry-run=client \
-o yaml > secret.local.yaml
kubectl apply -f secret.local.yaml
Practica también el fallo y la recuperación:
kubectl -n claude-k8s-demo set image deployment/demo-web nginx=nginx:1.27-alpine
kubectl -n claude-k8s-demo rollout status deployment/demo-web
kubectl -n claude-k8s-demo rollout history deployment/demo-web
kubectl -n claude-k8s-demo set image deployment/demo-web nginx=nginx:not-a-real-tag
kubectl -n claude-k8s-demo rollout status deployment/demo-web --timeout=30s
kubectl -n claude-k8s-demo rollout undo deployment/demo-web
Rollback no siempre revierte ConfigMaps, Secrets, migraciones, DNS o feature flags. Pide a Claude Code que el runbook diga qué se revierte y qué requiere otro procedimiento.
CI y errores comunes
Un gate mínimo de Pull Request reduce fallos básicos:
name: Kubernetes manifest review
on:
pull_request:
paths:
- "k8s/**"
jobs:
dry-run:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: azure/setup-kubectl@v4
with:
version: "v1.30.0"
- run: kubectl apply --dry-run=client -f k8s/
Los fallos más frecuentes son usar latest en producción, confundir readiness con liveness, omitir resources, creer que base64 protege secretos, depurar Ingress antes de Service y publicar la salida de Claude Code sin revisión humana. La defensa es simple: documentos oficiales, CI, práctica local, prompts con límites y review con hallazgos primero.
Ruta de consultoría y resultado probado
Este ejemplo es mínimo. En un proyecto real entran builds de Docker, tags inmutables, TLS, gestión de secretos, observabilidad, RBAC, CI/CD y comunicación de incidentes. Una persona puede empezar con el cheatsheet gratuito. Un equipo que quiera usar Claude Code para cambios de infraestructura debería estandarizar CLAUDE.md, prompts, gates de CI y ejercicios de rollback con formación y consultoría.
El flujo de este artículo está pensado para verificarse con apply, rollout status, listado de Pods, port-forward, curl, imagen inválida, fallo visible y rollout undo. En la práctica, los errores de principiantes fueron selectors no alineados, probe path incorrecto, falta de resources y ejemplos inseguros de Secret. Incluir esas reglas desde el primer prompt evita muchas correcciones posteriores.
PDF gratis: cheatsheet de Claude Code
Introduce tu email y descarga una hoja con comandos, hábitos de revisión y flujos seguros.
Cuidamos tus datos y no enviamos spam.
Sobre el autor
Masa
Ingeniero enfocado en workflows prácticos con Claude Code.
Artículos relacionados
Workflow de Obsidian a CLAUDE.md con Claude Code
Convierte notas de trabajo de Obsidian en notas operativas de CLAUDE.md para no repetir contexto.
Claude Code Revenue CTA Routing: de artículos a PDF, Gumroad y consulta
Un flujo con Claude Code para dirigir lectores a PDF gratis, Gumroad o consulta según intención.
Reglas de handoff para equipos con Claude Code: evidencia, permisos, rollback e ingresos
Formato práctico para entregar trabajo de Claude Code con pruebas, permisos, rollback, PDF gratis, Gumroad y consulta.