Skip to content

Kubernetes Hoja de referencia

Plataforma de orquestación de contenedores para automatizar el despliegue y el escalado.

01

Primeros pasos

Fundamentos de kubectl

kubectl es la CLI de Kubernetes. get lista recursos, create crea nuevos, expose crea services, scale cambia el número de réplicas. describe da información detallada sobre un recurso.

kubernetes
# cluster info
kubectl cluster-info

# list nodes
kubectl get nodes

# list pods (all namespaces)
kubectl get pods --all-namespaces

# create a deployment
kubectl create deployment nginx --image=nginx

# expose deployment as service
kubectl expose deployment nginx --port=80 --type=LoadBalancer

# scale deployment
kubectl scale deployment nginx --replicas=3

# get detailed info
kubectl describe pod <pod-name>

# view logs
kubectl logs <pod-name>

Formato de salida

El flag -o controla la salida. yaml/json muestran el spec completo del recurso. jsonpath y custom-columns extraen campos específicos para scripts. -w observa cambios en vivo. Usa --no-headers en scripts para quitar los nombres de columnas.

kubernetes
# wide format (more columns)
kubectl get pods -o wide

# YAML output
kubectl get pod nginx -o yaml

# JSON output
kubectl get pod nginx -o json

# jsonpath (extract specific fields)
kubectl get pods -o jsonpath='{.items[*].metadata.name}'

# custom columns
kubectl get pods -o custom-columns=NAME:.metadata.name,STATUS:.status.phase

# show labels
kubectl get pods --show-labels

# watch for changes
kubectl get pods -w

Context y configuración

Un context agrupa la dirección del clúster, las credenciales del usuario y el namespace. Los archivos kubeconfig (por defecto ~/.kube/config) guardan esto. Se pueden combinar varios archivos vía la variable de entorno KUBECONFIG para gestionar muchos clústeres.

kubernetes
# view current config
kubectl config view

# list contexts
kubectl config get-contexts

# switch context
kubectl config use-context my-cluster

# set default namespace for current context
kubectl config set-context --current --namespace=dev

# show current context
kubectl config current-context

# KUBECONFIG with multiple files
export KUBECONFIG=~/.kube/config:~/.kube/prod-config

Explain y API Resources

api-resources lista lo que admite el clúster. explain muestra el schema OpenAPI de cualquier recurso — invaluable para escribir YAML sin salir de la terminal. Usa --recursive para volcar la estructura anidada completa.

kubernetes
# list all resource types
kubectl api-resources

# list namespaced vs cluster-scoped
kubectl api-resources --namespaced=true
kubectl api-resources --namespaced=false

# explain a resource's fields
kubectl explain pod
kubectl explain pod.spec.containers
kubectl explain deployment.spec.strategy

# explain with recursion (all nested fields)
kubectl explain pod --recursive

# include description
kubectl explain pod.spec.containers.resources --api-version=apps/v1

Dry run y generar YAML

--dry-run=client -o yaml es la forma estándar de generar manifests a partir de comandos imperativos. --dry-run=server valida contra el apiserver real (admission webhooks, schema) sin persistir. Genial para arrancar YAML declarativo.

kubernetes
# generate YAML without applying
kubectl create deployment nginx --image=nginx --dry-run=client -o yaml

# pipe generated YAML straight to a file
kubectl create deployment nginx --image=nginx --dry-run=client -o yaml > nginx.yaml

# apply the generated manifest
kubectl apply -f nginx.yaml

# dry-run against the server (validates with apiserver)
kubectl apply -f nginx.yaml --dry-run=server

# generate a service from a deployment
kubectl create service clusterip my-svc --tcp=80:80 --dry-run=client -o yaml

Ayuda y autocompletado

Cada comando kubectl admite --help con ejemplos. El autocompletado de shell ahorra una enorme cantidad de tecleo y expone los subcomandos. El alias k=kubectl es casi universal entre los practicantes — combínalo con el autocompletado para la mejor experiencia.

kubernetes
# top-level help
kubectl --help

# subcommand help
kubectl create --help
kubectl explain --help

# generate bash completion
kubectl completion bash > /etc/bash_completion.d/kubectl

# zsh completion
source <(kubectl completion zsh)

# alias k=kubectl with completion
alias k=kubectl
complete -o default -F __start_kubectl k

# shorthand: kubectl -> k
echo 'alias k=kubectl' >> ~/.bashrc
02

Pod

Manifest de Pod

Un Pod es la unidad desplegable más pequeña, contiene uno o más contenedores que comparten red y almacenamiento. Los contenedores de un pod siempre se co-programan en el mismo nodo. Rara vez creas pods directamente — usa un Deployment o un Job en su lugar.

kubernetes
apiVersion: v1
kind: Pod
metadata:
  name: nginx
  labels:
    app: nginx
spec:
  containers:
    - name: nginx
      image: nginx:1.25
      ports:
        - containerPort: 80
      resources:
        requests:
          cpu: 100m
          memory: 128Mi
        limits:
          cpu: 200m
          memory: 256Mi
  restartPolicy: Always

Pod multi-contenedor (sidecar)

Los pods multi-contenedor comparten red (misma IP, mismo espacio de puertos) y volúmenes. Patrones comunes: sidecar (ayudante), adapter (transforma la salida), ambassador (proxy). El volumen compartido emptyDir permite al sidecar leer los logs que escribe el contenedor principal.

kubernetes
apiVersion: v1
kind: Pod
metadata:
  name: web-with-logs
spec:
  containers:
    - name: app
      image: nginx
      volumeMounts:
        - name: shared-logs
          mountPath: /var/log/nginx
    - name: log-shipper
      image: busybox
      command: ["sh", "-c", "tail -f /var/log/nginx/access.log"]
      volumeMounts:
        - name: shared-logs
          mountPath: /var/log/nginx
          readOnly: true
  volumes:
    - name: shared-logs
      emptyDir: {}

Ciclo de vida y fases del Pod

La fase de un pod es de alto nivel (Pending, Running, Succeeded, Failed). Los estados del contenedor (Waiting/Running/Terminated) dan el detalle real — por ejemplo CrashLoopBackOff significa que el contenedor no deja de salir. Revisa el contador de reinicios y los eventos para diagnosticar.

kubernetes
# pod phases: Pending | Running | Succeeded | Failed | Unknown
kubectl get pod nginx

# show status including container states
kubectl get pod nginx -o jsonpath='{.status}'

# container states: Waiting | Running | Terminated
kubectl describe pod nginx

# common Waiting reasons: ImagePullBackOff, CrashLoopBackOff, CreateContainerConfigError
kubectl get pods --field-selector=status.phase=Pending

# restart count reveals crash loops
kubectl get pods -o jsonpath='{.items[*].status.containerStatuses[*].restartCount}'

Estado del Pod y eventos

Los eventos son el registro de auditoría del clúster para un recurso — programación, descargas, errores de descarga, fallos de liveness. Expiran (~1 hora por defecto), así que captúralos mientras depuras. describe agrupa los eventos con el spec del recurso para un triage rápido.

kubernetes
# full describe (includes Events at the bottom)
kubectl describe pod nginx

# list cluster events sorted by time
kubectl get events --sort-by=.lastTimestamp

# events for a specific namespace
kubectl get events -n default

# watch events live
kubectl get events -w

# filter events by type
kubectl get events --field-selector type=Warning

# events for a specific pod
kubectl get events --field-selector involvedObject.name=nginx

Exec y port-forward

exec ejecuta comandos dentro de un contenedor; -it asigna un TTY para shells. port-forward tuneliza un puerto local hacia un pod/service sin exponerlo públicamente — esencial para depurar bases de datos o UIs web desde tu laptop.

kubernetes
# open an interactive shell
kubectl exec -it nginx -- sh

# run a one-off command
kubectl exec nginx -- ls /etc/nginx

# specify container in a multi-container pod
kubectl exec -it web-with-logs -c log-shipper -- sh

# forward a local port to a pod port
kubectl port-forward pod/nginx 8080:80

# forward to a service / deployment
kubectl port-forward svc/nginx 8080:80
kubectl port-forward deployment/nginx 8080:80

# forward to a random local port
kubectl port-forward pod/nginx :80

Delete y force

Eliminar un pod controlado por un Deployment/StatefulSet causa un reemplazo inmediato. --force --grace-period=0 se salta el período de gracia de la señal TERM y puede dejar recursos obsoletos — úsalo con moderación. Los pods atascados en Terminating a menudo necesitan quitar un finalizer.

kubernetes
# delete a pod (controller will recreate it)
kubectl delete pod nginx

# force delete immediately (bypasses graceful shutdown)
kubectl delete pod nginx --grace-period=0 --force

# delete by label
kubectl delete pods -l app=nginx

# delete all pods in a namespace
kubectl delete pods --all -n default

# delete a pod and wait for it to be gone
kubectl delete pod nginx --wait

# delete with a timeout
kubectl delete pod nginx --timeout=30s
03

Deployment

Manifest de Deployment

Un Deployment gestiona ReplicaSets y provee rolling updates y rollbacks declarativos. spec.selector debe coincidir con spec.template.metadata.labels. El template define el spec del pod que se despliega.

kubernetes
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.25
          ports:
            - containerPort: 80

Estrategia de rolling update

RollingUpdate (por defecto) reemplaza los pods gradualmente para cero downtime. maxSurge/maxUnavailable controlan la velocidad del rollout y la disponibilidad. Recreate mata los pods existentes antes de crear los nuevos — se usa cuando la app no puede correr dos versiones a la vez (por ejemplo, escritores de un solo volumen).

kubernetes
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 10
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 25%        # extra pods above replicas during update
      maxUnavailable: 25%  # pods allowed down during update
  # alternative: recreate (kills all, then starts new)
  # strategy:
  #   type: Recreate
  selector:
    matchLabels:
      app: nginx
  template:

Rollback

Cada cambio del pod template crea una revisión de ReplicaSet. undo devuelve el tráfico a un ReplicaSet anterior. pause permite hacer varios arreglos entre incrementos canary. Usa --record (deprecado) o anotaciones para rastrear las causas de los cambios.

kubernetes
# view rollout history
kubectl rollout history deployment/nginx

# see details of a specific revision
kubectl rollout history deployment/nginx --revision=2

# undo to the previous revision
kubectl rollout undo deployment/nginx

# undo to a specific revision
kubectl rollout undo deployment/nginx --to-revision=2

# pause/resume a rollout (for canary pauses)
kubectl rollout pause deployment/nginx
kubectl rollout resume deployment/nginx

# check rollout status
kubectl rollout status deployment/nginx

Scale y HPA

HPA escala las réplicas según CPU/memoria o métricas personalizadas. Requiere metrics-server para CPU/mem. minReplicas y maxReplicas acotan el escalado. La API v2 admite múltiples métricas y comportamientos (estabilización al bajar).

kubernetes
# scale manually
kubectl scale deployment/nginx --replicas=5

# horizontal pod autoscaler (CPU target)
kubectl autoscale deployment nginx --min=2 --max=10 --cpu-percent=80

# list HPA
kubectl get hpa

# HPA manifest (v2 with custom metrics)
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: nginx
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: nginx
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 80

Actualizar imagen y reiniciar

set image dispara un ReplicaSet nuevo y un rolling update. rollout restart es la forma más limpia de traer la última imagen o refrescar la configuración — crea un ReplicaSet nuevo con el mismo spec. edit abre tu $EDITOR para arreglos ad-hoc.

kubernetes
# update container image
kubectl set image deployment/nginx nginx=nginx:1.26

# update from a specific container
kubectl set image deployment/nginx container=nginx:1.26 --record

# trigger a rollout restart (same image, recreate pods)
kubectl rollout restart deployment/nginx

# edit a deployment in editor
kubectl edit deployment/nginx

# patch a single field
kubectl patch deployment/nginx -p '{"spec":{"replicas":5}}'

# apply a manifest change
kubectl apply -f nginx-deployment.yaml

Estado del Deployment

Un Deployment posee ReplicaSets; solo uno está activo (replicas>0). Los ReplicaSets antiguos escalan a cero para el rollback. pod-template-hash etiqueta cada pod con su revisión. Revisa status.conditions para las señales Available, Progressing y ReplicaFailure.

kubernetes
# deployment status
kubectl get deployment nginx

