Cerrábamos la lección anterior señalando un hilo suelto que ha recorrido todo el módulo. El selector de un ReplicaSet que adopta pods, el selector de un Service que encuentra sus destinos, la etiqueta entorno con la que las políticas de red seleccionarán namespaces, la anotación kubernetes.io/change-cause que documenta cada revisión, el pod-template-hash que el Deployment añade por su cuenta, y todas las consultas con -l que llevamos usando desde la primera lección: todo eso son etiquetas y anotaciones. Las hemos ido usando por necesidad, sin sistematizar. Esta lección pone orden, y no es un asunto menor: en un clúster con seis componentes por tres entornos, el esquema de etiquetado es lo que separa una plataforma navegable de un caos de objetos anónimos. Verás la diferencia exacta entre etiqueta y anotación, la sintaxis y las restricciones de claves y valores, las etiquetas recomendadas por Kubernetes y cómo se concretan en el esquema oficial de Rutas Norte, los selectores de igualdad y de conjunto en todas sus formas, quién los consume, por qué el selector de un Deployment es inmutable, el uso real de las anotaciones y las consultas del día a día que te harán productivo.

1. Etiquetas frente a anotaciones
2. Sintaxis y restricciones de claves y valores
3. Las etiquetas recomendadas por Kubernetes
4. El esquema de etiquetado de Rutas Norte
5. Selectores de igualdad
6. Selectores de conjunto
7. Selectores en manifiestos: matchLabels y matchExpressions
8. Quién consume selectores
9. La regla de oro: el selector de un Deployment es inmutable
10. Anotaciones en la práctica
11. kubectl label y kubectl annotate
12. Consultas útiles del día a día

Ambas viven en metadata y ambas son pares clave-valor. Ahí termina el parecido.

La regla de decisión, que resuelve el 100 % de las dudas:

¿Vas a querer buscar objetos por este dato, o va a servirle a un selector? Es una etiqueta. ¿Es información que se lee pero no se busca? Es una anotación.

Ejemplos aplicados a Rutas Norte:

Kubernetes es estricto con el formato, y conocer las reglas evita rechazos incomprensibles.

Una clave tiene un nombre y, opcionalmente, un prefijo separado por /:

Reglas del nombre (la parte obligatoria):

• Máximo 63 caracteres.
• Debe empezar y terminar por carácter alfanumérico.
• Puede contener -, _, . y alfanuméricos en medio.

Reglas del prefijo (opcional):

• Debe ser un subdominio DNS válido: rutasnorte.example, app.kubernetes.io.
• Máximo 253 caracteres.
• Se separa del nombre con /.
• Reservados: los prefijos kubernetes.io/ y k8s.io/ están reservados para el propio Kubernetes y sus componentes principales. No los uses para tus etiquetas.

• Máximo 63 caracteres (o vacío, que es válido).
• Si no está vacío, debe empezar y terminar por alfanumérico.
• Solo alfanuméricos, -, _ y . en medio.
• Prohibidos: espacios, /, :, @, acentos, ñ, emojis.

Ejemplos válidos e inválidos:

Comprueba el rechazo tú mismo:

La versión correcta usa una anotación:

Las claves siguen las mismas reglas que las de las etiquetas. Los valores, en cambio, son casi libres: cualquier cadena, incluidos JSON, saltos de línea y caracteres especiales, con un límite conjunto de 256 KiB para todas las anotaciones de un objeto.

Ese límite generoso es el que permite que kubectl apply guarde el manifiesto completo en kubectl.kubernetes.io/last-applied-configuration, como vimos en Objetos y Manifiestos.

Kubernetes define un conjunto de etiquetas comunes bajo el prefijo app.kubernetes.io/. No son obligatorias ni las impone nada, pero son el vocabulario compartido que entienden Helm, Kustomize, Argo CD, Prometheus y prácticamente cualquier herramienta del ecosistema.

La diferencia entre name e instance es la que más cuesta:

