Golden Pipeline — Template CI/CD Centralizado

Resumen Ejecutivo

El Golden Pipeline es el template CI/CD centralizado que estandariza cómo se construyen, validan, aseguran y despliegan los 800+ servicios de HERA.

• Valor: Un solo template mantiene la consistencia de 800 servicios. Las actualizaciones se aplican centralmente, los proyectos las adoptan a su ritmo vía SemVer.
• Eficiencia: El desarrollador configura 2 archivos YAML (product-manifest.yml + service-manifest.yml) y el pipeline genera automáticamente labels, resources, Workload Identity, KEDA y Helm values.
• Riesgo sin esto: Cada equipo inventa su propio pipeline, las herramientas de seguridad se configuran de forma inconsistente, las actualizaciones se aplican de forma manual a 800 repos.

---

Flujo del Golden Pipeline

Golden Pipeline HERA — Flujo End-to-End

1

Init

Lee manifiestos

product-manifest.yml service-manifest.yml

2

Validate

JSON Schema

Gate

3

Build

Por tech_stack

Docker image

4

Security

Feature flags

SAST SCA Secrets

5

Deploy

Helm + values

Labels HERA Resources WI

6

Post-Deploy

KEDA + Observatory

ScaledObject Metrics

---

1. Arquitectura del repositorio de templates

El template vive en un repositorio centralizado gestionado por el equipo de plataforma:

grupo-herdez/platform/pipelines/gitlab-ci/
├── base/
│   ├── stages.yml                 ← 6 etapas estándar + post-deploy
│   ├── rules.yml                  ← Reglas comunes de ejecución
│   └── init-manifest.yml          ← Lee product-manifest + service-manifest
├── validate/
│   ├── schema-validation.yml      ← Valida manifiestos contra JSON Schema
│   └── schemas/
│       ├── product-manifest.schema.json
│       └── service-manifest.schema.json
├── stacks/
│   ├── nodejs.yml
│   ├── dotnet.yml
│   ├── python.yml
│   ├── php.yml
│   └── java.yml
├── security/
│   ├── sonarqube.yml              ← SAST (default: ON)
│   ├── docker-scout.yml           ← SCA (default: ON)
│   ├── trufflehog.yml             ← Secrets (siempre ON, sin flag)
│   ├── veracode.yml               ← Solo CDE (default: OFF)
│   └── zap-dast.yml               ← DAST post-deploy en QA
├── deploy/
│   ├── helm-gke.yml               ← Deploy + generación de values
│   └── keda-config.yml            ← ScaledObject para DEV/QA
├── observability/
│   ├── version-check.yml          ← Warning si template desactualizado
│   └── pipeline-metrics.yml       ← Reporta al Pipeline Observatory
├── CHANGELOG.md
└── README.md

El equipo de plataforma es el único que modifica este repositorio. Los equipos de desarrollo lo consumen, no lo modifican.

---

2. Versionado y rollback

Tags semánticos

Cada release es un tag que sigue SemVer:

Tipo	Cuándo	Ejemplo
Major (breaking)	Nueva etapa, cambio de schema de manifiesto	v3.0.0
Minor (feature)	Nueva herramienta, nuevo stack soportado	v2.1.0
Patch (fix)	Corrección de bug en un job existente	v2.1.1

Tag stable para rollback centralizado

Además de los tags numéricos, existe un tag stable que el equipo de plataforma controla:

Tag	Apunta a	Quién lo mueve	Uso
stable	Última versión validada	Solo plataforma	Default para el 90% de proyectos
latest	Última versión publicada	Automático con cada release	Solo pilotos
vX.Y.Z	Versión específica	Inmutable	Proyectos que necesitan pin

Configuración en cada proyecto GitLab

En Settings → CI/CD → CI/CD configuration file, se configura la URL del template con el tag deseado:

<URL_GITLAB>/<GRUPO>/templates/gitlab-ci/-/raw/stable/.gitlab-ci.yml

Donde <URL_GITLAB> es la URL de la instancia GitLab corporativa y <GRUPO> es el grupo raíz de HERA.

Flujo de rollback

Si una versión nueva tiene un bug:

1. Plataforma detecta el problema en la versión v2.2.0
2. Mueve el tag stable a la versión anterior: v2.1.0
3. Los proyectos que apuntan a stable vuelven a la versión funcional automáticamente en su siguiente ejecución
4. Los pilotos en v2.2.0 explícito no se afectan — pueden decidir si regresan o esperan el fix

Nunca apuntar a main en producción

Apuntar el CI/CD configuration file a raw/main/... significa que cualquier commit en el template impacta inmediatamente a todos los proyectos sin validación. Siempre usar stable o un tag explícito.

---

3. Manifiestos como fuente de verdad

HERA define dos manifiestos YAML que el pipeline consume como contrato declarativo: uno por producto (product-manifest.yml) y uno por servicio (service-manifest.yml). El portal documenta su schema como contrato; el YAML canónico (con valores de ejemplo) vive en los templates oficiales.

Templates canónicos

Los manifiestos se forkean desde grupo-herdez/platform/templates/manifests/ (product-manifest.yml y service-manifest.yml). El portal no duplica el YAML completo — publica el schema aquí y evita el drift.

product-manifest.yml — en _shared/ del producto

Define la identidad, clasificación y configuración que aplica a todos los servicios del producto.

Ubicación en el repo: grupo-herdez/products/<dominio>/<producto>/_shared/product-manifest.yml

Schema del product-manifest.yml

Campo	Tipo / Formato	Obligatorio	Descripción
product.name	kebab-case, lowercase	✅	Nombre canónico del producto (p. ej. tienda-herdez)
product.domain	enum de dominios de negocio	✅	ecommerce, marketing, supply-chain, sitios, integracion, cms, datos, apps, shared-services
product.brand	enum de marcas	✅	grupo-herdez, barcel, donamaria, corporativo, interno
product.owner.tech_lead	email corporativo	✅	Responsable técnico del producto
product.owner.product_owner	email corporativo	✅	Product Owner del negocio
classification.criticality	enum	✅	Criticidad (ver Valores permitidos)
classification.data_classification	enum	✅	Sensibilidad de datos (ver Valores permitidos)
active_version	string	✅	Versión activa en PRD (determina qué subcarpeta de servicios se despliega)
partner	string	❌	Partner externo responsable (si aplica)
state	enum	✅	candidate, active-dev, active-qa, active-prd, legacy, retired
infrastructure.namespace	kebab-case	✅	Namespace Kubernetes único por producto
infrastructure.gcp_project.{dev,qa,prd}	string (ID GCP)	✅	Project GCP por ambiente, siguiendo Estándares de Naming
infrastructure.cluster.{dev,qa,prd}	string	✅	Cluster GKE por ambiente
keda.schedule.timezone	IANA timezone	❌	Zona horaria del cron (p. ej. America/Mexico_City)
keda.schedule.active_start	cron expression	❌	Inicio del horario activo (scale-up)
keda.schedule.active_end	cron expression	❌	Fin del horario activo (scale-down)
homologation	enum	✅	Nivel de homologación (gold, silver, bronze)

service-manifest.yml — en cada repo de servicio

Define la configuración específica del servicio: stack tecnológico, recursos, seguridad y probes.

Ubicación en el repo: grupo-herdez/products/<dominio>/<producto>/<version>/<servicio>/service-manifest.yml

Schema del service-manifest.yml