# watch rollout
kubectl rollout status deployment/nginx

# show ReplicaSets owned by the deployment
kubectl get rs -l app=nginx

# show pods across all revisions
kubectl get pods -l app=nginx --show-labels

# pod-template-hash label distinguishes revisions
# kubectl get pods -l app=nginx,pod-template-hash=xxxx

# conditions: Available, Progressing, ReplicaFailure
kubectl get deployment nginx -o jsonpath='{.status.conditions}'
04

Service

Tipos de Service

Un Service provee una IP/DNS estable que balancea carga sobre un conjunto de pods. ClusterIP es el por defecto (solo dentro del clúster). NodePort y LoadBalancer exponen hacia afuera. ExternalName es un alias DNS, no un proxy.

kubernetes
# four service types:
# - ClusterIP (default): reachable inside the cluster
# - NodePort: exposed on each node's IP at a static port
# - LoadBalancer: cloud-provisioned external LB
# - ExternalName: DNS CNAME to an external host

# quick create
kubectl expose deployment nginx --port=80 --type=ClusterIP
kubectl expose deployment nginx --port=80 --type=NodePort
kubectl expose deployment nginx --port=80 --type=LoadBalancer

# external name (no proxying, pure DNS)
kubectl create service externalname my-svc --external-name=db.example.com

Service ClusterIP

ClusterIP da una IP virtual estable y un nombre DNS dentro del clúster. El selector coincide con las etiquetas de los pods; kube-proxy programa iptables/IPVS para balancear sobre los endpoints. Resuelve vía <svc>.<ns>.svc.cluster.local o simplemente <svc>.

kubernetes
apiVersion: v1
kind: Service
metadata:
  name: nginx
spec:
  type: ClusterIP
  selector:
    app: nginx
  ports:
    - name: http
      port: 80          # service port
      targetPort: 80    # container port
      protocol: TCP
# DNS: nginx.default.svc.cluster.local
# short names also work: nginx, nginx.default
# kube-dns / CoreDNS resolves the service VIP

Service NodePort

NodePort abre el mismo puerto estático (30000-32767) en cada nodo. El tráfico hacia cualquier nodo:nodePort llega a un pod (kube-proxy puede redirigir a un pod en otro nodo). Útil cuando no puedes aprovisionar un LB en la nube; combínalo con un LB externo para HA.

kubernetes
apiVersion: v1
kind: Service
metadata:
  name: nginx
spec:
  type: NodePort
  selector:
    app: nginx
  ports:
    - port: 80
      targetPort: 80
      nodePort: 30080   # optional, 30000-32767 range
# reachable at <any-node-ip>:30080
# also still reachable via clusterIP:80

# get assigned nodePort
kubectl get svc nginx -o jsonpath='{.spec.ports[*].nodePort}'

Service LoadBalancer

LoadBalancer pide al proveedor de nube aprovisionar un balanceador externo apuntando a los nodos. externalTrafficPolicy: Local preserva la IP de origen del cliente (sin SNAT) pero omite el balanceo entre nodos. STATUS muestra la IP externa asignada una vez listo.

kubernetes
apiVersion: v1
kind: Service
metadata:
  name: nginx
spec:
  type: LoadBalancer
  selector:
    app: nginx
  ports:
    - port: 80
      targetPort: 80
  # cloud-specific annotations
  # annotations:
  #   service.beta.kubernetes.io/aws-load-balancer-type: nlb
  #   service.beta.kubernetes.io/azure-load-balancer-internal: "true"
  # externalTrafficPolicy: Local preserves client IP
  externalTrafficPolicy: Local
# status.ingress shows the external IP/hostname

Headless Service

Un headless service (clusterIP: None) no tiene VIP — el DNS devuelve directamente las IPs de los pods. Lo requiere el StatefulSet para que cada pod obtenga un nombre DNS estable (pod-0.svc, pod-1.svc). También lo usan clientes que quieren descubrir el conjunto completo de backends por sí mismos.

kubernetes
apiVersion: v1
kind: Service
metadata:
  name: nginx-headless
spec:
  clusterIP: None       # makes it headless
  selector:
    app: nginx
  ports:
    - port: 80
      targetPort: 80
# DNS returns pod IPs directly (not a VIP)
# A records: nginx-headless.default.svc.cluster.local
#   -> 10.1.0.5, 10.1.0.6, 10.1.0.7
# used by StatefulSet for stable pod DNS:
#   <pod-name>.<svc-name>.default.svc.cluster.local

Endpoints y EndpointSlices

Endpoints/EndpointSlices listan las IPs de los pods que realmente reciben tráfico — solo aparecen los pods Ready. Si un service no tiene endpoints, los pods no coinciden con el selector o no están Ready. EndpointSlices (v1) escala mejor para services enormes y es el valor por defecto.

kubernetes
# view endpoints backing a service
kubectl get endpoints nginx

# endpoint slices (newer, more scalable)
kubectl get endpointslices -l kubernetes.io/service-name=nginx

# endpoints track pods that match the selector
# AND pass readiness checks
kubectl describe endpoints nginx

# a service with no ready pods has no endpoints
# - check pod readiness if traffic is refused
# - EndpointSlices are grouped by address type (IPv4/IPv6)

# manually managed endpoints (selector-less service)
05

ConfigMap

Crear ConfigMap

Los ConfigMaps almacenan configuración no sensible como pares clave-valor. --from-literal para valores en línea, --from-file para incrustar archivos completos (el nombre del archivo se vuelve la clave). Útil para desacoplar la configuración de las imágenes sin recompilar.

kubernetes
# from literal values
kubectl create configmap app-config \
  --from-literal=LOG_LEVEL=debug \
  --from-literal=ENABLE_FEATURE=true

# from a file (key = filename, value = contents)
kubectl create configmap app-config --from-file=app.properties

# from a directory (one key per file)
kubectl create configmap app-config --from-file=configs/

# from an env file
kubectl create configmap app-config --from-env-file=app.env

# from a file with a custom key
kubectl create configmap app-config --from-file=custom-key=app.properties

Manifest de ConfigMap

data contiene valores de cadena (cada clave se convierte en una variable de entorno o en un archivo al montarse). Las cadenas multilínea usan block scalars de YAML (|). binaryData acepta base64 para blobs binarios. El límite total de tamaño es 1 MiB por ConfigMap.

kubernetes
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  LOG_LEVEL: "debug"
  ENABLE_FEATURE: "true"
  application.yml: |
    server:
      port: 8080
    logging:
      level: debug
binaryData:
  # base64-encoded binary values
  logo.png: iVBORw0KGgoAAAANSUhEUg...

Consumir como variables de entorno

envFrom inyecta todas las claves del ConfigMap como variables de entorno de una sola vez. env con configMapKeyRef elige claves individuales. optional: true permite que el pod arranque aunque el ConfigMap no exista. Las actualizaciones del ConfigMap NO refrescan las variables de entorno en pods en ejecución.

kubernetes
apiVersion: v1
kind: Pod
metadata:
  name: app
spec:
  containers:
    - name: app
      image: myapp:1.0
      env:
        - name: LOG_LEVEL
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: LOG_LEVEL
      envFrom:
        - configMapRef:
            name: app-config      # injects all keys as env vars
              optional: true      # pod starts even if CM missing

Consumir como volumen

Montar un ConfigMap como volumen proyecta cada clave como archivo. Las actualizaciones del ConfigMap se reflejan eventualmente en los archivos montados (configurado por el período de sincronización del kubelet) — pero las apps deben releerlos. Los montajes subPath fijan una única clave y NO se actualizan.

kubernetes
apiVersion: v1
kind: Pod
metadata:
  name: app
spec:
  containers:
    - name: app
      image: myapp:1.0
      volumeMounts:
        - name: config
          mountPath: /etc/config
          readOnly: true
  volumes:
    - name: config
      configMap:
        name: app-config
        items:                       # optional: pick subset
          - key: application.yml
            path: app.yml            # rename file
        defaultMode: 0644
# each ConfigMap key becomes a file under /etc/config

Actualizar y recargar

Los archivos de ConfigMap montados se refrescan automáticamente (tras la sincronización del kubelet), pero las variables de entorno son inmutables durante la vida del pod — reinicia los pods para recoger los cambios de env. rollout restart es la forma más limpia de propagar actualizaciones de configuración a un Deployment.

kubernetes
# edit the configmap
kubectl edit configmap app-config

# patch a single key
kubectl patch configmap app-config \
  --type merge -p '{"data":{"LOG_LEVEL":"info"}}'

# mounted files update within ~kubelet sync period (default 60s)
# but env vars do NOT update in running pods

# force pods to pick up new config by rolling them
kubectl rollout restart deployment/app

# verify the new value on a pod
kubectl exec app -- printenv LOG_LEVEL

ConfigMap inmutable

Establecer immutable: true congela el ConfigMap — cualquier cambio requiere delete + recreate. Esto reduce drásticamente el tráfico de watch kubelet-apiserver para configuraciones grandes y estables (una gran victoria de escalabilidad). Común en producción para configuraciones de app versionadas junto a la imagen.

kubernetes
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
immutable: true
data:
  LOG_LEVEL: "debug"
# once immutable, the only change allowed is delete + recreate
# benefits: kubelet does not watch it, lower apiserver load
# useful for large, stable configs in production

# make it mutable again
kubectl patch configmap app-config -p '{"immutable":false}'
# (this fails if currently immutable — must delete instead)
06

Secret

Crear Secret

Los Secrets almacenan datos sensibles codificados en base64 (NO cifrados en reposo por defecto — activa el cifrado en reposo para producción). Usa generic/Opaque para datos arbitrarios, docker-registry para descargar imágenes, tls para TLS de Ingress. Nunca subas YAML de Secrets a git.

kubernetes
# generic (opaque) from literals
kubectl create secret generic db-creds \
  --from-literal=username=admin \
  --from-literal=password='S3cur3!'

# from a file (e.g. SSH key, certificate)
kubectl create secret generic ssh-key --from-file=ssh-privatekey=~/.ssh/id_rsa

# docker registry secret (for private image registries)
kubectl create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username=user \
  --docker-password=pass \
  [email protected]

# TLS secret from cert/key files
kubectl create secret tls my-tls \
  --cert=fullchain.pem \
  --key=privkey.pem

Manifest de Secret

los valores de data deben estar codificados en base64 (echo -n 'value' | base64). stringData es una conveniencia que acepta texto plano y se fusiona en data al aplicar. El tipo Opaque es el por defecto; los tipos especializados (kubernetes.io/tls, kubernetes.io/dockerconfigjson) validan las claves.

kubernetes
apiVersion: v1
kind: Secret
metadata:
  name: db-creds
type: Opaque
data:
  username: YWRtaW4=         # base64 of "admin"
  password: UzNjdXIzIQ==     # base64 of "S3cur3!"
# stringData accepts plaintext (auto-encoded on apply)
stringData:
  api-key: "live-key-xyz"
# encode on the command line:
# echo -n 'admin' | base64
# decode:
# echo 'YWRtaW4=' | base64 -d

Usar Secret como variable de entorno

Consumir secrets como variables de entorno es idéntico a los ConfigMaps pero usa secretKeyRef/secretRef. Ten en cuenta que las variables de entorno son visibles vía /proc/1/environ y para cualquier proceso del contenedor — prefiere los montajes de volumen para datos muy sensibles.

kubernetes
apiVersion: v1
kind: Pod
metadata:
  name: app
spec:
  containers:
    - name: app
      image: myapp:1.0
      env:
        - name: DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: db-creds
              key: password
      envFrom:
        - secretRef:
            name: db-creds      # injects all keys
              optional: true

Usar Secret como volumen

Los secrets montados se proyectan como archivos en un volumen tmpfs (memoria) — nunca se escriben al disco del nodo. defaultMode 0400 restringe el acceso. Los secrets montados SÍ se actualizan cuando el Secret cambia (tras la sincronización del kubelet), a diferencia de los secrets por variable de entorno.

kubernetes
apiVersion: v1
kind: Pod
metadata:
  name: app
spec:
  containers:
    - name: app
      image: myapp:1.0
      volumeMounts:
        - name: secrets
          mountPath: /etc/secrets
          readOnly: true
  volumes:
    - name: secrets
      secret:
        secretName: db-creds
        defaultMode: 0400       # restrict permissions
        items:
          - key: password
            path: db-password   # written to /etc/secrets/db-password