• name es qué es: postgres. La misma en todas las instalaciones.
• instance es cuál es: postgres-reservas-pro. Distingue dos instalaciones de lo mismo.

Si Rutas Norte tuviera dos bases de datos PostgreSQL —una de reservas y otra de facturación—, ambas llevarían name: postgres pero instance: postgres-reservas y instance: postgres-facturacion.

Un ejemplo completo con las seis:

Nota práctica: version: "2.5.0" va entre comillas. Sin ellas, YAML podría interpretar valores como 1.0 como número y provocar un error de tipo, ya que los valores de etiqueta deben ser cadenas.

Un aviso importante que enlaza con el apartado 9: app.kubernetes.io/version no debe ir en el selector. Si estuviera, al cambiar de versión el selector dejaría de casar con sus propios pods, y como el selector es inmutable, tendrías que recrear el Deployment en cada despliegue. La versión es informativa; la identidad la dan name e instance.

Ha llegado el momento de fijar el esquema definitivo del proyecto. Hasta ahora hemos usado tres etiquetas mínimas (app, app.kubernetes.io/part-of y entorno); las consolidamos y las ampliamos.

La regla de oro del esquema, que se deriva de todo lo aprendido en el módulo:

Solo app y entorno entran en los selectores. Son las dos únicas etiquetas que identifican al componente de forma inequívoca y que no cambian nunca.

Todo lo demás —versión, componente, criticidad, gestor— es informativo y puede cambiar sin recrear nada.

Así queda api-reservas con el esquema completo aplicado:

Repara en la asimetría, que es exactamente la que aprendimos con los ReplicaSets: el template lleva nueve etiquetas y el selector solo exige dos. Está permitido y es lo correcto: el selector debe ser un subconjunto mínimo y estable; las demás etiquetas viajan con los pods para poder consultarlos.

Aplícalo y observa la potencia inmediata:

Un selector es una consulta sobre etiquetas. El tipo más simple compara valores.

Se usan con -l (o --selector), y varias condiciones separadas por comas se combinan con Y lógico:

Un detalle sobre != que conviene conocer: también selecciona los objetos que no tienen esa etiqueta en absoluto. entorno!=pro devuelve tanto los de dev y pre como los que carecen de la etiqueta entorno.

No existe el O lógico en los selectores de igualdad. Para eso están los de conjunto.

Más expresivos. Operan sobre conjuntos de valores y sobre la existencia de la clave.

Ejemplos aplicados:

Nota sobre las comillas: los selectores de conjunto llevan paréntesis y espacios, que la shell interpretaría. Enciérralos siempre entre comillas simples.

Y se pueden combinar con los de igualdad, separando por comas:

Dentro de un YAML, los selectores tienen dos formas equivalentes a las dos familias que acabas de ver.

Es un mapa: todas las claves deben coincidir (Y lógico). Es lo que hemos usado en todo el módulo.

Se pueden usar los dos a la vez; todas las condiciones se combinan con Y lógico:

Traducción: "pods con app=api-reservas y con entorno igual a pre o a pro".

Atención a la excepción del Service, que ya vimos en su lección y conviene recordar aquí porque es una asimetría real de la API:

El motivo es histórico: los Services son del grupo core v1, anterior al selector enriquecido, y solo soportan igualdad.

Los selectores no son solo para consultas manuales. Son el mecanismo de acoplamiento de todo Kubernetes: la forma en que unos objetos encuentran a otros sin conocer sus nombres.

La lección de fondo: las etiquetas de un pod no son decoración, son su interfaz con el resto del sistema. Cambiar una etiqueta de un pod puede sacarlo de un Service, dejarlo fuera de una política de red o hacerlo invisible para su ReplicaSet. Lo veremos en el ejercicio 3.

Compruébalo:

Lo mismo ocurre con ReplicaSets, StatefulSets y DaemonSets. Los Services son la excepción: su selector sí se puede modificar, y eso los convierte en la herramienta de las estrategias blue-green del módulo 11.

