Feature 6: Integración con Cloud Secret Manager #

Descripción general #

Semaphore actualmente almacena todas las credenciales en su propia base de datos. Las organizaciones que utilizan plataformas en la nube necesitan una forma de obtener secrets directamente del servicio de gestión de secrets de su proveedor de nube en tiempo de ejecución, evitando la duplicación de credenciales y aprovechando las políticas de rotación existentes. Esta funcionalidad añade integraciones nativas con AWS Secrets Manager y Azure Key Vault como capacidades exclusivas de Enterprise.

Motivación #

• Los equipos Enterprise ya gestionan secrets en AWS Secrets Manager o Azure Key Vault con políticas de rotación establecidas, controles de acceso y registros de auditoría. Duplicar estas credenciales en la base de datos de Semaphore crea una segunda fuente de verdad que puede desincronizarse.
• La rotación de credenciales en el proveedor de nube no se propaga automáticamente a Semaphore — alguien debe actualizar manualmente cada entrada del key store afectada después de cada rotación.
• Las políticas de cumplimiento y seguridad en industrias reguladas a menudo requieren que los secrets nunca salgan del perímetro del proveedor de nube ni se almacenen en bases de datos de terceros.
• El key store integrado de Semaphore carece de los controles de acceso, la granularidad de auditoría y la automatización de rotación que los cloud secret managers proporcionan de forma predeterminada.

Especificación detallada #

Enterprise #

6.1 Integración con AWS Secrets Manager #

Objetivo: Obtener secrets en tiempo de ejecución desde AWS Secrets Manager, permitiendo a los equipos aprovechar su infraestructura existente de secrets en AWS sin duplicar credenciales en la base de datos de Semaphore.

Requisitos:

• Nuevo tipo de backend de secrets externo: aws_secrets_manager.
• Métodos de autenticación:
  • Rol IAM (recomendado para despliegues en EC2/ECS/EKS) — no se almacenan credenciales en Semaphore.
  • Access key + secret key — almacenados en el key store de Semaphore (cifrados).
  • Rol asumido con ID externo — para acceso entre cuentas.
• Los secrets se referencian por ARN o nombre + versión/etapa opcional.
• Soporte para secrets estructurados en JSON con un selector field para extraer valores individuales (p. ej., {"username": "admin", "password": "..."} → extraer password).
• Soporte automático de rotación de secrets — cuando AWS rota un secret, Semaphore obtiene el nuevo valor en la siguiente ejecución de tarea.
• Modelo de configuración:

{
  "name": "Production AWS",
  "type": "aws_secrets_manager",
  "region": "us-east-1",
  "auth_method": "iam_role",
  "role_arn": "arn:aws:iam::123456789:role/semaphore-secrets",
  "external_id": "optional-external-id"
}

• Referencia de entrada del key store:

{
  "type": "external",
  "backend": "aws_secrets_manager",
  "secret_name": "production/db_password",
  "field": "password",
  "aws_config_id": 1
}

Issues relacionados: #2248

6.2 Integración con Azure Key Vault #

Objetivo: Obtener secrets en tiempo de ejecución desde Azure Key Vault, permitiendo a las organizaciones que utilizan Azure gestionar y rotar credenciales de forma centralizada sin almacenarlas en Semaphore.

Requisitos:

• Nuevo tipo de backend de secrets externo: azure_key_vault.
• Métodos de autenticación:
  • Managed identity (recomendado para despliegues en Azure VM/AKS) — no se almacenan credenciales en Semaphore.
  • Service principal con client secret.
  • Service principal con certificado.
• Los secrets se referencian por URL del vault + nombre del secret + versión opcional.
• Soporte para la obtención de secrets, claves y certificados del vault.
• Soporte automático de rotación de secrets — cuando Azure rota un secret, Semaphore obtiene el nuevo valor en la siguiente ejecución de tarea.
• Modelo de configuración:

{
  "name": "Production Azure",
  "type": "azure_key_vault",
  "vault_url": "https://my-vault.vault.azure.net",
  "auth_method": "managed_identity",
  "tenant_id": "...",
  "client_id": "..."
}

• Referencia de entrada del key store:

{
  "type": "external",
  "backend": "azure_key_vault",
  "secret_name": "db-password",
  "version": "latest",
  "azure_config_id": 1
}

Issues relacionados: #2248, #3170

6.3 Referencia externa unificada de secrets #

Objetivo: Proporcionar un tipo de entrada de key store común que apunte a un secret en cualquier proveedor de nube compatible.

Requisitos:

• Nuevo tipo de key store: “External Reference” que almacena un puntero al secret (p. ej., AWS ARN, URL del vault de Azure + nombre del secret) en lugar del secret en sí.
• En el momento de la ejecución de la tarea, Semaphore resuelve la referencia llamando a la API del proveedor de nube y obtiene el valor actual.
• El valor resuelto nunca se almacena en la base de datos de Semaphore — solo existe en memoria durante la ejecución de la tarea.
• La conexión al cloud secret manager se configura a nivel de proyecto o sistema (URL, método de autenticación, namespace/prefijo).
• La interfaz de usuario muestra las referencias externas con una insignia/icono distintivo y el tipo de backend (AWS/Azure).
• Validación al guardar: Semaphore intenta resolver la referencia y muestra una advertencia si el secret no es accesible (sin bloquear el guardado).

6.4 Caché de secrets #

Objetivo: Reducir las llamadas a la API de los proveedores de nube mediante el almacenamiento en caché de los secrets resueltos en memoria.

Requisitos:

• Caché en memoria opcional de corta duración (TTL configurable, predeterminado 5 minutos) para reducir las llamadas a la API del proveedor de nube.
• La caché está solo en memoria y se invalida al reiniciar Semaphore.
• La caché se indexa por ID de configuración del backend + referencia del secret, de modo que el mismo secret utilizado por múltiples templates se obtiene solo una vez por ventana de TTL.
• La caché puede desactivarse por configuración de backend (establecer TTL en 0) para secrets que deben obtenerse siempre frescos (p. ej., durante una rotación activa).
• Configuración: campo cache_ttl en la configuración del backend (p. ej., "cache_ttl": "5m").

Cambios en el esquema de base de datos #

Nuevas tablas:

• secret_backend — almacena configuraciones del proveedor de nube (project_id, type, name, config JSON, created_at, updated_at)

Tablas modificadas:

• access_key — añadir columnas:
  • external_backend_id (integer, nullable, FK a secret_backend) — enlaza con la configuración del proveedor de nube
  • external_reference (JSON, nullable) — almacena el puntero al secret (ARN, URL del vault, nombre del secret, field, version)

API Endpoints #

• GET/POST /api/project/{id}/secret-backends — listar/crear configuraciones de backend
• PUT/DELETE /api/project/{id}/secret-backends/{backend_id} — actualizar/eliminar backend
• POST /api/project/{id}/secret-backends/{backend_id}/test — probar conectividad y autenticación
• POST /api/project/{id}/secret-backends/{backend_id}/resolve — resolver una referencia de secret (para validación)

Configuración #

Nuevas opciones de configuración:

Key	Env Var	Default	Descripción
secret_cache_ttl	SEMAPHORE_SECRET_CACHE_TTL	5m	TTL predeterminado de la caché en memoria para secrets externos resueltos
secret_resolve_timeout	SEMAPHORE_SECRET_RESOLVE_TIMEOUT	10s	Tiempo máximo de espera para una respuesta de la API del proveedor de nube al resolver un secret

You might also like