# memory-backed tmpfs, never written to disk on the node

ImagePullSecret

imagePullSecrets autentica ante registros privados al descargar imágenes. Adjuntarlo a un ServiceAccount lo aplica a cada pod que use esa SA — el patrón preferido. El tipo de secret docker-registry produce el payload .dockerconfigjson correcto automáticamente.

kubernetes
# attach to a pod
apiVersion: v1
kind: Pod
metadata:
  name: private-app
spec:
  imagePullSecrets:
    - name: regcred
  containers:
    - name: app
      image: registry.example.com/myapp:1.0

# attach to a service account (auto-applied to all pods using it)
kubectl patch serviceaccount default \
  -p '{"imagePullSecrets":[{"name":"regcred"}]}'

# verify
kubectl get sa default -o jsonpath='{.imagePullSecrets}'

Tipos de Secret

Los tipos de secret especializados habilitan validación e integración: tls para Ingress, dockerconfigjson para descargar imágenes, service-account-token montado automáticamente en los pods. Usar el tipo correcto asegura que las claves sean validadas y consumidas por los controladores adecuados.

kubernetes
# Opaque (default) — arbitrary key-value
type: Opaque

# kubernetes.io/service-account-token — auto for SAs
type: kubernetes.io/service-account-token

# kubernetes.io/dockerconfigjson — registry auth
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: <base64>

# kubernetes.io/tls — for Ingress TLS
type: kubernetes.io/tls
data:
  tls.crt: <base64>
  tls.key: <base64>

# kubernetes.io/basic-auth
type: kubernetes.io/basic-auth
stringData:
  username: admin
  password: pass
07

Namespace

Crear Namespace

Los namespaces particionan un clúster para varios equipos o entornos (dev/stage/prod). Los nombres de los recursos deben ser únicos dentro de un namespace. Algunos recursos (Nodes, PVs, StorageClasses) tienen ámbito de clúster y no están en namespaces.

kubernetes
# imperative
kubectl create namespace dev

# declarative
apiVersion: v1
kind: Namespace
metadata:
  name: dev
  labels:
    environment: development
    team: platform

# apply
kubectl apply -f namespace.yaml

# list namespaces
kubectl get namespaces

# set default namespace for current context
kubectl config set-context --current --namespace=dev

ResourceQuota

ResourceQuota limita el uso agregado de recursos en un namespace — solicitudes/límites totales de CPU/memoria, conteo de objetos (pods, PVCs, services, deployments). Esencial en clústeres multi-tenant para evitar que un equipo pegue a los demás. Los pods sin solicitudes explícitas se rechazan una vez fijada la cuota.

kubernetes
apiVersion: v1
kind: ResourceQuota
metadata:
  name: compute-quota
  namespace: dev
spec:
  hard:
    requests.cpu: "10"
    requests.memory: 20Gi
    limits.cpu: "20"
    limits.memory: 40Gi
    pods: "50"
    services.loadbalancers: "2"
    persistentvolumeclaims: "10"
    count/deployments.apps: "5"
# limits total aggregate resource use in the namespace

LimitRange

LimitRange fija valores por defecto y cotas por recurso: requests/limits por defecto para pods que no los especifican, más min/max para restringir valores desorbitados. Va de la mano con ResourceQuota — sin requests por defecto, la cuota rechazaría cada pod que olvide definirlos.

kubernetes
apiVersion: v1
kind: LimitRange
metadata:
  name: default-limits
  namespace: dev
spec:
  limits:
    - type: Container
      default:               # default limits (if unset)
        cpu: 500m
        memory: 512Mi
      defaultRequest:        # default requests (if unset)
        cpu: 100m
        memory: 128Mi
      max:                   # max allowed limits
        cpu: "2"
        memory: 2Gi
      min:                   # min allowed requests
        cpu: 50m
        memory: 64Mi
    - type: PersistentVolumeClaim
      max:
        storage: 100Gi
      min:
        storage: 1Gi

Eliminar Namespace y finalizers

Eliminar un namespace arrastra en cascada cada uno de sus recursos. Un namespace atascado en Terminating normalmente tiene un finalizer que no puede completarse — un APIService no disponible (por ejemplo metrics-server) o un CRD cuyo controlador desapareció. Quitar el finalizer fuerza la finalización pero puede fugar recursos externos.

kubernetes
# delete a namespace (cascades all resources in it)
kubectl delete namespace dev

# if stuck in Terminating, inspect finalizers
kubectl get namespace dev -o yaml

# remove finalizer to force completion (DANGEROUS)
kubectl patch namespace dev -p '{"metadata":{"finalizers":null}}'

# resources that block deletion:
# - APIService unavailable (metrics-server removed)
# - custom resources whose CRD is gone
# - PVCs with attached PVs

# check what's still in the namespace
kubectl api-resources --verbs=list --namespaced -o name \
  | xargs -n 1 kubectl get -n dev --ignore-not-found

Namespaces por defecto

kube-system corre el plano de control y los add-ons (DNS, kube-proxy, CNI). kube-public guarda datos de bootstrap legibles por usuarios no autenticados. kube-node-lease almacena los heartbeats de los nodos como objetos Lease por rendimiento. default es donde caen tus workloads si no especificas un namespace.

kubernetes
# built-in namespaces
kubectl get namespaces
# NAME              STATUS   AGE
# default           Active   30d   <- user workloads land here
# kube-system       Active   30d   <- control plane / addons
# kube-public       Active   30d   <- publicly readable (bootstrap)
# kube-node-lease   Active   30d   <- node heartbeats (leases)

# kube-system holds:
# - kube-dns / CoreDNS
# - kube-proxy
# - metrics-server
# - CNI, CSI, cloud provider controllers

# kube-public is readable by all (used for cluster info discovery)

Namespace-scoped vs Cluster-scoped

La mayoría de los recursos de workload están en namespaces; la infraestructura (nodes, PVs, StorageClasses, ClusterRoles) tiene ámbito de clúster. Un Service solo puede apuntar a pods de su propio namespace. -A es la abreviatura de --all-namespaces — esencial para visibilidad a nivel de clúster.

kubernetes
# which resources are namespaced?
kubectl api-resources --namespaced=true
kubectl api-resources --namespaced=false

# namespaced: pods, services, deployments, configmaps, secrets
# cluster-scoped: nodes, namespaces, PVs, StorageClasses, ClusterRoles

# access across namespaces:
# - a Service selector only matches pods in the SAME namespace
# - cross-namespace refs require special controllers (e.g. external-dns)

# list resources across all namespaces
kubectl get pods --all-namespaces
kubectl get pods -A   # shorthand
08

Labels y Selectors

Sintaxis de labels

Las labels son pares clave-valor que identifican y agrupan recursos. Las claves pueden tener un prefijo opcional (un subdominio DNS, por ejemplo app.kubernetes.io/). Las labels sirven para consultar/filtrar, a diferencia de las annotations, que son para metadatos arbitrarios no identificativos.

kubernetes
# labels are key=value pairs
# key: prefix (optional DNS subdomain) + name
# value: string, up to 63 chars

metadata:
  labels:
    app: nginx
    tier: frontend
    env: prod
    app.kubernetes.io/name: nginx
    app.kubernetes.io/version: "1.25"

# view labels
kubectl get pods --show-labels

# add/overwrite a label
kubectl label pod nginx env=prod
kubectl label pod nginx env=staging --overwrite

# remove a label (trailing dash)
kubectl label pod nginx env-

Selectors de igualdad y de conjunto

Dos sabores de selector: basados en igualdad (=, ==, !=) y basados en conjuntos (in, notin, exists, !exists). Varias condiciones separadas por comas se combinan con AND. Los Services y Deployments usan selectors de igualdad en YAML; kubectl -l admite ambos.

kubernetes
# equality-based: = == !=
kubectl get pods -l app=nginx
kubectl get pods -l env!=dev
kubectl get pods -l 'app=nginx,env=prod'   # AND of conditions

# set-based: in, notin, exists
kubectl get pods -l 'env in (prod,staging)'
kubectl get pods -l 'env notin (dev)'
kubectl get pods -l 'tier'                 # key exists
kubectl get pods -l '!canary'              # key does not exist

# combine equality and set-based
kubectl get pods -l 'app=nginx,env in (prod,staging)'

Etiquetar recursos

label muta los metadatos identificativos — úsalo para aquello sobre lo que los selectors deban coincidir. annotate es para metadatos no identificativos (owner, ticket, descripción, pistas de herramientas). Los nodos suelen etiquetarse con pistas de topología o hardware para dirigir la programación.

kubernetes
# label a pod
kubectl label pod nginx app=nginx tier=web

# label all pods matching a selector
kubectl label pods -l app=oldapp app=newapp --overwrite

# label a node (for scheduling hints)
kubectl label node node-1 disktype=ssd

# remove a node label
kubectl label node node-1 disktype-

# list nodes by label
kubectl get nodes -l disktype=ssd

# annotate (non-identifying metadata)
kubectl annotate pod nginx owner=alice
kubectl annotate pod nginx description="web server"

Selectors en manifests

En YAML, los selectors usan matchLabels (igualdad) y matchExpressions (de conjunto con In/NotIn/Exists/DoesNotExist). Para Deployments el selector es inmutable tras la creación — y las labels del pod template deben coincidir con él. Los Services solo admiten matchLabels.

kubernetes
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  selector:
    matchLabels:            # equality-based
      app: nginx
    matchExpressions:       # set-based (optional)
      - key: env
        operator: In
        values: [prod, staging]
      - key: tier
        operator: Exists
  template:
    metadata:
      labels:
        app: nginx          # MUST match selector
        env: prod
        tier: web

Annotations

Las annotations guardan metadatos no identificativos que usan las herramientas — kubectl apply guarda la configuración last-applied, cert-manager lee pistas de issuer, Prometheus lee la configuración de scrape, los controladores almacenan el estado del rollout. A diferencia de las labels, los valores de las annotations pueden ser blobs JSON grandes.

kubernetes
metadata:
  annotations:
    kubernetes.io/change-cause: "bump nginx to 1.26"
    prometheus.io/scrape: "true"
    prometheus.io/port: "9090"
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"apps/v1",...}
    cert-manager.io/cluster-issuer: "letsencrypt-prod"

# view annotations
kubectl get pod nginx -o jsonpath='{.metadata.annotations}'

# annotate
kubectl annotate pod nginx owner=team-platform

# remove an annotation (trailing dash)
kubectl annotate pod nginx owner-

Labels recomendadas