Campo	Tipo / Formato	Obligatorio	Descripción
service.name	kebab-case, lowercase	✅	Nombre del repo de servicio
service.category	enum cerrado de 13 valores	✅	Ver Valores permitidos — determina el pipeline y SLOs
service.layer	enum	✅	experience, domain, integration, platform
service.tech_stack	enum	✅	nodejs, dotnet, python, php, java, go — determina el pipeline base
service.talla	enum	✅	micro, estandar, intensivo — tier de consumo de recursos
resources.requests.{cpu,memory}	K8s resource string	✅	Valor generado por la Calculadora de Recursos (herramienta del ecosistema HERA)
resources.limits.{cpu,memory}	K8s resource string	✅	Valor generado por la Calculadora
scaling.hpa.min_replicas	integer ≥ 2	✅	En PRD el mínimo corporativo es 2 (HA multi-zona)
scaling.hpa.max_replicas	integer	✅	Tope superior del HPA
scaling.hpa.target_cpu	integer (porcentaje)	✅	Umbral de CPU que dispara scale-up
scaling.keda.scaler	enum	✅	cron, pubsub, prometheus, none — habilita KEDA scale-to-zero en DEV/QA
security.pci_cde	boolean	✅	true si el servicio forma parte del entorno PCI-CDE (escaneos adicionales)
security.enable_veracode	boolean	❌	Habilita Veracode SAST (servicios con requisitos regulatorios)
security.workload_identity.gsa	Google SA name	✅	Google Service Account vinculada al KSA vía Workload Identity
probes.liveness.path	HTTP path	✅	Endpoint de liveness probe
probes.liveness.initial_delay	integer (segundos)	✅	Retardo inicial antes del primer probe
probes.readiness.path	HTTP path	✅	Endpoint de readiness probe
probes.readiness.initial_delay	integer (segundos)	✅	Retardo inicial antes del primer probe

La Calculadora genera `resources` y `scaling`

La Calculadora de Recursos (herramienta del ecosistema HERA, accesible desde el menú superior del portal) genera los valores de resources y scaling automáticamente. El desarrollador no calcula CPU/RAM a mano — los copia del informe ejecutivo de la Calculadora al service-manifest.yml.

---

4. Validación con JSON Schema

El pipeline valida que los valores del service-manifest.yml pertenezcan al catálogo cerrado de HERA antes de ejecutar cualquier job. Esto evita errores como talla: grande o category: api que pasarían silenciosamente.

Valores permitidos (catálogo cerrado)

Campo	Valores válidos
service.category	frontend, bff, experience, backend, data, cms, integration, event, worker, platform, edge, infra, docs
service.layer	experience, domain, integration, platform
service.tech_stack	nodejs, dotnet, python, php, java, go
service.talla	micro, estandar, intensivo
scaling.keda.scaler	cron, pubsub, prometheus, none
classification.criticality	low, medium, high, critical
classification.data_classification	public, internal, confidential, restricted

Ejemplo de error

Si un desarrollador configura un valor inválido:

❌ service-manifest.yml inválido: 'grande' is not one of ['micro', 'estandar', 'intensivo']
   Campo: service.talla
   Valores permitidos: ['micro', 'estandar', 'intensivo']

El pipeline se detiene en la etapa Validate — no llega a build ni a deploy.

---

5. Feature flags para herramientas de seguridad

Herramienta	Control	Default	Cuándo cambia
SonarQube (SAST)	Variable de grupo	ON	Solo plataforma puede desactivar (repos de IaC/docs)
Docker Scout (SCA)	Variable de grupo	ON	Solo plataforma puede desactivar
TruffleHog (Secrets)	Sin flag	Siempre ON	Nunca desactivable — un secreto filtrado es una brecha inmediata
Veracode	security.enable_veracode en service-manifest	OFF	Tech Lead activa para servicios del CDE (PCI-DSS)
OWASP ZAP (DAST)	Variable de grupo	ON solo en QA	Solo post-deploy en ambiente QA

Las herramientas base no son opcionales

SonarQube, Docker Scout y TruffleHog están activas por default y solo el equipo de plataforma puede desactivarlas con justificación. Los feature flags existen para herramientas adicionales (Veracode), nunca para quitar las obligatorias.

---

6. Generación automática de Helm values

El pipeline genera un values.yaml completo con todos los estándares HERA leyendo los manifiestos. El desarrollador nunca configura labels ni resources manualmente — el pipeline lo hace:

# Generado automáticamente por el pipeline
podLabels:
  # Estándares K8s
  app.kubernetes.io/name: "backend-checkout-service"
  app.kubernetes.io/version: "3.0.1"
  app.kubernetes.io/component: "domain"
  app.kubernetes.io/part-of: "tienda-herdez"
  app.kubernetes.io/managed-by: "hera-pipeline"
  # Labels 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"
  hera.grupoherdez.com/partner: "partner-beta"
  hera.grupoherdez.com/lifecycle: "active"

