Cerramos el módulo 9 con un diagnóstico incómodo: la plataforma Rutas Norte ya sabe escalar sola, resistir el puente de mayo y protegerse durante los mantenimientos, pero el directorio k8s/ se ha convertido en más de 120 ficheros YAML duplicados entre dev, pre y pro que alguien aplica a mano desde su portátil. El módulo 10 va precisamente de eso: de las herramientas que rodean a Kubernetes y que convierten un montón de manifiestos sueltos en un sistema operable.

Empezamos por el eslabón más cercano al equipo de desarrollo: el clúster local. Antes de plantillar nada con Helm (10-03), superponer nada con Kustomize (10-04) o reconciliar nada con Argo CD (10-05), hace falta un sitio barato y desechable donde probar los cambios. En el módulo 1 levantamos el clúster de prácticas con minikube start --profile=rutas-norte casi como un trámite, y dijimos que volveríamos a ello. Ha llegado el momento: en esta lección vamos a fondo con minikube, conocemos kind (la herramienta preferida en integración continua), comparamos las cinco alternativas más habituales y, sobre todo, aprendemos qué se puede validar en un clúster local y qué no, que es la raíz del clásico «en mi máquina funciona».

1. Por qué todo equipo necesita un clúster desechable
2. Minikube a fondo: perfiles y controladores
3. Dimensionado, versión de Kubernetes y clústeres multinodo
4. El catálogo de addons
5. Trabajar con imágenes locales sin registro
6. Acceso al clúster: tunnel, service, dashboard, mount y ssh
7. El ciclo de vida: stop, start, delete y logs
8. kind a fondo: nodos como contenedores
9. Tabla comparativa: minikube, kind, k3d, Docker Desktop y Rancher Desktop
10. Las diferencias con producción que provocan «en mi máquina funciona»
11. Receta reproducible: el entorno completo de Rutas Norte en local
12. Errores comunes y consejos
13. Ejercicios
14. Conclusión

En Rutas Norte S.L. hay tres entornos reales: rutas-norte-dev, rutas-norte-pre y rutas-norte-pro. Los tres viven en clústeres compartidos. Eso significa que cuando una desarrolladora quiere probar si su nuevo NetworkPolicy rompe la conexión entre api-reservas y postgres-reservas, tiene dos opciones malas:

• Aplicarlo en rutas-norte-dev y arriesgarse a bloquear el trabajo de los otros seis compañeros que comparten ese namespace.
• No probarlo y descubrirlo en pre, con el ciclo de espera que eso implica.

Un clúster local resuelve el dilema. Es suyo, gratis, rápido de recrear y, si lo rompe, minikube delete y vuelta a empezar en tres minutos.

La regla práctica: el clúster local valida la corrección de tus manifiestos y la lógica de tu aplicación; no valida el rendimiento, la topología ni la integración con la nube.

minikube es una herramienta que levanta un clúster de Kubernetes de un solo nodo (o de varios) dentro de una máquina virtual o un contenedor de tu equipo. Lo hemos usado desde el módulo 1; ahora vamos a entender qué hace por dentro.

Un perfil es un clúster independiente con su propio nombre, su propia configuración y su propio contexto de kubectl. Es la razón por la que en el módulo 1 escribimos --profile=rutas-norte y no simplemente minikube start.

Salida típica:

Sin --profile, minikube usa el perfil minikube. Puedes fijar el perfil activo para no repetirlo en cada orden:

Consejo: fijar el perfil es cómodo pero peligroso, porque es un estado invisible. En los scripts del equipo Rutas Norte usamos siempre --profile=rutas-norte explícito.

Cada perfil crea también su contexto de kubectl con el mismo nombre:

El controlador (driver) decide dónde se ejecuta el nodo de minikube. Es la decisión más importante al empezar.

Cómo elegir, en tres preguntas:

1. ¿Tienes Docker o Podman funcionando? Usa --driver=docker (o podman). Es lo más rápido y lo que menos memoria consume, porque no hay una VM completa por medio.
2. ¿Necesitas probar módulos del kernel, un CNI exigente o iptables de verdad? Usa kvm2 en Linux. Un contenedor comparte kernel con el anfitrión y algunas cosas no se pueden aislar.
3. ¿Estás en Windows sin WSL2 o en un entorno corporativo restringido? hyperv o virtualbox son la salida.