Las labels app.kubernetes.io/* son un vocabulario compartido para que las herramientas (Helm, operators, dashboards) puedan agrupar cada recurso de una aplicación. name+instance identifican unívocamente un release; component/part-of describen la jerarquía; managed-by/created-by rastrean la propiedad.

kubernetes
# shared recommended labels (app.kubernetes.io/*)
metadata:
  labels:
    app.kubernetes.io/name: nginx
    app.kubernetes.io/instance: nginx-prod
    app.kubernetes.io/version: "1.25"
    app.kubernetes.io/component: web
    app.kubernetes.io/part-of: storefront
    app.kubernetes.io/managed-by: helm
    app.kubernetes.io/created-by: controller-manager

# Helm applies these automatically; kubectl doesn't.
# They unify how tooling identifies an application's resources
# across Deployments, Services, Ingresses, ConfigMaps, etc.
09

ReplicaSet

Manifest de ReplicaSet

Un ReplicaSet mantiene un conjunto estable de pods réplica que coinciden con un selector — recrea los pods cuando se eliminan o fallan. Casi siempre usarás un Deployment en su lugar, que envuelve un ReplicaSet y agrega rolling updates y rollbacks.

kubernetes
apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.25
# kubectl get rs
# kubectl describe rs nginx

Cómo funciona el ReplicaSet

El controlador de ReplicaSet reconcilia el número deseado vs el real de pods usando el selector. Cada pod recibe un ownerReference apuntando al RS — por eso kubectl get pod muestra 'Owned by ReplicaSet/nginx'. Escalar solo cambia el número deseado.

kubernetes
# the controller loop:
# 1. count pods matching selector
# 2. if fewer than replicas -> create from template
# 3. if more than replicas -> delete excess (arbitrary order)

# owned-by reference on each pod
kubectl get pod -l app=nginx -o jsonpath='{.items[*].metadata.ownerReferences}'

# if you delete a pod, the RS creates a new one immediately
kubectl delete pod <pod-name>
kubectl get pods -l app=nginx

# scale by editing replicas
kubectl scale rs nginx --replicas=5

ReplicaSet vs ReplicationController

ReplicationController (la primitiva v1 original) solo admite selectors de igualdad y está deprecado. ReplicaSet (apps/v1) agrega selectors de conjunto. En la práctica, usa Deployment — gestiona los ReplicaSets por ti y provee rolling updates/rollbacks.

kubernetes
# ReplicationController (v1, legacy): equality-only selectors
# ReplicaSet (apps/v1, modern): set-based selectors (in, notin, exists)

# ReplicationController is deprecated; do not use.
apiVersion: v1
kind: ReplicationController      # legacy
# ...
# ReplicaSet is the successor:
apiVersion: apps/v1
kind: ReplicaSet                 # modern
# ...
# Deployment wraps ReplicaSet and is the recommended primitive:
apiVersion: apps/v1
kind: Deployment                 # use this in practice

Escalado manual

kubectl scale cambia el campo replicas. Si un HPA apunta al mismo recurso, sobrescribirá el escalado manual en la siguiente reconciliación. Prefiere kubectl scale para cosas puntuales y HPA para workloads elásticos continuos.

kubernetes
# scale a replicaset directly
kubectl scale rs nginx --replicas=5

# scale via patch
kubectl patch rs nginx -p '{"spec":{"replicas":5}}'

# scale multiple resources at once
kubectl scale deployment nginx deployment web --replicas=3

# scale by referencing a file
kubectl scale --replicas=5 -f nginx.yaml

# the autoscaler (HPA) will override manual scaling
# if it targets the same resource

Cambios de template y adopción

A diferencia de un Deployment, un ReplicaSet aislado no despliega cambios del pod template — solo los pods recién creados (tras un delete/escalado) reciben el nuevo spec. Un ReplicaSet adoptará cualquier pod huérfano que coincida con su selector, lo que puede causar comportamientos sorprendentes.

kubernetes
# changing the pod template does NOT update existing pods
# (unlike a Deployment, a bare ReplicaSet won't roll out)
kubectl edit rs nginx   # change image -> new pods use it, old ones don't

# delete old pods to force them onto the new template
kubectl delete pods -l app=nginx

# a ReplicaSet will ADOPT existing pods that match its selector
# even pods created independently — useful (and dangerous)

# orphaned pods (no owner) matching the selector are taken over
kubectl get pods -l app=nginx --show-kind

Quitar pods de un ReplicaSet

Para quitar un pod sin que el ReplicaSet lo recree, o bien escala el RS a 0 primero, o quítale los ownerReferences al pod para que el RS ya no lo posea. Útil para depurar una instancia específica o extraer logs antes de la limpieza.

kubernetes
# detaching a pod from its ReplicaSet (so it isn't replaced)
kubectl patch pod <pod-name> \
  -p '{"metadata":{"ownerReferences":[]}}'

# now deleting this pod won't trigger a replacement,
# because the RS no longer owns it

# or scale the RS to 0 first, then delete
kubectl scale rs nginx --replicas=0
kubectl delete pod <pod-name>

# useful for debugging a specific failing pod instance
# without the RS immediately recreating it
10

StatefulSet

Manifest de StatefulSet

StatefulSet da a los pods una identidad estable (nombre, hostname, almacenamiento) y despliegue/escalado ordenados. Requiere un serviceName headless. volumeClaimTemplates crea un PVC dedicado por pod — así, aunque pod-0 se reprograme, reengancha el mismo volumen.

kubernetes
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: mysql
spec:
  serviceName: mysql          # required: headless service
  replicas: 3
  selector:
    matchLabels:
      app: mysql
  template:
    metadata:
      labels:
        app: mysql
    spec:
      containers:
        - name: mysql
          image: mysql:8
          ports:
            - containerPort: 3306
          volumeMounts:
            - name: data
              mountPath: /var/lib/mysql
  volumeClaimTemplates:       # one PVC per pod
    - metadata:
        name: data
      spec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 10Gi

Identidad estable

Cada pod obtiene un nombre ordinal estable (mysql-0, mysql-1, …) y un nombre DNS estable vía el servicio headless. Cuando un nodo falla, pod-0 se reprograma en otro lugar pero conserva su nombre y reengancha su volumen — crítico para bases de datos en clúster que dependen de una membresía estable.

kubernetes
# pods are named <statefulset-name>-<ordinal>
# mysql-0, mysql-1, mysql-2
kubectl get pods -l app=mysql

# each pod has stable DNS (via the headless service):
#   mysql-0.mysql.default.svc.cluster.local
#   mysql-1.mysql.default.svc.cluster.local

# stable hostname inside the pod:
kubectl exec mysql-0 -- hostname
# -> mysql-0

# ordinal index also exposed:
kubectl exec mysql-0 -- sh -c 'echo $HOSTNAME'
# -> mysql-0

# pod identity persists across reschedules

Almacenamiento estable

volumeClaimTemplates genera un PVC por pod con nombre predecible (data-mysql-0, …). Los PVCs sobreviven a la eliminación del pod y del StatefulSet — esto evita la pérdida de datos pero implica que debes eliminar los PVCs explícitamente para recuperar el almacenamiento. El mismo volumen siempre se reengancha al mismo pod ordinal.

kubernetes
# one PVC per pod, named <volumeClaimTemplate-name>-<pod-name>
kubectl get pvc
# NAME        STATUS   VOLUME       CAPACITY   ...
# data-mysql-0   Bound   pvc-aaa      10Gi
# data-mysql-1   Bound   pvc-bbb      10Gi
# data-mysql-2   Bound   pvc-ccc      10Gi

# when pod-0 is rescheduled, it re-binds data-mysql-0
# deleting the StatefulSet does NOT delete PVCs by default
# (protects from accidental data loss)

# to actually delete the data:
kubectl delete pvc data-mysql-0 data-mysql-1 data-mysql-2

Despliegue ordenado y gestión de pods

OrderedReady (por defecto) crea los pods estrictamente en orden 0→1→2 y los elimina en reversa — lo exigen los sistemas que necesitan un primario que arranque antes de las réplicas. Parallel crea/elimina el conjunto de pods simultáneamente — más rápido para stores simétricos fragmentados (Cassandra, Elasticsearch).

kubernetes
spec:
  podManagementPolicy: OrderedReady   # default: strict order
  # podManagementPolicy: Parallel      # create/delete all at once

  replicas: 3
  # OrderedReady: create pod-0, then pod-1, then pod-2 (each waits for Ready)
  # deletion is reverse: pod-2, pod-1, pod-0

  # Parallel: all pods created/deleted simultaneously
  # identity and storage remain stable either way

# check policy
kubectl get statefulset mysql -o jsonpath='{.spec.podManagementPolicy}'

# parallel is great for sharded stores that don't need bootstrap order

Rolling updates

Los rolling updates del StatefulSet van en orden ordinal inverso (de N-1 a 0). partition permite hacer canary primero en los pods de ordinal más alto. OnDelete pausa las actualizaciones hasta que elimines manualmente un pod — útil para migraciones controladas. Los rollouts son más lentos que los de Deployments debido al orden.

kubernetes
spec:
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      partition: 2          # only pods with ordinal >= 2 update
      maxUnavailable: 1     # (default 1) allowed down
  # type: OnDelete  -> only update when pod is manually deleted

# partition enables canaries: set partition=N to update
# only the top N pods; lower to 0 to roll out to all.

kubectl rollout status statefulset/mysql
# waits for all pods to be updated

# StatefulSets also support rollout history/undo,
# but only when the change is in the pod template

Asociación con el headless service

El headless service (clusterIP: None) referenciado por spec.serviceName es lo que hace funcionar el DNS estable por pod. Sin él, el StatefulSet no creará pods. Los clientes resuelven el nombre del servicio para round-robin, o pod-0.svc para fijar el primario. No olvides crear el Service.

kubernetes
apiVersion: v1
kind: Service
metadata:
  name: mysql
spec:
  clusterIP: None         # headless
  selector:
    app: mysql
  ports:
    - port: 3306
---
# StatefulSet references this service via spec.serviceName
# this gives each pod a stable DNS:
#   mysql-0.mysql.default.svc.cluster.local

# clients can:
# - resolve mysql -> any pod IP (load-balanced by DNS round-robin)
# - resolve mysql-0.mysql -> pod-0's IP (pin to a specific replica)

# required: serviceName MUST match the headless service name
11

DaemonSet

Manifest de DaemonSet

Un DaemonSet corre exactamente un pod por nodo (que coincida con sus restricciones de programación). Perfecto para agentes a nivel de nodo: recolectores de logs, monitoreo, almacenamiento, CNI, ingress controllers. Los nodos nuevos reciben automáticamente un pod; de los nodos eliminados, sus pods se recogen.

kubernetes
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: log-agent
  namespace: kube-system
  labels:
    app: log-agent
spec:
  selector:
    matchLabels:
      app: log-agent
  template:
    metadata:
      labels:
        app: log-agent
    spec:
      containers:
        - name: agent
          image: fluent-bit:2.2
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
      # one pod per (matching) node automatically

Programación en nodos

nodeSelector es la restricción más simple (cada key=value debe coincidir). nodeAffinity agrega operadores In/NotIn/Exists y reglas preferred/required. Los DaemonSets las respetan como cualquier pod — combinados con tolerations puedes correr agentes también en nodos de control-plane contaminados.

kubernetes
spec:
  template:
    spec:
      nodeSelector:                # simplest: must match all
        disktype: ssd

      # more flexible affinity
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
              - matchExpressions:
                  - key: kubernetes.io/os
                    operator: In
                    values: [linux]

      # only run on nodes labeled role=logging
      nodeSelector:
        role: logging

      tolerations:                 # tolerate tainted nodes
        - key: node-role.kubernetes.io/control-plane
          operator: Exists

Estrategia de actualización

RollingUpdate (por defecto) actualiza los pods nodo por nodo, acotado por maxUnavailable (puede ser un número o %). OnDelete pausa las actualizaciones hasta que elimines manualmente cada pod — útil cuando se requiere control nodo por nodo. maxSurge vale 0 por defecto (los DaemonSets rara vez quieren pods extra).

kubernetes
spec:
  updateStrategy:
    type: RollingUpdate           # default
    rollingUpdate:
      maxUnavailable: 1           # how many nodes update at once
      maxSurge: 0                 # (default 0) no extra pods
  # type: OnDelete               # only update when old pod is deleted

# trigger an update (e.g. new image)
kubectl set image daemonset/log-agent agent=fluent-bit:2.3

# watch rollout
kubectl rollout status daemonset/log-agent -n kube-system

# rollout restart (recreate pods on every node)
kubectl rollout restart daemonset/log-agent -n kube-system

Taints y tolerations

Los taints repelen pods; las tolerations permiten que pods específicos ignoren un taint. Los nodos de control-plane llevan el taint NoSchedule para que los workloads de usuario no aterricen ahí — los agentes a nivel de nodo lo toleran para correr en todas partes. NoExecute además expulsa los pods que no toleran y ya están corriendo.

kubernetes
# inspect a node's taints
kubectl describe node node-1 | grep Taints
# Taints: node-role.kubernetes.io/control-plane:NoSchedule

# tolerate control-plane so the agent runs there too
spec:
  template:
    spec:
      tolerations:
        - key: node-role.kubernetes.io/control-plane
          operator: Exists
          effect: NoSchedule
        - key: node.kubernetes.io/disk-pressure
          operator: Exists
          effect: NoExecute

# taint effects: NoSchedule | NoExecute | PreferNoSchedule

Casos de uso de DaemonSet

Los DaemonSets son la forma estándar de desplegar infraestructura a nivel de nodo. Frecuentemente necesitan acceso privilegiado (hostNetwork, hostPID, hostPath) para hacer su trabajo — concédelos deliberadamente y solo a imágenes confiables. Nunca uses un DaemonSet para workloads de app que deban escalar horizontalmente.

kubernetes
# classic DaemonSet workloads (node-level agents):
# - log collection:        fluent-bit, filebeat, promtail
# - monitoring:            node-exporter, datadog-agent
# - networking:            kube-proxy, CNI plugins, ingress controllers
# - storage:               CSI node plugins, Rook/Ceph
# - security:              Falco, Tetragon, runtime security
# - GPU/FPGA drivers:      nvidia-device-plugin

# storage / device plugins often need:
spec:
  template:
    spec:
      hostNetwork: true        # use node network namespace
      hostPID: true            # see node processes
      hostPath:                # mount node paths
        - path: /var/log
        - path: /var/lib/docker/containers

Estado del DaemonSet

DESIRED iguala el número de nodos que cumplen las restricciones de programación; CURRENT/READY muestran cuántos pods existen y pasan la readiness. -o wide es la forma más fácil de ver en qué nodo aterrizó cada pod. Los DaemonSets admiten historial/undo de rollout igual que los Deployments.

kubernetes
# desired = number of matching nodes
kubectl get daemonset log-agent -n kube-system
# NAME         DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE
# log-agent    5         5         5       5            5

# show which nodes a DaemonSet pod landed on
kubectl get pods -n kube-system -l app=log-agent -o wide

# rollout history
kubectl rollout history daemonset/log-agent -n kube-system

# rollback
kubectl rollout undo daemonset/log-agent -n kube-system

# check a per-node pod's logs
kubectl logs -n kube-system log-agent-abcde
12

Job y CronJob

Manifest de Job

Un Job corre pods hasta que un número especificado de ellos se complete con éxito (completions). restartPolicy debe ser Never u OnFailure (no Always — eso es para workloads de larga vida). backoffLimit acota los reintentos; activeDeadlineSeconds acota el tiempo total de ejecución.

kubernetes
apiVersion: batch/v1
kind: Job
metadata:
  name: pi
spec:
  completions: 1              # how many successful pods needed
  parallelism: 1              # how many run concurrently
  backoffLimit: 6             # retries before marking Failed
  activeDeadlineSeconds: 600  # hard timeout
  template:
    spec:
      restartPolicy: Never    # OnFailure | Never
      containers:
        - name: pi
          image: perl
          command: ["perl", "-Mbignum=bpi", "-wle", "print bpi(2000)"]
# kubectl get jobs
# kubectl logs job/pi

Completions y parallelism del Job

completions = cuántos pods exitosos satisfacen el Job; parallelism = cuántos corren concurrentemente. Los Indexed Jobs asignan a cada pod un ordinal (variable de entorno JOB_COMPLETION_INDEX) — genial para procesamiento por lotes fragmentado donde cada pod posee una porción. NonIndexed (por defecto) solo necesita N éxitos de cualquier parte.

kubernetes
spec:
  completions: 5         # 5 successful pods total
  parallelism: 2         # 2 pods run at a time
  backoffLimit: 4
  # default completionMode: NonIndexed (any 5 successes)
  completionMode: Indexed
  # Indexed: pods get 0..N-1 in JOB_COMPLETION_INDEX env,
  # useful for sharded work (each pod handles one shard)

  template:
    spec:
      restartPolicy: OnFailure
      containers:
        - name: worker
          image: worker:1.0

# set via kubectl
kubectl create job pi --image=perl -- perl -Mbignum=bpi -wle "print bpi(2000)"

Backoff y timeouts del Job

backoffLimit reintenta pods fallidos (backoff exponencial). activeDeadlineSeconds es el techo duro — si se alcanza, el Job se marca Failed aunque queden reintentos. ttlSecondsAfterFinished auto-limpia los Jobs completados. podFailurePolicy (1.31+) permite fallar rápido ante ciertos códigos de salida o ignorar expulsiones voluntarias.

kubernetes
spec:
  backoffLimit: 6            # default 6, retries on failure
  activeDeadlineSeconds: 3600  # hard wall, even if retries remain
  ttlSecondsAfterFinished: 86400  # auto-delete Job 1 day after done
  startingDeadlineSeconds: 300  # (CronJob only) miss window

  # pod failure handling (v1.31+):
  podFailurePolicy:
    rules:
      - action: FailJob
        onExitCodes:
          operator: In
          values: [42]      # exit 42 -> don't retry, fail fast
      - action: Count
        onPodConditions:
          - type: DisruptionTarget   # don't count voluntary evictions

  template:

Manifest de CronJob

Un CronJob crea Jobs según un cronograma cron (5 campos: minuto hora día mes día-semana). concurrencyPolicy controla las ejecuciones superpuestas: Forbid salta una nueva ejecución si la anterior sigue en marcha; Replace mata la vieja y arranca la nueva. timeZone (1.27+) elimina la necesidad de aritmética UTC.

kubernetes
apiVersion: batch/v1
kind: CronJob
metadata:
  name: backup
spec:
  schedule: "0 2 * * *"          # 5-field cron: 02:00 daily
  timeZone: "Asia/Shanghai"
  concurrencyPolicy: Forbid      # Allow | Forbid | Replace
  successfulJobsHistoryLimit: 3
  failedJobsHistoryLimit: 1
  startingDeadlineSeconds: 200
  jobTemplate:
    spec:
      backoffLimit: 2
      template:
        spec:
          restartPolicy: OnFailure
          containers:
            - name: backup
              image: backup:1.0
# kubectl get cronjob
# kubectl get jobs

Suspend e historial del CronJob

suspend: true pausa un CronJob sin eliminarlo — práctico durante incidentes. Los límites de historial mantienen la lista de Jobs manejable (por defecto 3 éxitos / 1 fallo). kubectl create job --from=cronjob/X ejecuta la plantilla de inmediato, perfecto para disparadores manuales o rellenar ejecuciones perdidas.

kubernetes
spec:
  schedule: "*/5 * * * *"
  suspend: true                # pause without deleting the CronJob
  successfulJobsHistoryLimit: 3   # default 3
  failedJobsHistoryLimit: 1       # default 1

