Estándares de Nombramiento en GCP

Resumen Ejecutivo

Este estándar define las reglas de nomenclatura para todos los recursos de infraestructura en Google Cloud Platform (GCP), garantizando la trazabilidad, seguridad y eficiencia operativa.

• Estructura Jerárquica: Alinea los nombres de los recursos con la taxonomía de productos y servicios de HERA, facilitando la identificación inmediata de ownership.
• Consistencia Multientorno: Implementa sufijos obligatorios por ambiente (dev, qa, prd) para evitar errores de configuración cross-project.
• Optimización de Gobernanza: Permite el uso de scripts de automatización y herramientas de auditoría mediante patrones predecibles y parseables.

En un ecosistema con cientos de microservicios y múltiples ambientes, un nombre inconsistente es una vulnerabilidad operativa. Este estándar asegura que cualquier ingeniero, ante un log o una alerta, sepa exactamente a qué producto, servicio y ambiente pertenece un recurso de GCP.

---

1. Reglas Generales

Casing y Caracteres

1. Lowercase estricto: Todos los nombres deben estar en minúsculas.
2. Kebab-case: Usar guiones - como separador de palabras.
3. Sin caracteres especiales: Solo letras a-z, números 0-9 y guiones -.
4. Prefijo Corporativo: Los recursos con namespace global (como Buckets) deben iniciar con ghdz-.

Principio: env implícito en el GCP project

Cada ambiente (DEV/QA/PRD) vive en un GCP project separado (ghdz-<tenant>-<capability>-<env>). El ambiente es implícito en el project ID, por lo que los recursos project-scoped (GSA, Artifact Registry, Cloud SQL, Pub/Sub) no llevan sufijo de ambiente — añadirlo es redundante.

El sufijo -dev/qa/prd aplica únicamente cuando el recurso tiene namespace global en GCP y debe ser globalmente único (Cloud Storage Buckets, GCP Project ID).

Principio consistente con Estándares de Configuración

Este principio ya está establecido para secretos y env vars en Estándares de Configuración y Variables de Entorno: el mismo nombre de secreto vive en ghdz-grupo-ext-sites-dev, -qa y -prd sin repetir el sufijo porque el project ID provee el contexto. Este estándar lo extiende al resto de recursos GCP.

---

2. Cómputo e Identidad

GCP Service Accounts (GSA)

Las cuentas de servicio de GCP son críticas para la seguridad vía Workload Identity. El <servicio> corresponde al nombre canónico del deployment siguiendo el patrón <tipo>-<detalle> definido en Clasificación de Servicios. No lleva sufijo de ambiente — el project ID del email del GSA (<gsa>@<project-id>.iam.gserviceaccount.com) provee el contexto.

Formato: gsa-<producto>-<servicio>

• Ejemplo: gsa-tienda-herdez-backend-checkout-service (email completo: gsa-tienda-herdez-backend-checkout-service@ghdz-grupo-ext-sites-prd.iam.gserviceaccount.com)

Artifact Registry (Repositories)

Los repositorios viven dentro de un proyecto GCP, por lo que heredan el ambiente del project ID.

Formato: <producto>-<tipo>

• Ejemplo: tienda-herdez-docker, tienda-herdez-npm

---

3. Almacenamiento y Datos

Cloud Storage Buckets

Los nombres de los buckets son globales en GCP, por lo que el prefijo corporativo ghdz- y el sufijo de ambiente son obligatorios para garantizar unicidad global y separación entre entornos.

Formato: ghdz-<producto>-<proposito>-<env>

• Ejemplo: ghdz-tienda-herdez-public-assets-prd, ghdz-sitio-donamaria-logs-dev

Cloud SQL (Instancias)

Las instancias viven dentro de un proyecto GCP, por lo que heredan el ambiente del project ID.

Formato: sql-<producto>-<motor>

• Ejemplo: sql-tienda-herdez-postgres, sql-crm-mysql

Cloud SQL (Bases de Datos)

Dentro de la instancia, la base de datos lógica siempre incluye el producto y el servicio que la consume. El formato es defensivo: funciona para instancias dedicadas e instancias compartidas cross-producto sin renames posteriores.

Formato: db_<producto>_<servicio> (snake_case obligatorio por compatibilidad con motores SQL)

• Ejemplo: db_tienda_herdez_checkout, db_tienda_herdez_inventory, db_miel_carlota_loyalty

Parte	Regla	Ejemplo
<producto>	Nombre canónico del producto en Estructura de Repositorios, en snake_case	tienda_herdez, miel_carlota, hoy_toca
<servicio>	Parte <detalle> del nombre canónico del deployment (sin el prefijo <tipo>- ni -service final), en snake_case	checkout, inventory, user

---

4. Mensajería y Eventos

Pub/Sub Topics

Los topics viven dentro de un proyecto GCP — heredan el ambiente del project ID.

Formato: top-<producto>-<detalle>

• Ejemplo: top-tienda-herdez-order-created

Pub/Sub Subscriptions

Igual que los topics: project-scoped, sin sufijo de ambiente.

Formato: sub-<consumidor>-<topic-name>

• Ejemplo: sub-email-worker-order-created

---

5. Checklist de Cumplimiento para Code Review