Con el controlador docker, el nodo es literalmente un contenedor. Puedes verlo:

Ese kicbase es la imagen que contiene systemd, containerd, el kubelet y las herramientas necesarias para que un contenedor se comporte como un nodo.

Por defecto minikube pide 2 CPU y 2 GB de memoria. Para Rutas Norte eso se queda corto en cuanto instalamos Prometheus (07-03) y cert-manager (04-05):

Explicación de cada opción:

• --cpus=4: número de CPU virtuales asignadas al nodo. Con menos de 4, el kube-apiserver y Prometheus compiten y el clúster se siente lento.
• --memory=8192: memoria en MiB (8 GB). Puedes escribir también 8g. Ojo: esta memoria se reserva frente a tu sistema; si tu portátil tiene 16 GB, no le des 12.
• --disk-size=40g: tamaño del disco del nodo. Las imágenes de contenedor se acumulan rápido; 20 GB se agotan en un par de semanas de trabajo real.

Estos valores se recuerdan por perfil. Si mañana ejecutas minikube start --profile=rutas-norte sin flags, respeta lo que ya configuraste. Para cambiarlos hay que borrar y recrear el perfil (o usar minikube config set antes).

Una advertencia importante: --cpus y --memory no se pueden cambiar en caliente con el controlador de VM. Si te quedas corto, minikube delete --profile=rutas-norte y vuelve a crearlo con los valores nuevos. Por eso conviene tener el script de creación versionado (apartado 11).

Esta es una de las prácticas más rentables y más olvidadas. Si rutas-norte-pro corre Kubernetes 1.30 y tu minikube corre 1.32, puedes escribir manifiestos que funcionan en tu portátil y son rechazados en producción, o al revés: puedes no detectar una API obsoleta.

Salida:

Regla del equipo de plataforma de Rutas Norte: el fichero del script de arranque local declara la misma versión menor que producción. Cuando pro sube de versión, el script se actualiza en el mismo cambio.

Un solo nodo no permite probar nada relacionado con la planificación: afinidades (06-05), topologySpreadConstraints (09-05), DaemonSets con varios objetivos (06-02) o el drenaje de un nodo. minikube sabe crear varios:

Fíjate en que --cpus y --memory se aplican por nodo: tres nodos de 2 CPU y 4 GB consumen 6 CPU y 12 GB del anfitrión. Es fácil ahogar el portátil sin darse cuenta.

Puedes añadir o quitar nodos después:

Y etiquetar los nodos para simular zonas y probar la distribución topológica de 09-05:

Esto es una simulación útil para verificar que el selector funciona, pero recuerda: siguen estando en la misma máquina física, así que no prueba la tolerancia real a la caída de una zona.

Los addons son componentes preempaquetados que minikube sabe instalar y mantener por ti. Es lo que evita tener que aplicar a mano los manifiestos del controlador de Ingress o del metrics-server.

Los que usa este curso y por qué:

Cada addon es, por dentro, un conjunto de manifiestos que minikube aplica en el namespace kube-system (o uno propio). Puedes verlos:

Aviso importante: el addon ingress de minikube instala ingress-nginx con una configuración pensada para un solo nodo. En producción, tu equipo de plataforma probablemente lo instala con Helm y con valores muy distintos (réplicas, PDB, recursos). El comportamiento de las reglas es el mismo; el de la disponibilidad, no.

Este es, en la práctica diaria, el punto donde más tiempo se pierde. Has construido api-reservas:dev-local en tu portátil y el pod se queda en ImagePullBackOff, porque el nodo de minikube tiene su propio almacén de imágenes, separado del Docker de tu máquina.

Hay tres formas de resolverlo.

En el manifiesto, la clave es evitar que Kubernetes intente descargarla del registro:

Trampa clásica: si la etiqueta de la imagen es latest, Kubernetes aplica por defecto imagePullPolicy: Always y siempre intentará descargarla, ignorando la copia local. Nunca uses latest (ya lo vimos en 08-05); aquí además te rompe el flujo local.

Si en varios nodos, image load la copia a todos automáticamente.

Esta opción reapunta tu cliente Docker al demonio que corre dentro del nodo de minikube. Lo que construyas queda directamente disponible para el kubelet, sin paso de copia.

Ventaja: es más rápido en el bucle editar-construir-probar, porque no hay copia. Desventaja: solo funciona con el runtime docker; si el perfil usa containerd, no aplica. Y es un estado del terminal fácil de olvidar (has construido dentro del nodo y luego no encuentras la imagen en tu máquina).

Levanta un registro dentro del clúster. Es la opción más parecida a producción, pero también la que más pasos exige (hay que empujar la imagen, resolver el nombre desde el nodo). Para el trabajo diario, la opción A gana casi siempre.

Cuando declaras un Service de tipo LoadBalancer (04-02), Kubernetes le pide a un controlador del proveedor de nube que aprovisione un balanceador. En tu portátil no hay proveedor de nube, así que el Service se queda para siempre en <pending>:

minikube tunnel simula ese balanceador: crea rutas en tu máquina y asigna una IP externa.

Ahora, en otro terminal:

Puntos que confunden a todo el mundo la primera vez:

• El proceso debe seguir vivo. Si cierras el terminal, la IP vuelve a <pending>.
• No es un balanceador real: no hay comprobaciones de salud del proveedor, ni distribución entre zonas, ni reglas de cortafuegos de nube. Solo enruta.
• En macOS y Windows con el controlador docker, tunnel también es necesario para llegar al Ingress.

Para Services de tipo NodePort (o incluso ClusterIP con --url), esta es la vía rápida:

Activa el addon dashboard si no lo estaba, levanta un proxy y abre el navegador. Útil para explorar visualmente el clúster mientras aprendes; en el día a día profesional kubectl y k9s son más rápidos.

A veces quieres que el pod vea un directorio de tu portátil: un volcado SQL de datos de prueba para postgres-reservas, o los ficheros estáticos de tienda-web.

En el pod se usa un hostPath (05-01) apuntando a /datos-prueba, que ahora existe dentro del nodo:

Advertencia: hostPath está prohibido por las Pod Security Standards del nivel restricted (08-03). En local es aceptable para datos de prueba; en rutas-norte-pro sería rechazado, y con razón.

Te deja dentro del nodo. Útil para:

En un clúster multinodo, elige el nodo:

--purge borra además el directorio ~/.minikube con la configuración y la caché de imágenes de Kubernetes. Úsalo cuando minikube esté en un estado raro que no consigues explicar; es el equivalente a apagar y encender.

Cuando minikube start falla o el clúster arranca a medias:

Ese tipo de mensaje casi siempre significa que el nodo se quedó sin recursos o que el estado de red del contenedor quedó corrupto tras un apagón brusco. minikube delete && minikube start lo resuelve, y es exactamente por eso que un clúster local debe ser desechable.

kind (Kubernetes IN Docker) tiene un enfoque distinto y una filosofía más estrecha: cada nodo del clúster es un contenedor de Docker que ejecuta containerd y el kubelet. No hay addons, no hay tunnel, no hay dashboard. Solo Kubernetes, muy rápido y muy reproducible.

Precisamente por esa austeridad, es la herramienta que el propio proyecto Kubernetes usa para sus pruebas y la elección habitual en integración continua.

Tarda unos 25 segundos. El contexto se llama kind-rutas-norte (con el prefijo kind-).

Aquí está la verdadera potencia de kind: el clúster se declara en un fichero versionable.

Repasemos los campos clave:

• extraPortMappings: publica un puerto del contenedor-nodo en tu máquina. Es la solución de kind al problema del acceso externo. Con hostPort: 80, una vez instalado ingress-nginx, curl -H "Host: www.rutasnorte.example" http://localhost llega a tienda-web. Solo se puede definir al crear el clúster: si lo olvidas, hay que recrearlo.
• extraMounts: el equivalente a minikube mount, pero declarativo y sin proceso en primer plano. Mucho más cómodo.
• kubeadmConfigPatches: kind usa kubeadm por dentro (lo veremos en 10-02). Este campo te deja modificar su configuración; aquí lo usamos para poner la etiqueta ingress-ready=true que el manifiesto de ingress-nginx para kind espera en su nodeSelector.
• image: fija la versión de Kubernetes. Igual que con minikube, iguálala a producción.
• labels: etiquetas de nodo aplicadas desde el principio, sin kubectl label posterior.

Ahora sí:

Igual que en minikube, la imagen se copia a todos los nodos. Y también aquí hace falta imagePullPolicy: IfNotPresent y evitar la etiqueta latest.

También puedes cargar un fichero de imagen exportado, práctico en canalizaciones donde la construcción y la carga están en pasos distintos:

Un paso típico en la canalización ci-rutasnorte se reduce a: kind create cluster --config kind-ci.yaml --wait 120s, construir y cargar la imagen, kubectl apply -k k8s/entornos/dev (eso es Kustomize, lo veremos en 10-04), esperar el rollout, ejecutar las pruebas de humo y kind delete cluster al final pase lo que pase.

Notas para elegir:

• k3s (el motor de k3d y Rancher Desktop) es una distribución ligera y conforme, pero sustituye algunas piezas: usa Traefik como Ingress, SQLite en vez de etcd por defecto y desactiva componentes de nube. Es perfecto para desarrollar; es engañoso si quieres comprobar un comportamiento fino del plano de control.
• Docker Desktop con Kubernetes activado es lo más cómodo si ya lo tienes, pero es un solo nodo, no configurable, y su licencia es de pago para empresas por encima de cierto tamaño. Rutas Norte S.L. es pequeña, así que no le afecta, pero es un factor real en decisiones de equipo.
• La recomendación de este curso: minikube para el trabajo diario (por los addons, que ahorran mucha instalación manual) y kind en la canalización ci-rutasnorte (por velocidad y reproducibilidad). Que sean dos herramientas distintas no es un problema si el manifiesto que despliegas es el mismo.

Este apartado es el más importante de la lección. Cada punto es un incidente real esperando a ocurrir.

En local, type: LoadBalancer no hace nada sin minikube tunnel. En rutas-norte-pro, ese mismo Service aprovisiona un balanceador de verdad, con su IP pública, su coste mensual y su tiempo de aprovisionamiento de varios minutos.

Consecuencias que solo ves en la nube: anotaciones específicas del proveedor (tipo de balanceador, certificados, listas de acceso), comprobaciones de salud propias, y el hecho de que borrar el Service borra el balanceador. Lo veremos en 10-06.

Mitigación: en local, usa Ingress (04-04) y no LoadBalancer en los manifiestos de la aplicación. Deja el LoadBalancer solo para el controlador de Ingress, que en local se publica por NodePort o extraPortMappings.

En minikube, la StorageClass standard es un directorio del nodo servido por storage-provisioner. En rutas-norte-pro, postgres-reservas usa una StorageClass de disco de red con IOPS provisionadas (05-04).

Ese último punto es traicionero: en producción el PV no se crea hasta que el pod se planifica, y eso cambia el orden de los eventos. Un StatefulSet que arranca bien en local puede quedarse en Pending en la nube por una afinidad de zona incompatible.

Este es el más peligroso porque falla en silencio. Escribes una NetworkPolicy que aísla postgres-reservas para que solo api-reservas pueda hablar con él (04-06), la aplicas en tu minikube, el objeto se crea sin error... y no hace absolutamente nada, porque el CNI por defecto no la implementa.

Parece que funciona. Pero:

Conecta. La política se ignoró.

Cómo detectarlo: kubectl get pods -n kube-system -o wide | grep -Ei 'calico|cilium|flannel|kindnet'. kindnet (el de kind por defecto) y el bridge básico no implementan NetworkPolicies; calico y cilium sí.

Mitigación: en minikube, --cni=calico. En kind, disableDefaultCNI: true con podSubnet: "192.168.0.0/16" y aplicar después el manifiesto de Calico.