# toggle suspend
kubectl patch cronjob backup -p '{"spec":{"suspend":true}}'
kubectl patch cronjob backup -p '{"spec":{"suspend":false}}'

# trigger a one-off run immediately
kubectl create job --from=cronjob/backup manual-backup

# clean up old jobs manually
kubectl delete jobs -l job-name=backup

Cronograma y casos límite del CronJob

Cron estándar de 5 campos. Cuando se restringen a la vez el día-del-mes y el día-de-la-semana, cron dispara con CUALQUIERA de las dos coincidencias (semántica OR) — una trampa clásica. Si se pierde la hora programada de un CronJob más allá de startingDeadlineSeconds, esa ejecución se salta en lugar de recuperarse.

kubernetes
# cron syntax (5 fields):
# ┌───────────── minute (0-59)
# │ ┌───────────── hour (0-23)
# │ │ ┌───────────── day of month (1-31)
# │ │ │ ┌───────────── month (1-12)
# │ │ │ │ ┌───────────── day of week (0-6, Sun=0)
# "*/5 * * * *"      every 5 minutes
# "0 2 * * *"        daily at 02:00
# "0 0 * * 0"        weekly Sunday midnight
# "0 0 1 * *"        monthly on the 1st
# "30 3-5 * * *"     03:30, 04:30, 05:30

# gotchas:
# - day-of-month AND day-of-week both set => OR (not AND)
# - if startingDeadlineSeconds is missed, the run is skipped
# - control-plane restart can skip a tick if the schedule is missed
# - cron interprets literal fields; prefer timeZone over UTC math
13

Ingress

Manifest de Ingress

Ingress expone rutas HTTP/HTTPS desde fuera del clúster hacia los Services, gestionado por un Ingress controller (nginx, traefik, ALB, …). ingressClassName elige qué controlador lo maneja. Cada regla mapea un host + path a un backend service+puerto.

kubernetes
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port:
                  number: 80
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api
                port:
                  number: 8080

Ingress con TLS

Las entradas tls vinculan un secret TLS (tipo kubernetes.io/tls, con tls.crt + tls.key) a uno o más hosts. El Ingress controller termina el TLS y proxea HTTP plano al backend. cert-manager puede emitir y rotar automáticamente certificados de Let's Encrypt según la anotación cluster-issuer.

kubernetes
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web-tls
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - app.example.com
        - www.example.com
      secretName: web-tls-secret   # kubernetes.io/tls secret
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port:
                  number: 80

# auto-issue certs with cert-manager:
# annotations:
#   cert-manager.io/cluster-issuer: letsencrypt-prod

Reglas de Ingress y backend por defecto

defaultBackend maneja el tráfico que no coincide con ninguna regla (sin host o con path no coincidente). Múltiples reglas permiten a un solo Ingress enrutar muchos hosts virtuales. Cada regla puede tener varios backends de path — un solo Ingress puede encabezar toda la topología de enrutamiento de una aplicación.

kubernetes
spec:
  ingressClassName: nginx
  defaultBackend:                # catch-all for unmatched traffic
    service:
      name: default-svc
      port:
        number: 80
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service: { name: api, port: { number: 8080 } }
    - host: blog.example.com     # different host -> different svc
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service: { name: blog, port: { number: 80 } }

IngressClass

Un IngressClass declara un controlador (por ejemplo k8s.io/ingress-nginx). Los Ingress lo referencian vía spec.ingressClassName para que varios controladores puedan coexistir. Exactamente una clase puede marcarse por defecto con la anotación is-default-class — los Ingress nuevos sin clase explícita la usan.

kubernetes
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nginx
  annotations:
    ingressclass.kubernetes.io/is-default-class: "true"
spec:
  controller: k8s.io/ingress-nginx

# an Ingress picks a class via spec.ingressClassName
# (replaces the deprecated kubernetes.io/ingress.class annotation)

# multiple IngressClasses in one cluster:
# - nginx    (community ingress-nginx)
# - traefik  (Traefik controller)
# - alb      (AWS ALB)
# only one IngressClass can be marked default

Tipos de path

Exact coincide con el path literalmente; Prefix coincide con segmentos de path completos (/api coincide con /api y /api/foo pero no con /apix). ImplementationSpecific delega en el controlador — por ejemplo la regex de nginx. Prefiere siempre Prefix o Exact por un comportamiento portable; ImplementationSpecific te ata a un controlador.

kubernetes
spec:
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /api/v1
            pathType: Exact        # only /api/v1 (exact match)
            backend: ...
          - path: /api
            pathType: Prefix       # /api, /api/, /api/x (prefix match)
            backend: ...
          - path: /old
            pathType: ImplementationSpecific  # controller decides
            backend: ...

# Prefix matches path segments, not raw string prefix:
# /api   matches /api, /api/, /api/x  but NOT /apix
# Exact  matches the path verbatim
# ImplementationSpecific defers to the controller

Annotations (Nginx Controller)

Las anotaciones específicas del controlador configuran comportamientos más allá del spec estándar de Ingress. ingress-nginx tiene decenas: rewrite-target, ssl-redirect, body-size, timeouts, CORS, basic auth, configuration snippets. Son específicas del controlador — portarlas a otro controlador implica reescribirlas.

kubernetes
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
  annotations:
    kubernetes.io/ingress.class: nginx          # legacy form
    nginx.ingress.kubernetes.io/rewrite-target: /$2
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/proxy-body-size: "50m"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
    nginx.ingress.kubernetes.io/cors-allow-origin: "https://app.example.com"
    nginx.ingress.kubernetes.io/auth-type: basic
    nginx.ingress.kubernetes.io/auth-secret: basic-auth
    nginx.ingress.kubernetes.io/configuration-snippet: |
      more_set_headers "X-Frame-Options: DENY";
spec:
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /v1(/|$)(.*)
            pathType: ImplementationSpecific
            backend:
              service: { name: api, port: { number: 8080 } }
14

Volume (PV/PVC)

Manifest de PersistentVolume

Un PersistentVolume (PV) es una pieza de almacenamiento con ámbito de clúster aprovisionada por un admin o dinámicamente por una StorageClass. accessModes describe cómo puede montarse. reclaimPolicy controla qué pasa con el almacenamiento cuando el PVC se libera.

kubernetes
apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-1
spec:
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce        # RWO: one node R/W
  persistentVolumeReclaimPolicy: Retain   # Retain | Delete | Recycle
  storageClassName: manual
  hostPath:                # for dev only (single node)
    path: /mnt/data
  # nfs:
  #   server: 10.0.0.1
  #   path: /export/data
  # csi:
  #   driver: ebs.csi.aws.com
  #   volumeHandle: vol-xxxx

