Estándares de Etiquetado (K8s Labels)

Resumen Ejecutivo

Este estándar define la taxonomía de etiquetas (labels) para todos los recursos de Kubernetes en HERA, vinculando la identidad técnica con el contexto de negocio.

• Gobernanza Basada en Metadatos: Traduce automáticamente el product-manifest.yml en etiquetas persistentes, permitiendo auditorías y reportes de costos granulares.
• Interoperabilidad de Industria: Adopta las etiquetas estándares app.kubernetes.io/* para garantizar la compatibilidad con herramientas de la comunidad (Helm, dashboards, CLI).
• Automatización de Operaciones: Facilita el filtrado dinámico en logs y métricas, permitiendo a los equipos de SRE y Seguridad identificar el impacto de un incidente por dominio, marca o criticidad en segundos.

En Kubernetes, las Labels (etiquetas) son el mecanismo principal para organizar y seleccionar grupos de objetos. En HERA, el etiquetado no es opcional ni arbitrario: es el puente que conecta un recurso técnico (como un Pod o un Service) con su identidad en la organización (dominio, producto, responsable).

---

1. Mapeo del product-manifest.yml

La fuente de verdad para el etiquetado es el archivo product-manifest.yml de cada repositorio. El pipeline de CI/CD inyecta estos valores como etiquetas en los manifiestos de Kubernetes durante la fase de despliegue.

Etiquetas de Negocio (Prefijo hera.grupoherdez.com/)

Estas etiquetas permiten segmentar los recursos según la estructura organizacional de Grupo Herdez. Los valores se derivan del product-manifest.yml canónico.

Etiqueta	Origen en Manifiesto	Ejemplo	Propósito
hera.grupoherdez.com/domain	product.domain	ecommerce	Atribución de costos y reportes ejecutivos
hera.grupoherdez.com/product	product.name	tienda-herdez	Identificación del producto raíz
hera.grupoherdez.com/brand	product.brand	grupo-herdez	Segmentación por marca comercial
hera.grupoherdez.com/criticality	classification.criticality	critical	Priorización en respuesta a incidentes y DR (valores permitidos: low, medium, high, critical)
hera.grupoherdez.com/data-classification	classification.data_classification	confidential	Aplicación de políticas de seguridad y DLP (valores permitidos: public, internal, confidential, restricted)
hera.grupoherdez.com/partner	partner	interno	Identificación de autoría (equipo interno o partner)

---

2. Etiquetas Estándares de Kubernetes

HERA adopta las etiquetas recomendadas por la comunidad de Kubernetes (app.kubernetes.io/) para garantizar que las herramientas de terceros funcionen correctamente.

Etiqueta	Valor sugerido	Ejemplo
app.kubernetes.io/name	Nombre del servicio	backend-checkout-service
app.kubernetes.io/instance	Nombre único de la instancia	checkout-v1
app.kubernetes.io/version	Versión semántica (SemVer)	1.2.3
app.kubernetes.io/component	Capa de la arquitectura	backend, frontend, database
app.kubernetes.io/part-of	Nombre del producto	tienda-herdez
app.kubernetes.io/managed-by	Herramienta de despliegue	hera-pipeline, helm, argocd

---

3. Reglas de Implementación

Casing y Formato

1. Lowercase estricto: Todas las etiquetas deben estar en minúsculas.
2. Separadores: Usar guiones - para separar palabras, nunca guiones bajos _ ni espacios.
3. Longitud: No exceder los 63 caracteres (límite técnico de K8s).
4. Caracteres permitidos: [a-z0-9], guiones -, puntos . y el prefijo de dominio.

Herencia y Propagación

Las etiquetas deben definirse en el nivel más alto posible y propagarse automáticamente:

• Deployment/StatefulSet: Las etiquetas en metadata.labels deben replicarse en spec.template.metadata.labels para que los Pods las hereden.
• Services: El spec.selector debe usar un subconjunto mínimo de etiquetas (usualmente app.kubernetes.io/name e instance) para encontrar los Pods.
• Ingress: Debe incluir las etiquetas de negocio para que el Balanceador de Carga de GCP pueda reportar costos correctamente.

---

4. Ejemplo de Aplicación

A continuación se muestra cómo debe verse un manifiesto de un servicio estándar en HERA:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend-checkout-service
  namespace: tienda-herdez
  labels:
    # Etiquetas de negocio HERA
    hera.grupoherdez.com/domain: ecommerce
    hera.grupoherdez.com/product: tienda-herdez
    hera.grupoherdez.com/brand: grupo-herdez
    hera.grupoherdez.com/criticality: critical
    hera.grupoherdez.com/data-classification: restricted
    # Etiquetas estándares K8s
    app.kubernetes.io/name: backend-checkout-service
    app.kubernetes.io/instance: checkout-prod
    app.kubernetes.io/version: "1.2.3"
    app.kubernetes.io/component: backend
    app.kubernetes.io/part-of: tienda-herdez
    app.kubernetes.io/managed-by: hera-pipeline
spec:
  replicas: 3
  selector:
    matchLabels:
      app.kubernetes.io/name: backend-checkout-service
  template:
    metadata:
      labels:
        # Los Pods deben heredar todas las labels del Deployment
        app.kubernetes.io/name: backend-checkout-service
        app.kubernetes.io/instance: checkout-prod
        # ... resto de etiquetas de negocio

---

5. Casos de Uso y Beneficios Operativos

Búsqueda y Filtrado en CLI

Con un etiquetado correcto, puedes realizar consultas potentes en segundos:

# Ver todos los pods del dominio 'ecommerce' en todos los namespaces
kubectl get pods -A -l hera.grupoherdez.com/domain=ecommerce

# Listar servicios críticos (tier-1) que tienen errores
kubectl get pods -l hera.grupoherdez.com/criticality=tier-1 --field-selector status.phase!=Running

Observabilidad en Cloud Logging

En Google Cloud Logging, puedes filtrar logs por etiquetas de negocio para entender el comportamiento de una marca específica o detectar anomalías en servicios que manejan datos confidenciales.

resource.labels.namespace_name="tienda-herdez"
labels."hera.grupoherdez.com/data-classification"="restricted"

Validación en Code Review

Al revisar un Merge Request, asegúrate de que las etiquetas de negocio coincidan con lo declarado en el product-manifest.yml. Una discrepancia aquí rompe la trazabilidad de costos y la observabilidad de la plataforma.

---

6. Checklist de Cumplimiento para Code Review

Esta checklist es obligatoria en todo MR que agregue o modifique manifiestos Kubernetes con etiquetas. Todo item debe estar marcado ✅ antes del merge a develop.

Etiquetas de negocio

• Todos los recursos tienen las 6 etiquetas de negocio del prefijo hera.grupoherdez.com/: domain, product, brand, criticality, data-classification, partner
• Los valores de cada etiqueta coinciden exactamente con lo declarado en el product-manifest.yml del repo (no se inventan valores locales)
• criticality usa uno de los valores permitidos: low, medium, high, critical
• data-classification usa uno de los valores permitidos: public, internal, confidential, restricted
• Los valores son lowercase y usan guiones como separador (nunca underscores ni espacios)

Etiquetas estándar de Kubernetes

• Todos los recursos incluyen las 6 etiquetas app.kubernetes.io/*: name, instance, version, component, part-of, managed-by
• app.kubernetes.io/name coincide con el nombre del deployment (patrón <tipo>-<detalle>)
• app.kubernetes.io/part-of coincide con el nombre del producto (el mismo valor del K8s namespace)
• app.kubernetes.io/version usa SemVer (1.2.3) entre comillas para forzar parsing como string
• app.kubernetes.io/managed-by identifica la herramienta real (hera-pipeline, helm, argocd)

Herencia y consistencia

• Las etiquetas del Deployment.metadata.labels se replican en spec.template.metadata.labels para que los Pods las hereden
• Los Services usan un subconjunto mínimo de etiquetas en spec.selector (típicamente app.kubernetes.io/name + instance), no la lista completa
• Los recursos asociados (Ingress, HPA, PDB, NetworkPolicy) usan las mismas etiquetas de negocio que el Deployment al que aplican

Formato

• Ninguna etiqueta excede 63 caracteres (límite técnico de K8s)
• Ninguna etiqueta contiene caracteres fuera de [a-z0-9\-\.] + el separador / del prefijo de dominio
• Los valores con versión entre comillas ("1.2.3") para evitar que YAML los interprete como float

---

7. Anti-Patterns Bloqueados

Estos patrones están explícitamente prohibidos y bloquean el merge en code review:

#	Anti-pattern	Por qué es malo	Qué hacer en su lugar
1	❌ Etiquetas inventadas locales	Rompe la trazabilidad de costos y la observabilidad centralizada	Usar solo las 6 etiquetas de negocio y las 6 app.kubernetes.io/* definidas aquí
2	❌ Valores que no coinciden con product-manifest.yml	El pipeline de CI/CD valida este matching — el MR falla	Leer los valores del manifest, nunca hardcodearlos en el manifiesto K8s
3	❌ criticality: tier-1 u otras taxonomías	La taxonomía oficial es low/medium/high/critical — tier-1 no existe en HERA	Usar critical para servicios críticos del negocio
4	❌ Etiquetas con mayúsculas, guiones bajos o espacios	K8s las acepta pero la convención HERA es lowercase + guiones	hera.grupoherdez.com/data-classification, nunca hera.grupoherdez.com/Data_Classification
5	❌ Etiquetas del Deployment sin replicar en los Pods	Los Pods quedan sin trazabilidad — no aparecen en queries por criticidad ni en reportes de costos por dominio	Replicar las mismas etiquetas en spec.template.metadata.labels
6	❌ Versiones sin quotes (version: 1.2.3)	YAML interpreta 1.2.3 como multi-dot que algunos parsers rompen	Siempre entre comillas: version: "1.2.3"
7	❌ part-of apuntando a otro nombre	Rompe la agrupación por producto en dashboards y queries	part-of siempre es el nombre del producto (= nombre del namespace)
8	❌ Etiquetas mezcladas en el mismo recurso con prefijos distintos (ej. hera.grupoherdez.com/ + hera.cloudherdez.com/)	Confunde la gobernanza; dos prefijos para el mismo propósito	Solo hera.grupoherdez.com/ para labels de negocio. Otros prefijos requieren aprobación de Arquitectura

---

8. Estándares Relacionados

Este estándar forma parte del conjunto de convenciones de configuración y naming del ecosistema HERA. Consulta también:

• Estándares de Configuración y Variables de Entorno — modelo Context-Aware Naming de 5 capas, reglas R1–R12 para env vars, naming de K8s Secrets y GCP Secret Manager
• Estándares de Nombramiento en GCP — convención para Service Accounts, Cloud Storage, Cloud SQL, Artifact Registry y Pub/Sub
• Estructura de Repositorios GitLab — fuente de verdad del product-manifest.yml y la taxonomía de atributos