Y la regla de oro: una NetworkPolicy no está probada hasta que has verificado que algo que antes conectaba, ahora no conecta. Probar solo que lo permitido sigue funcionando no demuestra nada.

topologySpreadConstraints (09-05) con topologyKey: topology.kubernetes.io/zone en un clúster de un nodo se satisface trivialmente. Etiquetar los nodos de un clúster multinodo simula zonas y verifica que el selector y las etiquetas son correctos, pero no prueba la tolerancia a fallos.

Igual con el Cluster Autoscaler (09-03): en local no hay grupo de nodos elástico, así que un pod Pending por falta de recursos se queda Pending para siempre. En producción aparecería un nodo nuevo en dos minutos. El síntoma en local es idéntico a un fallo grave en producción, lo que despista.

Lo peor de un entorno local es que cada persona del equipo lo tenga distinto. La solución es un script versionado en el repositorio, junto a los manifiestos.

Explicación de las decisiones del script:

• set -euo pipefail: aborta a la primera orden que falle, en vez de seguir dejando un clúster a medias.
• Versión de Kubernetes en una variable arriba: cuando pro sube de versión, se cambia una línea.
• --cni=calico: la diferencia entre probar de verdad las NetworkPolicies y engañarse.
• --dry-run=client -o yaml | kubectl apply -f -: el patrón idempotente de 01-06; crea el namespace si no existe y no falla si ya existe.
• kubectl wait: el script no termina hasta que el clúster es realmente usable. Sin esto, quien lo ejecuta prueba a desplegar y falla porque el Ingress aún no está.
• El aviso final sobre /etc/hosts: los dominios www.rutasnorte.example y api.rutasnorte.example no existen en ningún DNS; hay que resolverlos a mano contra la IP del nodo.

El equivalente con kind es aún más corto, porque toda la configuración del clúster ya está en kind-rutas-norte.yaml: basta kind create cluster --config ... --wait 180s, aplicar Calico e ingress-nginx, esperar al controlador y cargar las imágenes con kind load docker-image. Y no hace falta tocar /etc/hosts: gracias a extraPortMappings, el Ingress responde en http://localhost con la cabecera Host adecuada.

1. Dar a minikube casi toda la memoria del portátil. Con 16 GB físicos, --memory=12288 deja al sistema operativo sin margen y todo va a tirones. Regla: no más de la mitad de la RAM física, y recuerda que en multinodo el valor se multiplica por el número de nodos.

2. Olvidar que --cpus y --memory se quedan grabados en el perfil. Ejecutas minikube start --profile=rutas-norte --memory=8192 un día, y al día siguiente minikube start --profile=rutas-norte sin flags: sigue usando 8192. Si crees que cambiaste el valor y no cambió nada, es esto. Para cambiarlo hay que recrear el perfil.

3. ImagePullBackOff con una imagen que "sí has construido". Casi siempre son dos causas: no hiciste minikube image load / kind load docker-image, o la etiqueta es latest y el imagePullPolicy implícito es Always. Usa etiquetas explícitas (dev-local) e imagePullPolicy: IfNotPresent.

4. Creer que una NetworkPolicy aplicada está funcionando. Comprueba siempre el CNI y haz la prueba negativa: intenta la conexión que debe estar bloqueada y verifica que da timeout. Sin esa prueba, no has probado nada.

5. Cerrar el terminal de minikube tunnel o minikube mount. Ambos son procesos en primer plano. Si desaparece la IP externa o el directorio montado, mira si el proceso sigue vivo antes de buscar causas exóticas.

6. Descubrir tarde que faltaba un extraPortMapping en kind. No se pueden añadir a un clúster ya creado. Ten el fichero de configuración con los puertos 80, 443 y quizá alguno más desde el principio.

7. Usar latest de la imagen del nodo. Tanto kindest/node como la versión de minikube deben estar fijadas. Un compañero con v1.31 y tú con v1.29 producís resultados distintos sobre los mismos manifiestos.

8. Acumular perfiles olvidados. Cada perfil detenido sigue ocupando disco. minikube profile list de vez en cuando y minikube delete --profile=X de lo que no uses.

