Gestión de Secretos

La Gestión de Secretos es el conjunto de prácticas y herramientas que usamos para manejar de forma segura las credenciales, API keys, tokens y cualquier otra información sensible.

Política fundamental

NUNCA, bajo ninguna circunstancia, se deben “hardcodear” secretos en el código fuente o en archivos de configuración comiteados a un repositorio Git. La violación de esta regla es considerada una falta de seguridad grave.

Estándar mandatorio de configuración

El naming de secretos en GCP Secret Manager, los nombres de K8s Secrets y las variables de entorno del pod están normados por el Estándar de Configuración HERA. Todo manifiesto K8s debe cumplir las reglas R1–R12 antes del primer despliegue. Ver la regla R4 específicamente para el patrón obligatorio de valueFrom.secretKeyRef con External Secrets Operator.

Almacenes de Secretos en HERA

Utilizamos dos herramientas principales, cada una con un propósito específico:

1. GCP Secret Manager:

   • Uso Principal: Almacenar secretos para aplicaciones en runtime. Por ejemplo, contraseñas de bases de datos, API keys de servicios de terceros que tu aplicación necesita para funcionar.
   • Ventajas: Versionado de secretos, auditoría completa de accesos, integración nativa con IAM y Workload Identity.

2. GitLab CI/CD Variables:

   • Uso Principal: Proveer secretos al ambiente de CI/CD durante el pipeline. Por ejemplo, el token de SonarQube (SONAR_TOKEN) o las credenciales para hacer push a un registro.
   • Ventajas: Integrado en GitLab, fácil de usar, con opciones de Masked (ocultar en logs) y Protected (solo disponible en ramas protegidas).

¿Dónde guardo mi secreto?

?

¿Lo necesita tu aplicación para funcionar en producción?

Ej: contraseña de base de datos, API key de terceros

Sí

GCP Secret Manager

• Versionado y auditoría completa
• Integración con IAM + Workload Identity
• Montado como archivo en el pod (CSI Driver)

o

?

¿Lo necesita el pipeline para construir, probar o desplegar?

Ej: SONAR_TOKEN, credenciales para el registry de imágenes

Sí

GitLab CI/CD Variables

• Integrado en GitLab, fácil de usar en .gitlab-ci.yml
• Masked: ocultado en los logs del pipeline
• Protected: disponible solo en ramas protegidas

NUNCA hardcodees secretos en el código fuente o en archivos .env comiteados a Git

Mensaje clave GCP Secret Manager para runtime. GitLab CI Variables para pipelines. Cero secretos en código.

---

Acceso a Secretos desde GKE (Runtime)

El método estándar y obligatorio para que tus aplicaciones en GKE accedan a secretos de GCP Secret Manager es a través de Workload Identity y el External Secrets Operator (ESO).

Secret Manager + External Secrets Operator + Workload Identity

HERA utiliza External Secrets Operator (ESO) para sincronizar de forma segura los secretos desde GCP Secret Manager hacia Secrets nativos de Kubernetes. Este enfoque desacopla tu aplicación de la API de GCP y permite consumir secretos como variables de entorno estándar.

Flujo de trabajo:

1. El secreto se almacena en GCP Secret Manager (ej. mi-app-db-password).
2. El pod asume una identidad de GCP mediante Workload Identity (ej. mi-app-gsa@mi-proyecto.iam).
3. El GSA tiene el rol roles/secretmanager.secretAccessor otorgado sobre los secretos específicos que necesita.
4. El operador ESO lee el secreto de GCP utilizando Workload Identity y crea un Secret nativo en tu namespace de Kubernetes.
5. Tu aplicación consume el secreto inyectado como variable de entorno usando valueFrom.secretKeyRef.

Configuración del ExternalSecret (CRD)

Para que ESO sincronice un secreto, debes definir un recurso ExternalSecret en tu repositorio. El operador se encarga de mantenerlo sincronizado (útil para la rotación automática).

external-secret.yaml

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: mi-app-db-credentials
  namespace: mi-app
spec:
  refreshInterval: "1h" # Frecuencia con la que ESO verifica cambios en GCP
  secretStoreRef:
    name: gcp-secret-store # Referencia al ClusterSecretStore configurado por Plataforma
    kind: ClusterSecretStore
  target:
    name: mi-app-db-credentials-k8s # Nombre del Secret de K8s que ESO creará
    creationPolicy: Owner
  data:
  - secretKey: password # Llave dentro del Secret de K8s
    remoteRef:
      key: mi-app-db-password # Nombre del secreto en GCP Secret Manager

Abstracción para el desarrollador

Como desarrollador, no necesitas interactuar directamente con la API de Secret Manager en tu código ni montar volúmenes complejos. Simplemente declaras el ExternalSecret y consumes la variable de entorno generada. La plataforma HERA se encarga de la autenticación segura y la sincronización.

Nota Operacional: Rotación y Caché

El refreshInterval de 1 hora significa que si actualizas el secreto en GCP Secret Manager, tomará hasta una hora para que el Secret de K8s se actualice automáticamente. Además, las aplicaciones que leen secretos como variables de entorno al inicio (arranque del pod) no verán el nuevo valor hasta que el pod se reinicie. Para una rotación sin downtime, usa herramientas como Reloader o reinicia el Deployment tras la actualización.

---

Rotación de Secretos

Los secretos no deben ser eternos. La rotación periódica limita el tiempo de exposición en caso de una brecha.

Política de Rotación

Tipo de Secreto	Frecuencia de Rotación
API Keys críticas	30 días
Service Account Keys (si se usan)	90 días
Contraseñas de Bases de Datos	90 días
JWT Secrets	180 días

El proceso de rotación debe seguir un flujo que evite el downtime:

1. Crear y agregar el nuevo secreto (versión N+1) en el almacén.
2. Desplegar la aplicación para que empiece a usar el nuevo secreto.
3. Verificar que la aplicación funciona correctamente con la nueva versión.
4. Desactivar y eliminar el secreto antiguo (versión N).