Manifest de PersistentVolumeClaim

Un PersistentVolumeClaim (PVC) es una solicitud de almacenamiento con ámbito de namespace. El controlador lo vincula a un PV coincidente (accessModes, capacidad suficiente, misma StorageClass). Con una StorageClass por defecto, dejar storageClassName vacío dispara el aprovisionamiento dinámico.

kubernetes
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data-claim
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: manual
  resources:
    requests:
      storage: 5Gi
  volumeMode: Filesystem     # Filesystem | Block
  selector:                  # optional: filter PVs by labels
    matchLabels:
      disktype: ssd
# kubectl get pvc
# STATUS: Pending -> Bound once a matching PV is found

Modos de acceso

AccessModes describen la semántica de montaje — pero el soporte real depende del backend de almacenamiento. EBS/GCE PD/Azure Disk son solo RWO. RWX (lectura/escritura multinodo) necesita NFS, CephFS o un sistema de archivos distribuido. RWOP (1.27+) restringe a un solo pod incluso en el mismo nodo.

kubernetes
# four access modes (support is driver-specific):
# - ReadWriteOnce  (RWO):  mounted R/W by ONE node
# - ReadOnlyMany   (ROX):  mounted R/O by MANY nodes
# - ReadWriteMany  (RWX):  mounted R/W by MANY nodes
# - ReadWriteOncePod (RWOP): mounted R/W by ONE pod (1.27+)

# examples by backend:
# AWS EBS, GCE PD, Azure Disk:  RWO only
# NFS:                          RWO, ROX, RWX
# CephFS, Portworx:             RWO, RWX
# Block volumes:                RWO

# RWX is required for pods on different nodes
# to share the same volume (e.g. read-only assets)

Política de reclaim

Retain conserva los datos por seguridad — debes limpiar y revincular el PV manualmente. Delete (por defecto en el aprovisionamiento dinámico) borra tanto el PV como el almacenamiento subyacente cuando el PVC desaparece. Recycle está deprecado. Un PV Released con Retain necesita que se limpie su claimRef antes de revincular.

kubernetes
# what happens when a PVC is deleted:
# - Retain:   PV stays, data preserved; PV must be manually
#             reclaimed (delete data, then delete PV) before reuse
# - Delete:   PV and the underlying storage are deleted (dynamic only)
# - Recycle:  deprecated; ran scrub on the volume

# change policy on an existing PV
kubectl patch pv pv-1 -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'

# a released PV (PVC deleted, policy Retain) is stuck:
#   phase=Released, claimRef still set
# to reuse: clear claimRef
kubectl patch pv pv-1 --type json -p '[{"op":"remove","path":"/spec/claimRef"}]'

PVC en un Pod

Monta un PVC como cualquier volumen vía persistentVolumeClaim.claimName. subPath monta un subdirectorio — práctico para compartir un volumen entre pods/rutas. Los volúmenes RWO pueden montarse por varios pods pero solo en el mismo nodo; el montaje entre nodos causa errores de multi-attach.

kubernetes
apiVersion: v1
kind: Pod
metadata:
  name: db
spec:
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName: data-claim
  containers:
    - name: db
      image: postgres:16
      volumeMounts:
        - name: data
          mountPath: /var/lib/postgresql/data
          subPath: pgdata       # mount a subdirectory of the volume

# a PVC is namespaced and bound to ONE PV
# RWO PVCs can be mounted by multiple pods on the SAME node
# (e.g. one writer, several readers on that node)

Aprovisionamiento estático vs dinámico

El aprovisionamiento estático exige que los admins pre-creen los PVs — bien para NFS, doloroso a escala. El dinámico permite que un PVC dispare la creación del volumen bajo demanda vía el provisioner de una StorageClass. Los clústeres modernos casi siempre usan aprovisionamiento dinámico; el estático queda reservado para almacenamiento compartido/legado.

kubernetes
# STATIC: admin pre-creates PVs; PVCs bind to them.
#   Good for: pre-existing NFS exports, manual capacity planning.

# DYNAMIC: PVC requests storage; StorageClass provisions a PV
#   automatically (AWS EBS, GCE PD, Ceph, local-path, etc.)

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: dynamic-claim
spec:
  storageClassName: ebs-sc      # triggers dynamic provisioning
  accessModes: ["ReadWriteOnce"]
  resources:
    requests:
      storage: 20Gi

# no PV exists -> provisioner creates one -> binds to PVC
# kubectl get pvc dynamic-claim -> Bound
# kubectl get pv -> shows the dynamically-created PV
15

StorageClass

Manifest de StorageClass

Una StorageClass describe un 'sabor' de almacenamiento aprovisionado dinámicamente: el provisioner (driver CSI), los parámetros (tipo de disco, cifrado, fsType) y las políticas. Los PVCs la referencian vía spec.storageClassName. Un clúster suele tener varias clases (SSD rápida, HDD masiva, NFS, …).

kubernetes
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: ebs-sc
provisioner: ebs.csi.aws.com
parameters:
  type: gp3
  fsType: ext4
  encrypted: "true"
reclaimPolicy: Delete            # Retain | Delete
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
mountOptions:
  - noatime
# kubectl get storageclass

StorageClass por defecto

Exactamente una StorageClass puede ser la por defecto (anotación is-default-class: true). Los PVCs que omiten storageClassName la usan automáticamente — cómodo para usuarios que no se preocupan de qué backend obtienen. Usa kubectl get sc para ver qué clase está marcada (default).

kubernetes
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: standard
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
provisioner: kubernetes.io/no-provisioner
volumeBindingMode: WaitForFirstConsumer

# a PVC with no storageClassName uses the default
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: auto
spec:
  accessModes: ["ReadWriteOnce"]
  resources:
    requests:
      storage: 5Gi
# (no storageClassName set -> uses 'standard')

Provisioners

kubernetes.io/no-provisioner significa solo vinculación estática (sin creación dinámica). El aprovisionamiento dinámico real usa drivers CSI — los proveedores de nube traen los suyos (ebs.csi.aws.com, etc.), y las opciones autohospedadas (Longhorn, Rook/Ceph, local-path) cubren bare metal. Los parámetros son completamente específicos de cada provisioner.

kubernetes
# built-in (no external driver): only static binding
provisioner: kubernetes.io/no-provisioner

# cloud CSI drivers (dynamic):
provisioner: ebs.csi.aws.com          # AWS EBS
provisioner: pd.csi.storage.gke.io    # GCE PD
provisioner: disk.csi.azure.com       # Azure Disk
provisioner: nfs.csi.k8s.io           # NFS

# popular self-hosted:
provisioner: driver.longhorn.io       # Longhorn
provisioner: rook-ceph.ceph.com       # Rook/Ceph
provisioner: rancher.io/local-path    # local-path (dev)

# parameters are provisioner-specific
# (e.g. AWS: type=gp3|iops=3000|encrypted=true)

Modo de vinculación de volúmenes

Immediate vincula el PVC en cuanto se crea — arriesgado para discos zonales porque el pod podría aterrizar en otra zona. WaitForFirstConsumer difiere la vinculación hasta que un pod realmente consume el PVC, así el volumen aterriza en la zona correcta. Usa siempre WaitForFirstConsumer para discos zonales en la nube.

kubernetes
spec:
  volumeBindingMode: WaitForFirstConsumer
  # ^ default for many CSI drivers
  # alternatives:
  # volumeBindingMode: Immediate

# Immediate: PVC binds/provisions as soon as created
#   risk: volume created in zone A, pod scheduled in zone B
#   -> multi-attach / cross-zone latency issues

# WaitForFirstConsumer: delays binding until a pod using the PVC
#   is scheduled. The PV is then created in the pod's zone.
#   REQUIRED for topology-constrained backends (EBS, etc.)

# topology constraints come from the CSI driver via
# AllowedTopologies

Reclaim por StorageClass

StorageClass.reclaimPolicy fija la política de cada PV que aprovisiona dinámicamente. Delete (por defecto) destruye el volumen al eliminar el PVC — eficiente pero peligroso para datos de producción. Para salvar datos, cambia el PV a Retain antes de borrar el PVC, o usa una clase Retain desde el principio.

kubernetes
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: ebs-temp
provisioner: ebs.csi.aws.com
reclaimPolicy: Delete            # default for dynamic volumes
# reclaimPolicy: Retain          # keep data after PVC delete

# the StorageClass policy becomes the PV's policy
# when a PV is dynamically provisioned

# to preserve data, either:
# 1. use a Retain StorageClass
# 2. patch the dynamically-created PV to Retain before deleting PVC:
kubectl patch pv pvc-xxxx -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'

# then delete PVC safely; data survives

Expansión de volúmenes

Establecer allowVolumeExpansion: true permite a los usuarios crecer un PVC editando spec.resources.requests.storage. El driver CSI expande el volumen subyacente, luego el kubelet expande el sistema de archivos en el próximo montaje. Encoger nunca se admite. La mayoría de los drivers CSI de nube admiten expansión en línea (sin desmontar).

kubernetes
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: ebs-sc
provisioner: ebs.csi.aws.com
allowVolumeExpansion: true       # must be true to resize

# then resize by editing the PVC's requested size
kubectl patch pvc data-claim -p '{"spec":{"resources":{"requests":{"storage":"50Gi"}}}}'

# status.conditions shows Resizing / FileSystemResizePending
kubectl describe pvc data-claim

# requirements:
# - StorageClass.allowVolumeExpansion = true
# - driver supports online expansion (most CSI drivers do)
# - shrinking is NOT supported (only grow)
# - FilesystemResize happens after the PV is expanded
16

Helm

Install y release de Helm

Helm empaqueta manifests de Kubernetes como un 'chart' y los gestiona como un 'release'. install crea un release; upgrade aplica cambios; upgrade --install es idempotente. Los releases se rastrean con un Secret/ConfigMap en el namespace — así funciona el rollback.

kubernetes
# add and update a chart repo
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

# search for charts
helm search repo nginx
helm search hub wordpress   # searches Artifact Hub

# install a chart (creates a release)
helm install my-nginx bitnami/nginx --namespace web --create-namespace

# upgrade an existing release
helm upgrade my-nginx bitnami/nginx --set replicaCount=3

# upgrade + install in one idempotent command
helm upgrade --install my-nginx bitnami/nginx -f values.yaml

# uninstall
helm uninstall my-nginx -n web

# list releases
helm list -n web
helm list --all-namespaces

Estructura del chart

Un chart es un directorio de YAML con plantillas más valores por defecto. Chart.yaml guarda los metadatos; values.yaml los valores por defecto; templates/ las plantillas Go que se renderizan con esos valores. helm create andaza un chart funcional. helm lint detecta errores de schema/plantilla antes de publicar.

kubernetes
my-chart/
├── Chart.yaml          # chart metadata (name, version, apiVersion)
├── values.yaml         # default values (overridable)
├── charts/             # chart dependencies (subcharts)
├── templates/          # Go-templated YAML
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── _helpers.tpl    # named templates (partials)
│   └── NOTES.txt       # post-install notes
├── templates.yaml      # (optional) CRDs to install before templates
└── README.md

# create a new chart skeleton
helm create my-chart

# lint a chart
helm lint my-chart

# package into a .tgz
helm package my-chart

Values y overrides

values.yaml guarda los valores por defecto del chart. Sobrescribe con --set (para escalares) o -f (para archivos completos). helm show values lista todas las claves que admite un chart. helm template renderiza los manifests sin tocar el clúster — esencial para ver qué aplicará realmente un release.

kubernetes
# values.yaml (chart defaults)
image:
  repository: nginx
  tag: "1.25"
replicaCount: 2
service:
  type: ClusterIP
  port: 80

# override on the command line
helm upgrade --install web my-chart \
  --set replicaCount=5 \
  --set image.tag=1.26 \
  --set service.type=LoadBalancer

# override from a file
helm upgrade --install web my-chart -f prod-values.yaml

# see all values a chart supports
helm show values bitnami/nginx

# rendered output (debug, no install)
helm template web my-chart -f prod-values.yaml

Plantillas y objetos integrados

Las plantillas usan sintaxis de Go template con funciones Sprig. .Release.Name hace única cada instalación; .Values expone los valores del chart; .Chart extrae de Chart.yaml. La función default aporta valores de respaldo. Nombrar de forma segura con .Release.Name permite que un chart corra muchos releases en el mismo namespace.