Esta checklist es obligatoria en todo MR que agregue o modifique recursos de GCP a través de Terraform o el Cloud Console. Todo item debe estar marcado ✅ antes del merge a develop.

Formato general

• Todos los nombres están en lowercase estricto ([a-z0-9-])
• Los nombres usan kebab-case con guiones como único separador (nunca underscores, salvo en databases Cloud SQL donde se permite)
• Sólo los recursos con namespace global llevan sufijo de ambiente: Cloud Storage Buckets (-dev/qa/prd) y el GCP Project ID mismo. El resto de recursos project-scoped no lleva sufijo de ambiente — el env es implícito en el project ID
• Ningún nombre excede los límites de GCP para su tipo de recurso (ej. 63 chars para Service Accounts, 30 chars para Cloud SQL instances)

Prefijos corporativos

• Buckets de Cloud Storage usan el prefijo global ghdz- (son namespace global en GCP)
• Ningún nombre contiene el prefijo legacy hera- o hera_ (refactorizados a ghdz- / grupoherdez_ en 2026-04-14)

Alineación con la taxonomía HERA

• El nombre del GSA incluye el nombre canónico del deployment con sufijo -service donde aplique (ej. gsa-tienda-herdez-backend-checkout-service, no gsa-tienda-herdez-checkout)
• El nombre del recurso incluye el nombre del producto cuando el recurso es específico de un producto (sql-tienda-herdez-postgres)
• Pub/Sub topics y subscriptions siguen los patrones top-<producto>-<detalle> y sub-<consumidor>-<topic>
• Los nombres de Cloud SQL databases siguen el formato db_<producto>_<servicio> e incluyen producto y servicio (db_tienda_herdez_checkout para backend-checkout-service del producto tienda-herdez). Nunca db_<servicio> solo

Documentación del recurso

• El recurso tiene labels GCP para trazabilidad: domain, product, environment, criticality, data-classification
• El recurso se crea con un módulo Terraform de HERA que recibe variables estandarizadas (product, purpose, env) y deriva el nombre internamente
• El recurso tiene un comentario en el archivo .tf que explica su propósito

---

6. 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	❌ Nombres con mayúsculas, camelCase o PascalCase	GCP acepta algunos pero son inconsistentes con el ecosistema HERA	Lowercase estricto + kebab-case
2	❌ Buckets sin sufijo de ambiente (ghdz-tienda-herdez-uploads en vez de ghdz-tienda-herdez-uploads-prd)	El namespace global de Cloud Storage requiere unicidad y separación visible entre entornos	Buckets y GCP Project IDs siempre llevan -dev/qa/prd; el resto de recursos hereda el env del project ID
2a	❌ Sufijo de ambiente en recursos project-scoped (gsa-tienda-herdez-backend-checkout-service-prd en vez de gsa-tienda-herdez-backend-checkout-service)	El env ya está en el project ID del recurso — duplicarlo es ruido que rompe la consistencia con secretos y env vars	Omitir el sufijo en GSA, Artifact Registry, Cloud SQL y Pub/Sub
3	❌ Prefijo legacy hera-	Se refactorizó a ghdz- en 2026-04-14 para alinear con la identidad corporativa	Usar ghdz- para buckets
4	❌ Nombres hardcodeados en manifiestos en lugar de módulos Terraform	Rompe la auditoría automática de OPA y la reutilización entre entornos	Usar siempre los módulos templates/terraform/ con variables product, purpose, env
5	❌ GSA sin el sufijo -service del deployment (ej. gsa-tienda-checkout)	Rompe la trazabilidad al deployment canónico del repo de GitLab	Usar el nombre completo del deployment: gsa-tienda-herdez-backend-checkout-service
5a	❌ Cloud SQL database sin producto (db_checkout, db_cms, flaveur_cms, MielCarlota_db, bd_loyalty_miel_carlota, cielito-app, PV_DB)	Colisión en instancias compartidas cross-producto; prefijos inconsistentes (bd_, sin prefijo, mayúsculas, guiones); nombres no auto-descriptivos	Usar siempre db_<producto>_<servicio> en lowercase snake_case: db_tienda_herdez_checkout, db_flaveur_cms, db_miel_carlota, db_cielito_app
6	❌ Recursos sin labels GCP	Imposibles de rastrear en reportes de FinOps o auditorías por dominio/marca	Agregar labels mínimas: domain, product, environment, criticality
7	❌ Creación manual de recursos productivos desde Cloud Console	Crea drift entre Terraform state y el estado real, rompe reproducibilidad	Solo IaC via Terraform para recursos de DEV/QA/PRD. Cloud Console solo en sandbox
8	❌ Nombres que exceden el límite técnico del recurso (ej. Cloud SQL instance > 30 chars)	GCP rechaza el terraform apply y el deploy falla tarde	Validar longitud en el módulo de Terraform antes de llegar al CI

---

7. 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 Etiquetado (K8s Labels) — mapeo del product-manifest.yml a etiquetas de negocio y etiquetas estándar de Kubernetes
• Clasificación de Servicios — taxonomía de 13 categorías que determina el sufijo canónico del deployment utilizado en los nombres de GSA y recursos vinculados