Funzionalità 6: Integrazione con Cloud Secret Manager #

Panoramica #

Semaphore attualmente memorizza tutte le credenziali nel proprio database. Le organizzazioni che utilizzano piattaforme cloud hanno bisogno di un modo per recuperare i segreti direttamente dal servizio di gestione dei segreti del proprio cloud provider in fase di esecuzione, evitando la duplicazione delle credenziali e sfruttando le policy di rotazione esistenti. Questa funzionalità aggiunge integrazioni native con AWS Secrets Manager e Azure Key Vault come funzionalità esclusivamente Enterprise.

Motivazione #

• I team enterprise gestiscono già i segreti in AWS Secrets Manager o Azure Key Vault con policy di rotazione consolidate, controlli di accesso e tracce di audit. Duplicare queste credenziali nel database di Semaphore crea una seconda fonte di verità che può perdere la sincronizzazione.
• La rotazione delle credenziali nel cloud provider non si propaga automaticamente a Semaphore — qualcuno deve aggiornare manualmente ogni voce del key store interessata dopo ogni rotazione.
• Le policy di conformità e sicurezza nei settori regolamentati spesso richiedono che i segreti non lascino mai il perimetro del cloud provider o vengano memorizzati in database di terze parti.
• Il key store integrato di Semaphore non dispone dei controlli di accesso, della granularità di audit e dell’automazione della rotazione che i cloud secret manager forniscono nativamente.

Specifica Dettagliata #

Enterprise #

6.1 Integrazione con AWS Secrets Manager #

Obiettivo: Recuperare i segreti in fase di esecuzione da AWS Secrets Manager, consentendo ai team di sfruttare la propria infrastruttura AWS esistente per i segreti senza duplicare le credenziali nel database di Semaphore.

Requisiti:

• Nuovo tipo di backend per segreti esterni: aws_secrets_manager.
• Metodi di autenticazione:
  • Ruolo IAM (consigliato per deployment EC2/ECS/EKS) — nessuna credenziale memorizzata in Semaphore.
  • Access key + secret key — memorizzati nel key store di Semaphore (crittografati).
  • Ruolo assunto con external ID — per l’accesso cross-account.
• I segreti sono referenziati tramite ARN o nome + versione/stage opzionale.
• Supporto per segreti strutturati in JSON con un selettore field per estrarre valori singoli (es. {"username": "admin", "password": "..."} → estrai password).
• Supporto automatico per la rotazione dei segreti — quando AWS ruota un segreto, Semaphore recupera il nuovo valore alla prossima esecuzione del task.
• Modello di configurazione:

{
  "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"
}

• Riferimento della voce del key store:

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

Issue correlate: #2248

6.2 Integrazione con Azure Key Vault #

Obiettivo: Recuperare i segreti in fase di esecuzione da Azure Key Vault, consentendo alle organizzazioni che utilizzano Azure di gestire e ruotare centralmente le credenziali senza memorizzarle in Semaphore.

Requisiti:

• Nuovo tipo di backend per segreti esterni: azure_key_vault.
• Metodi di autenticazione:
  • Identità gestita (consigliato per deployment Azure VM/AKS) — nessuna credenziale memorizzata in Semaphore.
  • Service principal con client secret.
  • Service principal con certificato.
• I segreti sono referenziati tramite vault URL + nome del segreto + versione opzionale.
• Supporto per il recupero di segreti, chiavi e certificati dal vault.
• Supporto automatico per la rotazione dei segreti — quando Azure ruota un segreto, Semaphore recupera il nuovo valore alla prossima esecuzione del task.
• Modello di configurazione:

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

• Riferimento della voce del key store:

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

Issue correlate: #2248, #3170

6.3 Riferimento Unificato ai Segreti Esterni #

Obiettivo: Fornire un tipo di voce comune nel key store che punti a un segreto in qualsiasi cloud provider supportato.

Requisiti:

• Nuovo tipo di key store: “External Reference” che memorizza un puntatore al segreto (es. AWS ARN, Azure vault URL + nome del segreto) invece del segreto stesso.
• Al momento dell’esecuzione del task, Semaphore risolve il riferimento chiamando l’API del cloud provider e recupera il valore corrente.
• Il valore risolto non viene mai memorizzato nel database di Semaphore — esiste solo in memoria durante l’esecuzione del task.
• La connessione al cloud secret manager è configurata a livello di progetto o di sistema (URL, metodo di autenticazione, namespace/prefisso).
• L’interfaccia utente mostra i riferimenti esterni con un badge/icona distinto e il tipo di backend (AWS/Azure).
• Validazione al salvataggio: Semaphore tenta di risolvere il riferimento e mostra un avviso se il segreto non è accessibile (senza bloccare il salvataggio).

6.4 Cache dei Segreti #

Obiettivo: Ridurre le chiamate API ai cloud provider memorizzando nella cache in memoria i segreti risolti.

Requisiti:

• Cache in memoria opzionale a breve durata (TTL configurabile, default 5 minuti) per ridurre le chiamate API al cloud provider.
• La cache è solo in memoria e viene invalidata al riavvio di Semaphore.
• La cache è indicizzata per backend config ID + riferimento del segreto, quindi lo stesso segreto utilizzato da più template viene recuperato una sola volta per finestra TTL.
• La cache può essere disabilitata per configurazione del backend (impostare TTL a 0) per i segreti che devono essere sempre recuperati freschi (es. durante la rotazione attiva).
• Configurazione: campo cache_ttl nella configurazione del backend (es. "cache_ttl": "5m").

Modifiche allo Schema del Database #

Nuove tabelle:

• secret_backend — memorizza le configurazioni dei cloud provider (project_id, type, name, config JSON, created_at, updated_at)

Tabelle modificate:

• access_key — aggiunta colonne:
  • external_backend_id (integer, nullable, FK a secret_backend) — collegamento alla configurazione del cloud provider
  • external_reference (JSON, nullable) — memorizza il puntatore al segreto (ARN, vault URL, nome del segreto, field, versione)

API Endpoints #

• GET/POST /api/project/{id}/secret-backends — elenco/creazione configurazioni backend
• PUT/DELETE /api/project/{id}/secret-backends/{backend_id} — aggiornamento/eliminazione backend
• POST /api/project/{id}/secret-backends/{backend_id}/test — test di connettività e autenticazione
• POST /api/project/{id}/secret-backends/{backend_id}/resolve — risoluzione di un riferimento a un segreto (per validazione)

Configurazione #

Nuove opzioni di configurazione:

Key	Env Var	Default	Descrizione
secret_cache_ttl	SEMAPHORE_SECRET_CACHE_TTL	5m	TTL predefinito della cache in memoria per i segreti esterni risolti
secret_resolve_timeout	SEMAPHORE_SECRET_RESOLVE_TIMEOUT	10s	Tempo massimo di attesa per una risposta API del cloud provider durante la risoluzione di un segreto

You might also like