La razón es la seguridad de los datos... de los pods. Imagina que se permitiera cambiarlo:

1. El Deployment tiene selector: app=api-reservas y gobierna 4 pods con esa etiqueta.
2. Cambias el selector a app=api-reservas-v2.
3. Instantáneamente, los 4 pods dejan de casar. Se convierten en huérfanos, exactamente como los del experimento --cascade=orphan de la lección de ReplicaSets.
4. El Deployment cuenta 0 pods propios y crea 4 nuevos.
5. Resultado: 8 pods corriendo, 4 de ellos sin controlador, invisibles para el Deployment, consumiendo recursos y sin nadie que los actualice ni los recupere si caen.

Peor aún: si el Service seguía apuntando a app=api-reservas, esos 4 huérfanos seguirían recibiendo tráfico de producción sin que ningún controlador los vigile.

Kubernetes prefiere fallar al aplicar antes que dejarte llegar a ese estado.

Hay dos caminos, y el primero es el bueno:

Camino A: sustituir el controlador sin cortar el servicio.

Camino B: nombre nuevo y transición por el Service. Se crea un Deployment con otro nombre y el selector correcto, se espera a que esté listo y se cambia el selector del Service para que apunte a los pods nuevos. Es, en esencia, un despliegue blue-green (11-04).

Piensa bien el selector antes del primer apply. Es la decisión menos reversible de un manifiesto.

Y de ahí la regla del proyecto que ya conoces: en el selector, solo app y entorno. Nunca la versión, nunca el gestor, nunca la criticidad, nunca part-of. Todo lo que pueda cambiar con el tiempo se queda fuera.

Las anotaciones parecen menos importantes que las etiquetas hasta que descubres cuántas cosas funcionan gracias a ellas.

Este es el uso más potente: muchos controladores se configuran mediante anotaciones, no mediante campos del spec. El caso paradigmático es el controlador de Ingress:

Ninguna de esas líneas está en el esquema del Ingress: son instrucciones que el controlador de NGINX y cert-manager leen y aplican. El motivo de este diseño es que cada implementación de Ingress tiene capacidades distintas, y la API estándar no puede cubrirlas todas. Se estudian en Controladores de Ingress y TLS y Certificados.

Y el uso más simple y más rentable: información que salva una guardia nocturna.

Fíjate en dos cosas imposibles con etiquetas: valores con @, : y /, y un valor multilínea. Esa es la razón de que existan las anotaciones.

A las tres de la madrugada, esto vale su peso en oro:

Jamás guardes contraseñas, tokens, claves de API ni certificados privados en anotaciones.

Los motivos:

• Se leen en claro con kubectl get -o yaml o kubectl describe, que suelen ser permisos ampliamente concedidos.
• Aparecen en los logs: cualquier volcado de un objeto las incluye.
• Se copian a last-applied-configuration, quedando duplicadas.
• Se van a los backups y a las herramientas de GitOps, propagándose por todas partes.
• No se cifran en reposo dentro de etcd salvo que el clúster lo tenga configurado, y aun así el mecanismo está pensado para Secrets.

Lo mismo vale para las etiquetas, con el agravante de que además son indexadas y consultables.

Para eso están los Secrets, en la lección 03-02, y su gestión segura en el módulo 8. Ese POSTGRES_PASSWORD en claro que dejamos en el Deployment provisional de postgres-reservas es exactamente la deuda que vamos a pagar en el módulo siguiente.

Ambos comandos comparten sintaxis.

Si la clave ya existe, el comando falla salvo que lo indiques:

Es una protección deliberada contra pisar sin querer una etiqueta que algún selector esté usando.

Ese guion final es fácil de pasar por alto al leer un script. Recuérdalo: clave con guion al final significa borrar.

Advertencia de seguridad: --all combinado con --overwrite sobre una etiqueta que aparece en algún selector puede sacar pods de su Service o de su ReplicaSet en el acto. Prueba siempre primero con --dry-run=server:

Cambiar una etiqueta con kubectl label sobre un pod gestionado por un Deployment no sobrevive: en el próximo despliegue, los pods se recrean a partir del template y el cambio desaparece. Para que perdure, edita spec.template.metadata.labels en el manifiesto.

Y hay un efecto secundario mucho más grave, que exploraremos en el ejercicio 3: si cambias una etiqueta que está en el selector del ReplicaSet, el pod queda huérfano al instante y el ReplicaSet crea otro para sustituirlo.

Aquí es donde el esquema de etiquetado deja de ser burocracia y se convierte en productividad. Las consultas más rentables combinan -l con los formatos de salida que vimos en La CLI de Kubernetes.

Truco de sintaxis importante: en custom-columns, los puntos que forman parte de la clave de la etiqueta hay que escaparlos con \.. Si no, kubectl los interpreta como separadores de ruta JSONPath y no encuentra nada.

La consulta que más veces te pedirán:

Encontrar lo que incumple la convención del proyecto:

Ese --dry-run=client antes de un delete masivo es un hábito que conviene adquirir.

El flag -L (ele mayúscula) es un pequeño tesoro: añade columnas con el valor de las etiquetas indicadas, sin filtrar nada.

• Meter la versión en el selector. Al desplegar una versión nueva el selector deja de casar, y como es inmutable, te obliga a recrear el Deployment. El selector solo lleva app y entorno.
• Selectores demasiado amplios. Un app.kubernetes.io/part-of: rutas-norte como selector adopta y puede borrar pods de otros componentes, como vimos en ReplicaSets.
• Usar caracteres prohibidos en valores de etiqueta. Nada de @, :, /, espacios ni tildes. Si el dato los necesita, es una anotación.
• Usar el prefijo kubernetes.io/ para etiquetas propias. Está reservado. Usa el dominio de tu organización: rutasnorte.example/.
• Guardar secretos en anotaciones o etiquetas. Se leen en claro con describe, viajan a los backups y acaban en Git. Van en Secrets.
• Poner las etiquetas solo en metadata y no en spec.template.metadata. Los pods heredan las del template, no las del Deployment. Es el error que rompe los Services.
• Olvidar --overwrite y pensar que el comando ha funcionado. kubectl label falla si la clave existe. Lee siempre la salida.
• Cambiar con kubectl label una etiqueta que está en un selector. El pod queda huérfano y el controlador crea otro. Puede duplicar capacidad sin que te enteres.
• Esperar que un cambio con kubectl label sobre un pod perdure. Se pierde en el próximo despliegue. Edita el template.
• Olvidar las comillas simples en selectores de conjunto. Los paréntesis y espacios los interpreta la shell.
• No escapar los puntos de las claves en custom-columns. app.kubernetes.io/version debe escribirse app\.kubernetes\.io/version.
• Consejo: define el esquema de etiquetado antes de desplegar nada. Añadirlo después implica editar todos los manifiestos y, si toca selectores, recrear objetos.
• Consejo: kubectl get pods -A -L entorno,app te da una vista tabulada de toda la plataforma sin filtrar. Es la consulta con la que empezar cualquier revisión.
• Consejo: documenta el esquema en k8s/README.md del repositorio. Un esquema que solo conoce quien lo diseñó no es un esquema.

1. Actualiza k8s/base/tienda-web-deployment.yaml para que el Deployment y su template lleven las ocho etiquetas del esquema de Rutas Norte (app, entorno, las cinco de app.kubernetes.io/ y criticidad), y cuatro anotaciones: responsable, panel, runbook y change-cause.
2. Asegúrate de que el selector sigue teniendo solo app y entorno, y explica en dos líneas por qué.
3. Aplícalo y demuestra con un comando que los pods llevan las ocho etiquetas.
4. Recupera la URL del runbook con un solo comando.

Con los tres entornos desplegados, escribe el comando exacto para cada pregunta:

1. Todos los pods de la plataforma en pre o pro, en cualquier namespace.
2. Todos los Deployments de la plataforma que no son de desarrollo.
3. Los pods de componentes con criticidad critica o alta que no están en estado Running.
4. Una tabla con entorno, componente, versión y nodo de todos los pods de la plataforma.
5. Los Deployments a los que les falta la etiqueta rutasnorte.example/criticidad (auditoría del esquema).
6. Todos los pods, sin filtrar, mostrando entorno y app.kubernetes.io/component como columnas adicionales.

Este ejercicio demuestra por qué las etiquetas son la interfaz de un pod con el resto del sistema. Trabaja en rutas-norte-dev con el Deployment de tienda-web (3 réplicas) y su Service.

1. Anota cuántos pods hay y cuántos endpoints tiene el Service.
2. Elige un pod y cámbiale la etiqueta app a tienda-web-aislado con kubectl label --overwrite.
3. Observa inmediatamente: ¿cuántos pods hay ahora? ¿Qué ha hecho el ReplicaSet? ¿Sigue vivo el pod modificado? ¿Quién es su dueño?
4. Comprueba cuántos endpoints tiene ahora el Service y explica por qué.
5. Explica para qué sirve esta técnica en el mundo real y qué peligro tiene.
6. Deja el clúster como estaba.

Solución 1

2. El selector lleva solo app y entorno porque es inmutable y debe identificar al componente de forma estable. Si incluyera app.kubernetes.io/version, al desplegar la 1.9.0 el selector dejaría de casar con los pods nuevos, y como no se puede modificar, habría que borrar y recrear el Deployment en cada despliegue. Además, un selector mínimo evita el riesgo de adopciones indebidas si otro objeto comparte etiquetas informativas.

Las ocho del esquema, más el pod-template-hash que añade el Deployment.

Solución 2

Nota sobre la pregunta 3: -l filtra por etiquetas y --field-selector por campos del objeto. Son mecanismos distintos y complementarios; los campos disponibles para --field-selector son limitados (status.phase, spec.nodeName, metadata.name, metadata.namespace y poco más).

Solución 3

3 pods, 3 endpoints.

Ahora hay 4 pods. Lo ocurrido, paso a paso:

• Al cambiar app de tienda-web a tienda-web-aislado, el pod dejó de casar con el selector del ReplicaSet.
• En la siguiente vuelta de su bucle de reconciliación, el ReplicaSet contó 2 pods propios donde debía haber 3 y creó uno nuevo (h7pnk, con 4 segundos de edad).
• El pod modificado sigue vivo, pero ha quedado huérfano: ningún controlador lo vigila.

Salida vacía: no tiene dueño. Kubernetes le retiró el ownerReferences al dejar de casar con el selector.

Siguen siendo 3, pero uno ha cambiado. El pod aislado (10.244.0.81) ha salido del Service porque su selector también exige app=tienda-web; en su lugar ha entrado el pod nuevo (10.244.0.87). El pod huérfano ya no recibe tráfico aunque siga perfectamente vivo y sano.

5. Para qué sirve en el mundo real: es la técnica clásica de aislamiento para depuración en producción. Si uno de cinco pods presenta un comportamiento anómalo —una fuga de memoria, respuestas erráticas, un log sospechoso—, cambiarle una etiqueta del selector lo saca del Service y del ReplicaSet en un instante. Deja de recibir tráfico de clientes reales, el ReplicaSet crea un sustituto para no perder capacidad, y tú conservas el pod intacto, con su memoria y su estado, para inspeccionarlo con calma: kubectl exec, kubectl logs, volcados, perfilado. No hay que reproducir el problema en un entorno de pruebas: tienes el paciente vivo sobre la mesa.

   El peligro es doble. Primero, ese pod ya no lo gestiona nadie: si el nodo cae o alguien lo desaloja, desaparece sin sustituto, y sobre todo es fácil olvidarse de él, consumiendo CPU y memoria indefinidamente. Segundo, si el cambio de etiqueta se hace por error o en el sentido contrario —dar a un pod suelto las etiquetas de un componente gobernado—, provocas la adopción y el posible borrado inmediato que vimos en la lección de ReplicaSets. La disciplina obligatoria es etiquetar el pod aislado con la fecha y el motivo, y borrarlo al terminar:

Tres pods, tres endpoints, todo en orden. Y date cuenta de que al borrar el huérfano no apareció ningún sustituto: el ReplicaSet ya tenía sus tres pods y ese no era suyo.

Cierras el módulo 2 con el hilo que lo recorría entero convertido en sistema. Sabes distinguir sin dudar una etiqueta de una anotación: las primeras identifican y se consultan, están indexadas, tienen 63 caracteres y un juego de caracteres restringido; las segundas adjuntan información que se lee pero no se busca, admiten hasta 256 KiB y cualquier contenido, incluidos JSON y texto multilínea. Conoces la sintaxis completa de claves y valores, sabes que kubernetes.io/ es un prefijo reservado y que el dominio de tu organización es el sitio correcto para lo propio, y dominas las seis etiquetas recomendadas por Kubernetes, incluida la distinción entre name (qué es) e instance (cuál es).

Has fijado el esquema de etiquetado definitivo de Rutas Norte para sus seis componentes y sus tres entornos, con su regla de oro: solo app y entorno entran en los selectores, porque el selector de un Deployment es inmutable y meter en él la versión te condenaría a recrear el objeto en cada despliegue. Manejas las dos familias de selectores —igualdad con =, == y !=; conjuntos con in, notin, exists y su negación— tanto en la línea de comandos con -l como en los manifiestos con matchLabels y matchExpressions, sin olvidar la asimetría de los Services, que solo admiten mapa plano. Sabes quién consume selectores, que son casi todos: ReplicaSets, Deployments, Services, NetworkPolicies, PodDisruptionBudgets, afinidad y las herramientas de monitorización. Usas las anotaciones para lo que sirven —documentar el cambio, configurar controladores de Ingress, dejar el runbook y el teléfono de guardia a mano— sin cometer jamás el error de guardar en ellas un secreto. Y tienes en el cinturón kubectl label y kubectl annotate con --overwrite y el borrado con guion final, más el repertorio de consultas que convierte un clúster grande en algo navegable.

Con esto cierras el módulo 2 y la plataforma Rutas Norte ya está viva. tienda-web pasó de ser aquel pod frágil del módulo 1 a un Deployment de tres réplicas que se recupera solo; api-reservas, redis-cache y worker-notificaciones tienen los suyos; los cuatro componentes que reciben conexiones tienen una dirección estable con balanceo entre réplicas; sabes desplegar sin corte de servicio y deshacer un despliegue roto en menos de un minuto; tienes tres entornos separados en namespaces con el mismo manifiesto desplegado en varios de ellos; y todo está etiquetado con un esquema coherente que las lecciones siguientes van a explotar.

Pero hay deudas pendientes muy visibles. La contraseña de PostgreSQL sigue escrita en claro dentro de un manifiesto que está en Git, y esa base de datos guarda el nombre, el DNI, el teléfono y el correo de cada cliente de Rutas Norte. La URL de la API va incrustada en la imagen en lugar de inyectarse según el entorno. Ningún namespace tiene cuota, así que un error en desarrollo puede dejar sin recursos a producción. Y todos nuestros pods declaran requests y limits a ojo, sin criterio. El módulo 3, Gestión de Configuración y Secretos, ataca exactamente eso: separaremos la configuración del código con ConfigMaps, sacaremos las credenciales de los manifiestos con Secrets, inyectaremos ambos como variables de entorno, pondremos cuotas y límites a cada entorno, entenderemos las clases de calidad de servicio que deciden qué pod muere primero cuando falta memoria, y daremos a cada componente su propia identidad ante la API con ServiceAccounts.