kubernetes
# built-in template objects:
#   .Values         chart values (after overrides)
#   .Release        release metadata (Name, Namespace, Service, Revision, IsInstall, IsUpgrade)
#   .Chart          Chart.yaml contents
#   .Files          files in the chart
#   .Capabilities   cluster capabilities (KubeVersion, APIVersions)
#   .Template       current template info

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-app
  labels:
    app.kubernetes.io/instance: {{ .Release.Name }}
    app.kubernetes.io/managed-by: {{ .Release.Service }}
spec:
  replicas: {{ .Values.replicaCount | default 1 }}
  selector:
    matchLabels:
      app: {{ .Release.Name }}
  template:
    metadata:
      labels:
        app: {{ .Release.Name }}

Repositorio de Helm

Helm 3 admite tanto los repos de charts HTTP clásicos como los registros OCI (helm push/pull oci://…). OCI es el camino moderno y compatible con firmas. helm repo update refresca los índices; ejecútalo siempre antes de upgrade para obtener las últimas versiones de charts. Artifact Hub (helm search hub) indexa charts públicos.

kubernetes
# add a chart repository
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo add jetstack https://charts.jetstack.io

# list configured repos
helm repo list

# update repo indexes
helm repo update

# remove a repo
helm repo remove bitnami

# push to OCI registry (Helm 3+)
helm registry login registry.example.com
helm package my-chart
helm push my-chart-0.1.0.tgz oci://registry.example.com/charts

# pull an OCI chart
helm pull oci://registry.example.com/charts/my-chart --version 0.1.0

Rollback e historial

Cada install/upgrade crea una revisión numerada guardada como Secret. helm rollback salta a una revisión anterior al instante — la característica estrella de Helm frente al simple kubectl apply. helm get values muestra lo que realmente se desplegó, invaluable para depurar estados desviados.

kubernetes
# view release history
helm history my-nginx -n web

# rollback to a previous revision
helm rollback my-nginx 1 -n web

# get rendered manifests of a deployed release
helm get manifest my-nginx -n web

# get the values used at install/upgrade
helm get values my-nginx -n web
helm get values my-nginx -n web --all   # incl. chart defaults

# get all info (hooks, manifest, values, notes)
helm get all my-nginx -n web

# wait for resources to be ready on install/upgrade
helm upgrade --install my-nginx bitnami/nginx --wait --timeout 5m
17

NetworkPolicy

Manifest de NetworkPolicy

Una NetworkPolicy es una regla de firewall para pods. Un podSelector vacío selecciona cada pod del namespace; una lista de reglas vacía deniega por completo el tráfico de ese tipo. Las NetworkPolicies son aditivas — un pod se permite si CUALQUIER política lo autoriza. Requieren una CNI que las soporte; flannel plano las ignora.

kubernetes
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny
  namespace: prod
spec:
  podSelector: {}             # selects ALL pods in the namespace
  policyTypes:
    - Ingress
    - Egress
  # no ingress/egress rules => deny all traffic of that type
# effect: pods in 'prod' can't send or receive ANY traffic
# until another policy explicitly allows it

# REQUIRES a CNI that supports NetworkPolicy
# (Calico, Cilium, Weave, kube-router; NOT flannel alone)

Reglas de Ingress

Las reglas de ingress permiten el tráfico HACIA los pods seleccionados. Las entradas from se combinan con OR; los puertos también. podSelector coincide con pods del mismo namespace; namespaceSelector coincide con namespaces enteros (usa la label kubernetes.io/metadata.name agregada automáticamente). Combinar ambos en una entrada los une con AND.

kubernetes
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-web
  namespace: prod
spec:
  podSelector:
    matchLabels:
      app: web
  policyTypes:
    - Ingress
  ingress:
    - from:
        - podSelector:               # pods in same namespace
            matchLabels:
              app: gateway
        - namespaceSelector:         # whole other namespace
            matchLabels:
              kubernetes.io/metadata.name: monitoring
        - ipBlock:                   # external CIDR
            cidr: 10.0.0.0/8
      ports:
        - protocol: TCP
          port: 8080

Reglas de Egress

Las reglas de egress controlan CON QUIÉN pueden hablar los pods seleccionados. Una trampa común: un egress default-deny rompe la resolución DNS y los pods no alcanzan kube-dns. Permite siempre UDP/TCP 53 hacia el namespace kube-system antes de denegar lo demás. ipBlock.except recorta excepciones.

kubernetes
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-egress-dns
  namespace: prod
spec:
  podSelector:
    matchLabels:
      app: web
  policyTypes:
    - Egress
  egress:
    - to:
        - namespaceSelector: {}     # any namespace (kube-dns)
      ports:
        - protocol: UDP
          port: 53
    - to:
        - ipBlock:
            cidr: 0.0.0.0/0
            except:
              - 10.0.0.0/8          # allow internet, deny internal
      ports:
        - protocol: TCP
          port: 443

# WARNING: egress deny-all blocks DNS and breaks pods.
# Always allow kube-dns first.

Selectors y selección de namespaces

Un podSelector aislado coincide con pods del namespace propio de la política. Un namespaceSelector coincide con namespaces enteros. Especificar BOTH podSelector Y namespaceSelector en una entrada los une con AND (pods con label X en namespace Y) — colocarlos como entradas separadas los une con OR. ipBlock coincide con IPs externas.

kubernetes
spec:
  podSelector:                       # selects pods in THIS namespace
    matchLabels:
      app: web
  ingress:
    - from:
        # SAME namespace, matching pods
        - podSelector:
            matchLabels:
              app: gateway

        # DIFFERENT namespace (whole namespace)
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: monitoring

        # BOTH: pods in another namespace with specific labels
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: backend
          podSelector:
            matchLabels:
              app: api

        # external IP range
        - ipBlock:
            cidr: 192.168.1.0/24

Políticas por defecto (denegar/permitir sin restricción)

Las políticas default-deny (reglas vacías) encierran un namespace para que solo las listas de permiso explícitas abran agujeros. Aplica deny-all ingress + deny-all egress como línea base, y luego agrega políticas de permiso dirigidas. Una entrada ingress: [{}] vacía permite el ingress sin restricción — la válvula de escape para excluirse.

kubernetes
# --- DEFAULT DENY INGRESS (in a namespace) ---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny-ingress
  namespace: prod
spec:
  podSelector: {}
  policyTypes: [Ingress]
---
# --- DEFAULT DENY EGRESS ---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny-egress
  namespace: prod
spec:
  podSelector: {}
  policyTypes: [Egress]
---
# --- ALLOW ALL INGRESS (whitelist opt-out) ---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-all-ingress
  namespace: prod
spec:
  podSelector: {}
  policyTypes: [Ingress]
  ingress:
    - {}      # allow from anywhere

Tipos de política y comportamiento por defecto

Las NetworkPolicies son aditivas — en cuanto cualquier política selecciona un pod, ese tipo de tráfico se vuelve default-deny para el pod salvo que una regla explícita lo permita. Sin ninguna política, el tráfico queda completamente abierto. Lista las políticas que coinciden con las labels de un pod para ver qué rige su tráfico.

kubernetes
spec:
  policyTypes:
    - Ingress
    - Egress
  # if omitted, defaults are inferred:
  #   - Ingress is always present (a policy always affects ingress)
  #   - Egress is implied if any egress rule exists

# key behaviors:
# - policies are ADDITIVE: a pod is allowed if ANY matching
#   policy permits the traffic
# - if NO policy selects a pod => all traffic allowed (default open)
# - if at least one policy selects a pod => default deny for that type
#   unless an explicit rule allows it

# inspect effective policies for a pod
kubectl get networkpolicy -n prod -l app=web
18

RBAC

Role (namespaced)

Un Role otorga permisos sobre recursos con namespace dentro de un único namespace. rules lista apiGroups, resources y verbs. pods/log es un subrecurso; pods/exec requiere el verbo create (porque exec crea un subrecurso). Usa '*' como comodín para cualquier valor.

kubernetes
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: pod-reader
  namespace: dev
rules:
  - apiGroups: [""]
    resources: ["pods", "pods/log"]
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources: ["pods/exec"]
    verbs: ["create"]
# a Role grants permissions WITHIN one namespace
# verbs: get, list, watch, create, update, patch, delete, deletecollection, "*"
# apiGroups: "" (core), "apps", "batch", "rbac.authorization.k8s.io", ...

RoleBinding

Un RoleBinding otorga un Role (o un ClusterRole, acotado a un namespace) a sujetos: Users, Groups o ServiceAccounts. El binding vive en el namespace donde aplican los permisos. roleRef es inmutable — para cambiar el Role referenciado, elimina y recrea el binding.

kubernetes
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: read-pods
  namespace: dev
subjects:
  - kind: User
    name: alice
    apiGroup: rbac.authorization.k8s.io
  - kind: ServiceAccount
    name: my-sa
    namespace: dev
  - kind: Group
    name: dev-team
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io
# binds the Role to users, groups, or service accounts
# RoleBinding can also reference a ClusterRole (scoped to its namespace)

ClusterRole y ClusterRoleBinding

Un ClusterRole otorga permisos sobre recursos con ámbito de clúster (nodes, namespaces, PVs) — los Roles no pueden tocarlos. Los ClusterRoles también pueden vincularse en cualquier namespace vía un RoleBinding para reutilización (define una vez, vincula muchas). ClusterRoleBinding otorga un ClusterRole a escala de clúster.

kubernetes
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: node-reader
rules:
  - apiGroups: [""]
    resources: ["nodes"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: read-nodes
subjects:
  - kind: ServiceAccount
    name: monitor
    namespace: kube-system
roleRef:
  kind: ClusterRole
  name: node-reader
  apiGroup: rbac.authorization.k8s.io
# ClusterRole grants cluster-scoped resources (nodes, PVs, namespaces)
# or can be reused across namespaces via a RoleBinding

Verbs, Resources y API Groups

apiGroups agrupa recursos — core es '' (cadena vacía); apps tiene Deployments/StatefulSets; batch tiene Jobs/CronJobs. Los subrecursos (pods/log, pods/exec, pods/portforward) son permisos separados. resourceNames restringe una regla a instancias específicas. nonResourceURLs cubre /healthz, /metrics, etc.

kubernetes
rules:
  - apiGroups: [""]                        # core API group
    resources: ["pods", "services", "configmaps", "secrets"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["apps"]
    resources: ["deployments", "replicasets", "statefulsets"]
    verbs: ["*"]
  - apiGroups: ["batch"]
    resources: ["jobs", "cronjobs"]
    verbs: ["create", "delete", "get"]
  - apiGroups: [""]
    resources: ["pods/log", "pods/exec", "pods/portforward"]
    verbs: ["get", "create"]
  - nonResourceURLs: ["/healthz", "/healthz/*"]   # non-resource URLs
    verbs: ["get"]

# resourceNames: restrict to specific instances
  - apiGroups: [""]
    resources: ["configmaps"]
    resourceNames: ["my-config"]
    verbs: ["get"]

ServiceAccount

Un ServiceAccount es una identidad para los pods. Asígnalo vía serviceAccountName; el token se automonta en /var/run/secrets/kubernetes.io/serviceaccount. Desde 1.24, las SAs no tienen Secrets de token permanentes — usa kubectl create token para tokens de vida corta y con límite temporal. automountServiceAccountToken: false lo desactiva.

kubernetes
# create a service account
kubectl create serviceaccount my-sa -n dev

# assign a RoleBinding (see RoleBinding example)
# mount the SA in a pod
apiVersion: v1
kind: Pod
metadata:
  name: app
spec:
  serviceAccountName: my-sa
  automountServiceAccountToken: false   # opt out of token mount
  containers:
    - name: app
      image: myapp:1.0

# short-lived tokens (1.24+) - no permanent secret
kubectl create token my-sa -n dev --duration=1h

# list SAs
kubectl get sa -n dev

kubectl auth can-i

kubectl auth can-i comprueba los permisos RBAC del usuario actual (o suplantado) — esencial para depurar errores 'forbidden'. --list muestra cada verbo/recurso permitido. --as suplanta a un user/SA para pruebas. Los roles integrados (view, edit, admin, cluster-admin) cubren necesidades comunes.

kubernetes
# check if you can do something
kubectl auth can-i create pods -n dev
kubectl auth can-i delete deployments -n prod

# check on behalf of another user/SA
kubectl auth can-i list secrets --as=system:serviceaccount:dev:my-sa -n dev

# check all allowed verbs on a resource
kubectl auth can-i --list --as=alice -n dev

# whoami (1.25+)
kubectl auth whoami

# reconcile: detect over-privileged bindings
kubectl get rolebindings,clusterrolebindings --all-namespaces -o wide

# common built-in cluster roles:
#   view, edit, admin, cluster-admin
19

Probes (Liveness/Readiness/Startup)

Liveness Probe

Una liveness probe le dice al kubelet cuándo reiniciar un contenedor. Si falla failureThreshold veces consecutivas, el kubelet mata el contenedor y aplica la política de reinicio. Úsala para recuperarte de deadlocks o estados irrecuperables — no para revisar dependencias (eso es la readiness).

kubernetes
apiVersion: v1
kind: Pod
metadata:
  name: app
spec:
  containers:
    - name: app
      image: myapp:1.0
      livenessProbe:
        httpGet:
          path: /healthz
          port: 8080
        initialDelaySeconds: 15
        periodSeconds: 10
        timeoutSeconds: 2
        failureThreshold: 3
        successThreshold: 1
# if the probe fails failureThreshold times in a row,
# kubelet kills and restarts the container (per restartPolicy)

Readiness Probe

Una readiness probe controla si el pod recibe tráfico de los Services. Una readiness probe que falla quita la IP del pod de los endpoints — pero NO lo reinicia. Úsala para el calentamiento (no enrutar hasta estar listo) y para drenar tráfico durante fallos transitorios o apagados con elegancia.

kubernetes
apiVersion: v1
kind: Pod
metadata:
  name: app
spec:
  containers:
    - name: app
      image: myapp:1.0
      readinessProbe:
        httpGet:
          path: /ready
          port: 8080
        initialDelaySeconds: 5
        periodSeconds: 5
        failureThreshold: 3
# a failing readiness probe REMOVES the pod from service endpoints,
# but does NOT restart the container.
# use to drain traffic during deploys, warm-up, or transient outages.

Startup Probe

Una startup probe (1.18+) es para apps lentas en arrancar (Java, servidores legados). Mientras corre, liveness y readiness están desactivadas — así un arranque lento no muere por liveness. Una vez que la startup tiene éxito, se activan liveness/readiness. Usa una ventana larga de failureThreshold × periodSeconds para el arranque.

kubernetes
apiVersion: v1
kind: Pod
metadata:
  name: slow-app
spec:
  containers:
    - name: app
      image: myapp:1.0
      startupProbe:
        httpGet:
          path: /startup
          port: 8080
        failureThreshold: 30
        periodSeconds: 10      # up to 300s to start
      livenessProbe:
        httpGet:
          path: /healthz
          port: 8080
        periodSeconds: 10
# while the startup probe runs, liveness/readiness are disabled.
# once startup succeeds, liveness/readiness take over.

Handlers de probes

Tres tipos de handler: httpGet (éxito = HTTP 2xx/3xx), tcpSocket (éxito = conexión TCP), exec (éxito = código de salida 0). La probe gRPC (1.27+ GA) es la opción limpia para servicios gRPC. Prefiere httpGet — permite que la app señale 'saludable pero ocupado' (503) sin reiniciar. exec es frágil (necesita shell/binarios en la imagen).

kubernetes
# three handler types:

# 1. HTTP GET (most common) - success = 200-399
livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
    httpHeaders:
      - name: X-Custom
        value: probe
    scheme: HTTP

# 2. TCP socket - success = port open
livenessProbe:
  tcpSocket:
    port: 3306

# 3. Exec - success = exit code 0
livenessProbe:
  exec:
    command:
      - /bin/sh
      - -c
      - "pg_isready -h localhost"

# gRPC (1.24+, alpha -> GA): use grpc probe
livenessProbe:
  grpc:
    port: 9090
    service: my.package.Health

Parámetros de probes

initialDelaySeconds retrasa la primera probe — pero una startup probe es una forma más limpia de manejar arranques lentos. periodSeconds es la cadencia; failureThreshold × periodSeconds es cuánto tiempo puede estar un pod no saludable antes de actuar. Ajusta estos valores para failover rápido, relájalo para tolerancia. terminationGracePeriodSeconds acota el apagado.

kubernetes
livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 15   # wait before first probe (after start)
  periodSeconds: 10         # probe every 10s
  timeoutSeconds: 2         # max time per probe
  successThreshold: 1       # consecutive successes to mark OK
  failureThreshold: 3       # consecutive failures to mark failed
  terminationGracePeriodSeconds: 30  # (liveness) grace before SIGKILL

# tuning tips:
# - set initialDelaySeconds > typical startup time
# - OR use a startup probe instead (cleaner)
# - shorter period = faster reaction, more load
# - higher failureThreshold = more tolerant of blips

Comportamiento ante fallos de probes

El fallo de liveness mata y reinicia el contenedor en el sitio (no se reprograma). El fallo de readiness solo quita el pod de los Services — sin reinicio. El fallo de startup se comporta como liveness. Un liveness intermitente suele venir de probes que dependen de servicios aguas abajo lentos — mantén los health checks locales y baratos.

kubernetes
# --- LIVENESS FAIL ---
#   container killed -> restarted (per restartPolicy: Always/OnFailure)
#   pod stays on the same node (NOT rescheduled)
#   CrashLoopBackOff if it keeps failing

# --- READINESS FAIL ---
#   pod stays running, but is REMOVED from Service endpoints
#   no traffic until it succeeds again
#   NOT restarted by kubelet

# --- STARTUP FAIL ---
#   container killed and restarted (like liveness)
#   liveness/readiness never activate
#   after failureThreshold × periodSeconds, pod is stuck restarting

# check probe results:
kubectl describe pod app | grep -A5 "Last State"
kubectl get pod app -o jsonpath='{.status.containerStatuses[*].state}'

# common cause of flapping: liveness probe hitting a slow dependency
20

Recursos y kubectl avanzado

Requests y Limits

requests es lo que el scheduler reserva (un pod solo se programa si un nodo tiene requests libres) — fíjalos a tus necesidades en estado estacionario. limits son techos duros: la CPU se estrangula, la memoria provoca OOMKilled. cpu va en núcleos (500m = 0.5), memoria en bytes (Mi/Gi). Fija siempre ambos en producción.

kubernetes
spec:
  containers:
    - name: app
      image: myapp:1.0
      resources:
        requests:           # what the scheduler guarantees (reservation)
          cpu: 250m          # 250 millicores = 0.25 core
          memory: 256Mi      # 256 mebibytes
          ephemeral-storage: 1Gi
        limits:             # hard ceiling (enforced)
          cpu: "1"           # 1 core
          memory: 512Mi
          ephemeral-storage: 2Gi

# cpu limit: throttled (cfs quota)
# memory limit: OOMKilled if exceeded
# ephemeral-storage limit: evicted if exceeded
# request only (no limit): best-effort burst

Valores por defecto de LimitRange

LimitRange aplica requests/limits por defecto a los pods que no los especifican — crítico cuando un ResourceQuota exige requests. max/min acotan cuán grande/pequeño puede ser un solo contenedor. maxLimitRequestRatio limita cuánto puede dispararse un contenedor por encima de su request, evitando vecinos ruidosos.

kubernetes
apiVersion: v1
kind: LimitRange
metadata:
  name: defaults
  namespace: prod
spec:
  limits:
    - type: Container
      default:               # applied as LIMITS when not set
        cpu: 500m
        memory: 512Mi
      defaultRequest:        # applied as REQUESTS when not set
        cpu: 100m
        memory: 128Mi
      max:                   # max allowed LIMITS
        cpu: "4"
        memory: 8Gi
      min:                   # min allowed REQUESTS
        cpu: 50m
        memory: 64Mi
      maxLimitRequestRatio:  # limit/request ratio cap (burst cap)
        cpu: "4"

# a pod with no resources gets default/defaultRequest applied
# a pod with limit=4cpu, request=50m would breach maxLimitRequestRatio

Horizontal Pod Autoscaler

HPA escala las réplicas según métricas (CPU/memoria vía metrics-server, o custom/external vía Prometheus Adapter). behavior (v2) ajusta la agresividad: stabilizationWindowSeconds evita el flapping, policies acotan la tasa por minuto. Escalar hacia arriba suele ser rápido/agresivo; hacia abajo es deliberadamente lento.

kubernetes
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: web
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: web
  minReplicas: 3
  maxReplicas: 50
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization          # avg across pods
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80
  behavior:                          # (v2) scale up/down tuning
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
        - type: Percent
          value: 50                  # max 50% down per minute
          periodSeconds: 60
    scaleUp:
      stabilizationWindowSeconds: 0
      policies:
        - type: Percent
          value: 100
          periodSeconds: 60

# requires metrics-server for CPU/memory
kubectl get hpa web -w

Pod Disruption Budget

Un PodDisruptionBudget limita cuántos pods de un conjunto pueden expulsarse voluntariamente a la vez — protege la disponibilidad durante drenajes de nodos y acciones del cluster-autoscaler. Usa minAvailable o maxUnavailable (no ambos). NO protege contra disrupciones involuntarias (fallo de hardware) — para eso solo sirven las réplicas.

kubernetes
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: web-pdb
  namespace: prod
spec:
  minAvailable: 2            # at least 2 pods always available
  # OR
  # maxUnavailable: 1        # at most 1 down at a time
  selector:
    matchLabels:
      app: web
# PDB protects against VOLUNTARY disruptions:
#   - kubectl drain (node maintenance)
#   - cluster autoscaler evictions
#   - kubectl delete pod (controller-managed)
# It does NOT prevent INVOLUNTARY disruptions (node failure, kernel panic).

# check PDB status
kubectl get pdb -n prod
kubectl describe pdb web-pdb -n prod

Taints, tolerations y affinity

Los taints repelen pods; las tolerations permiten que pods específicos los ignoren — úsalos para dedicar nodos (GPU, ingress, control-plane). nodeAffinity prefiere/exige ciertos nodos. podAntiAffinity dispersa las réplicas por dominios de topología (hosts, zonas) para HA. Quita un taint con un guion final sobre la misma clave+efecto.

kubernetes
# taint a node
kubectl taint nodes node-1 dedicated=gpu:NoSchedule

# tolerate the taint so a pod can schedule there
spec:
  tolerations:
    - key: dedicated
      operator: Equal
      value: gpu
      effect: NoSchedule

# prefer specific nodes
spec:
  affinity:
    nodeAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
        - weight: 100
          preference:
            matchExpressions:
              - key: disktype
                operator: In
                values: [ssd]
    podAntiAffinity:               # spread replicas across nodes
      requiredDuringSchedulingIgnoredDuringExecution:
        - topologyKey: kubernetes.io/hostname
          labelSelector:
            matchLabels:
              app: web

# remove a taint
kubectl taint nodes node-1 dedicated=gpu:NoSchedule-

kubectl avanzado (patch/wait/top/debug)

patch admite los tipos JSON, strategic-merge y merge. wait bloquea hasta que se cumple una condición — perfecto para scripts. top muestra CPU/memoria en vivo (necesita metrics-server). kubectl debug adjunta un contenedor efímero a un pod en ejecución (genial para imágenes distroless) o abre un shell en un nodo.

kubernetes
# JSON patch (precise field ops)
kubectl patch deployment web --type json -p \
  '[{"op":"replace","path":"/spec/replicas","value":3}]'

# strategic merge patch (default for k8s objects)
kubectl patch svc web -p '{"spec":{"type":"NodePort"}}'

# wait for a condition
kubectl wait --for=condition=Ready pod/web --timeout=60s
kubectl wait --for=delete pod/web --timeout=30s

# resource usage (needs metrics-server)
kubectl top nodes
kubectl top pods -n prod
kubectl top pod web --containers

# ephemeral debug container (1.25+)
kubectl debug -it web --image=busybox --target=web
# debug a node
kubectl debug node/node-1 -it --image=ubuntu

# run a one-off pod
kubectl run tmp --rm -it --image=alpine -- sh

# explain a field
kubectl explain pod.spec.containers.resources

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.