resources:
  requests:
    cpu: "200m"
    memory: "256Mi"
  limits:
    cpu: "400m"
    memory: "512Mi"

serviceAccount:
  name: "backend-checkout-service-ksa"
  annotations:
    iam.gke.io/gcp-service-account: "gsa-tienda-herdez-checkout@ghdz-grupo-ext-sites-prd.iam.gserviceaccount.com"

Si el repo tiene un auto-deploy-values.yaml con configuraciones adicionales (probes, ports), el pipeline hace merge — las configuraciones del repo se suman, pero nunca sobreescriben labels ni resources.

---

7. KEDA post-deploy (DEV/QA)

Después del deploy exitoso en DEV o QA, el pipeline genera automáticamente un ScaledObject de KEDA leyendo el schedule del product-manifest.yml:

# Generado automáticamente — el desarrollador no escribe esto
apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
  name: backend-checkout-service-schedule
  namespace: tienda-herdez
spec:
  scaleTargetRef:
    name: backend-checkout-service
  minReplicaCount: 0
  maxReplicaCount: 6
  triggers:
    - type: cron
      metadata:
        timezone: "America/Mexico_City"
        start: "0 8 * * 1-5"
        end: "0 20 * * 1-5"
        desiredReplicas: "3"

En producción, el pipeline NO crea ScaledObject de Cron. Solo genera el HPA estándar con minReplicas mayor o igual a 2.

---

8. Jerarquía de variables GitLab

GitLab hereda variables del grupo padre al hijo. Esto evita configurar los mismos valores 800 veces:

Nivel	Qué se configura	Ejemplo
Root group (grupo-herdez/)	Herramientas globales, tokens de plataforma	SONAR_HOST_URL, DOCKER_REGISTRY, HERA_READ_TOKEN
Product subgroup (tienda-herdez/)	Proyectos GCP del producto	GCP_PROJECT_DEV, GCP_PROJECT_QA, GCP_PROJECT_PRD
Project	Secretos de build-time del servicio, por ambiente	K8S_SECRET_API_URL (scoped a qa), ADDITIONAL_HOSTS (scoped a prd)
GCP Secret Manager	Secretos de runtime	DB passwords, API keys, tokens OAuth — nunca en GitLab CI

Secretos de runtime van en Secret Manager, no en GitLab

Las variables CI/CD de GitLab son para secretos de build-time (tokens de SonarQube, credenciales de registry). Los secretos de runtime (contraseñas de BD, API keys de terceros) van en GCP Secret Manager + ESO.

---

9. Pipeline Observatory

Con 800 servicios, el equipo de plataforma necesita visibilidad agregada. El Pipeline Observatory es un job scheduled semanal que consume la API de GitLab y reporta:

Métrica	Qué responde
Distribución de versiones	¿Cuántos proyectos están en stable vs. versiones antiguas?
Tasa de fallos por herramienta	¿SonarQube falla más que Docker Scout? ¿Hay un patrón?
Cobertura de manifiestos	¿Cuántos proyectos aún no tienen service-manifest.yml?
Servicios sin KEDA en DEV/QA	¿Cuántos servicios corren 24/7 sin scale-to-zero?
Templates desactualizados	¿Quién está a 2+ minor versions de atraso?

Alertas automáticas

Condición	Severidad	Canal
Proyecto crítico con pipeline rojo mayor a 24h	Alta	Google Chat #hera-security-alerts
Mas del 20% de proyectos en versión desactualizada	Media	Google Chat #hera-platform-alerts
Mas de 50 servicios DEV/QA sin KEDA	Baja	Reporte FinOps mensual

---

10. Documentos relacionados

Documento	Relación
Estructura de Repositorios	Define la jerarquía de grupos GitLab y el product-manifest.yml
Estándares de Etiquetado	Los labels que el pipeline inyecta automáticamente
Workload Identity	El serviceAccount que el pipeline configura en cada deploy
Gestión de Secretos	Separación de secretos build-time (GitLab) vs. runtime (Secret Manager)
Clasificación de Servicios	Las 13 categorías válidas para service.category