9. Tratar el clúster local como si fuera valioso. Si dudas si algo está en un estado raro, bórralo y recréalo. El script del apartado 11 hace que eso cueste tres minutos; investigar un estado corrupto cuesta una tarde.

10. Probar el rendimiento en local. Un benchmark de postgres-reservas en tu SSD no dice nada del disco de red de producción. Para eso están rutas-norte-pre y k6 (09-06).

Crea un perfil de minikube llamado rutas-norte-topologia con 3 nodos, Kubernetes v1.30.4 y Calico como CNI. Etiqueta los dos nodos de trabajo como zona-a y zona-b. Despliega api-reservas con 4 réplicas y un topologySpreadConstraint que reparta entre zonas con maxSkew: 1, y comprueba con kubectl get pods -o wide que el reparto es 2 y 2.

Crea dos clústeres de kind: uno con el CNI por defecto (kindnet) y otro con disableDefaultCNI: true y Calico instalado. En ambos, aplica una NetworkPolicy de denegación total de entrada en el namespace rutas-norte-dev y comprueba, con un pod busybox intentando conectar a un Service, cuál de los dos la respeta de verdad.

Con el perfil rutas-norte en marcha, construye una imagen registry.rutasnorte.example/tienda-web:dev-local, cárgala en minikube y despliégala con un Ingress para www.rutasnorte.example. Después, cambia el contenido de la página, reconstruye con la misma etiqueta, recarga la imagen y consigue que el pod sirva el contenido nuevo. Explica por qué un simple kubectl apply no basta.

Solución 1

Deben salir 2 pods en -m02 y 2 en -m03. El nodo del plano de control no recibe pods porque tiene el taint correspondiente (06-05).

Solución 2

En sin-netpol devuelve el HTML de nginx: la política se ignoró. En con-netpol da timeout: Calico la aplica.

Solución 3

Por qué kubectl apply no basta: el manifiesto no ha cambiado (misma etiqueta de imagen), así que el objeto en la API es idéntico y el Deployment no genera un nuevo ReplicaSet. rollout restart añade una anotación con la marca de tiempo a la plantilla del pod, lo que sí provoca el despliegue. Esta es exactamente la razón por la que en producción se usan etiquetas inmutables con digest (08-05): la imagen nueva tiene un identificador nuevo y el cambio se propaga solo.

Ya sabes montar y destruir clústeres locales con criterio. Los puntos que conviene llevarse:

• minikube brilla por sus addons: ingress, metrics-server, storage-provisioner y csi-hostpath-driver te ahorran instalar a mano media plataforma. Los perfiles permiten tener varios clústeres a la vez, --kubernetes-version iguala tu entorno a producción, y --nodes abre la puerta a probar planificación y topología.
• kind gana en velocidad y reproducibilidad: los nodos son contenedores, todo el clúster se declara en un fichero versionado con extraPortMappings y extraMounts, y por eso es la elección natural de la canalización ci-rutasnorte.
• El bucle de trabajo con imágenes locales se resuelve con minikube image load o kind load docker-image, siempre con imagePullPolicy: IfNotPresent y etiquetas que no sean latest.
• Y lo más importante: un clúster local valida corrección, no realismo. No hay balanceador de nube, la StorageClass es otra, el CNI por defecto puede ignorar tus NetworkPolicies en silencio, y no hay zonas ni escalado de nodos. Saber exactamente qué no estás probando es lo que evita el «en mi máquina funciona».

Nos queda una pregunta pendiente: los clústeres locales son juguetes controlados, pero ¿cómo se monta un clúster de verdad, en máquinas propias, sin que lo haga un proveedor de nube por ti? En la siguiente lección, Kubeadm, veremos la herramienta oficial para arrancar un clúster conforme: preparar las máquinas, instalar containerd, ejecutar kubeadm init con un fichero de configuración, unir nodos, montar un plano de control en alta disponibilidad, renovar certificados y actualizar de versión. Y descubriremos por qué kind, por dentro, no es más que kubeadm dentro de un contenedor.