SecretsManagement

Ambito: namespaced · Obbligatoria per ogni workload

Seleziona il backend delle credenziali per un namespace. I workload nello stesso namespace possono collegarlo tramite secretsRef e fare riferimento ai nomi dei Secret materializzati; un workload senza secretsRef usa invece Secret creati da te. Un backend per risorsa. Per il modello completo dei secret, i provider e la matrice di Key Vault, vedi Gestione dei secret.

Spec

Campo	Tipo	Descrizione
`backend`	enum `eso` \| `sealedSecrets` (obbligatorio)	Il backend delle credenziali
`eso`	object	Configurazione ESO (quando `backend: eso`)
`sealedSecrets`	object	Configurazione Sealed Secrets (quando `backend: sealedSecrets`)

`eso`

Campo	Tipo	Descrizione
`provider`	enum `azureKeyVault` (predefinito) \| `hashicorpVault` \| `raw`	Il provider del `SecretStore` ESO
`vaultURL`	string	URL di Azure Key Vault (provider azureKeyVault)
`authType`	enum `WorkloadIdentity` (predefinito) \| `ServicePrincipal`	Metodo di autenticazione Azure
`serviceAccountName`	string	SA con cui ESO si autentica (Workload Identity). L'operatore crea questo ServiceAccount se manca (di proprietà del CR, annotato a partire da `clientID`/`tenantID`); un SA preesistente viene adottato senza modifiche
`clientID`	string	Client ID della managed identity user-assigned di Azure. Viene apposto sul SA creato come `azure.workload.identity/client-id`, che ESO legge per scambiare il token del SA. Obbligatorio per Workload Identity, a meno che tu non crei in anticipo il SA con tale annotation
`tenantID` / `authSecretRef`	string / riferimenti	Credenziali del Service Principal. `tenantID` viene inoltre apposto sul SA di Workload Identity come `azure.workload.identity/tenant-id`
`hashicorpVault`	object	Connessione a HashiCorp Vault — vedi `hashicorpVault`
`providerConfig`	object	Blocco `spec.provider` ESO grezzo (provider `raw`)
`refreshInterval`	duration	Predefinito `1h`
`externalSecrets`	list	I Secret da materializzare

`hashicorpVault`

Campo	Tipo	Descrizione
`server`	string (obbligatorio)	Indirizzo di Vault, ad es. `https://vault.example.internal:8200`
`path`	string	Mount KV, predefinito `secret`
`version`	enum `v2` (predefinito) \| `v1`	Versione del motore KV
`namespace`	string	Namespace di Vault Enterprise (ad es. `team-a`); vuoto per Vault open-source
`caSecretRef`	`{ name, key }`	Secret che contiene il certificato PEM della CA che ha firmato il certificato TLS di Vault (chiave predefinita `ca.crt`) — necessario quando Vault usa una CA privata, la norma on-prem
`auth`	object (obbligatorio)	Esattamente uno dei tre seguenti
`auth.kubernetes`	`{ role, mountPath, serviceAccountName }`	Autenticazione Kubernetes di Vault (consigliata nel cluster). Il ruolo Vault è associato a `serviceAccountName`; l'operatore crea quel ServiceAccount se manca (uno esistente viene usato senza modifiche). Vuoto ⇒ il ServiceAccount di ESO stesso. `mountPath` predefinito `kubernetes`
`auth.appRole`	`{ path, roleId, secretIdSecretRef }`	Autenticazione AppRole di Vault (comune on-prem): il role ID più un Secret che contiene il secret ID (chiave predefinita `secret-id`). `path` predefinito `approle`
`auth.tokenSecretRef`	`{ name, key }`	Un Secret che contiene un token Vault (chiave predefinita `token`). I token scadono — preferisci i metodi precedenti

Con Vault, ogni voce di keys associa una chiave del Secret Kubernetes a un percorso di secret sotto il mount; la chiave Kubernetes è anche il campo letto da quel secret di Vault (OPENAI_API_KEY: navique/models legge il campo OPENAI_API_KEY di secret/navique/models).

Il lato Vault — una policy di sola lettura sul mount e il ruolo per il tuo metodo di autenticazione — viene configurato una sola volta dall'amministratore di Vault; la console di gestione genera i comandi esatti per le tue impostazioni.

`externalSecrets[]`

Campo	Descrizione
`name`	Nome del Secret Kubernetes di destinazione
`keys`	Mappatura abbreviata `{ k8sKey: remoteSecretName }`
`data`	Forma completa `remoteRef` di ESO (`secretKey`, `remoteKey`, `property`, `version`) per i provider in cui property/version sono rilevanti
`findRegexp`	`dataFrom.find` massivo tramite espressione regolare

`sealedSecrets`

Campo	Descrizione
`controllerNamespace`	Dove risiede il controller Sealed Secrets; per impostazione predefinita questo namespace

Esempi

ESO — Azure Key Vault tramite Workload Identity (predefinito in produzione)

yaml

apiVersion: core.navique.com/v1alpha1
kind: SecretsManagement
metadata:
  name: forge-secrets
  namespace: forge-gateway
spec:
  backend: eso
  eso:
    vaultURL: https://kvforgepltprod.vault.azure.net/
    serviceAccountName: forge-sa   # created by the operator if absent (adopted if it exists)
    clientID: 11111111-2222-3333-4444-555555555555  # managed-identity client ID (SA annotation)
    refreshInterval: 1h
    externalSecrets:
      - name: model-credentials
        keys:
          OPENAI_API_KEY: gateway-foundry-api-key
          ANTHROPIC_API_KEY: gateway-foundry-api-key

ESO — Service Principal (non AKS / Kind)

yaml

spec:
  backend: eso
  eso:
    vaultURL: https://kv.vault.azure.net/
    authType: ServicePrincipal
    tenantID: <tenant-guid>
    authSecretRef:
      clientID:     { name: azure-sp, key: client-id }
      clientSecret: { name: azure-sp, key: client-secret }

ESO — HashiCorp Vault on-prem (autenticazione Kubernetes, CA privata)

yaml

spec:
  backend: eso
  eso:
    provider: hashicorpVault
    hashicorpVault:
      server: https://vault.example.internal:8200
      namespace: team-a            # Vault Enterprise only
      caSecretRef: { name: vault-ca }
      auth:
        kubernetes: { role: navique, serviceAccountName: navique-vault }
    externalSecrets:
      - name: model-credentials
        keys: { OPENAI_API_KEY: navique/models }

ESO — HashiCorp Vault con AppRole

yaml

spec:
  backend: eso
  eso:
    provider: hashicorpVault
    hashicorpVault:
      server: https://vault.example.internal:8200
      caSecretRef: { name: vault-ca }
      auth:
        appRole:
          roleId: 0f3c…                                 # not a secret
          secretIdSecretRef: { name: vault-approle }    # key secret-id
    externalSecrets:
      - name: model-credentials
        keys: { OPENAI_API_KEY: navique/models }

ESO — HashiCorp Vault con un token (dev / ermetico)

yaml

spec:
  backend: eso
  eso:
    provider: hashicorpVault
    hashicorpVault:
      server: http://vault.vault.svc:8200
      auth:
        tokenSecretRef: { name: vault-token, key: token }
    externalSecrets:
      - name: model-credentials
        keys: { OPENAI_API_KEY: model-credentials }

ESO — qualsiasi provider (passthrough grezzo)

provider: raw inietta il blocco spec.provider di ESO così com'è, quindi ogni provider ESO funziona (AWS, GCP, IBM, Akeyless, 1Password, …) senza modifiche all'operatore:

yaml

spec:
  backend: eso
  eso:
    provider: raw
    providerConfig:
      aws:
        service: SecretsManager
        region: eu-central-1
        auth: { jwt: { serviceAccountRef: { name: forge-sa } } }
    externalSecrets:
      - name: model-credentials
        data:
          - { secretKey: OPENAI_API_KEY, remoteKey: prod/model, property: openai, version: AWSCURRENT }

Sealed Secrets

yaml

spec:
  backend: sealedSecrets
  sealedSecrets:
    controllerNamespace: sealed-secrets

Comportamento

ESO ⇒ l'operatore garantisce la presenza dell'External Secrets Operator (tenendo conto della provenienza), attende che i suoi CRD siano Established, quindi applica un SecretStore namespaced e gli ExternalSecret configurati. Uno store namespaced (non un ClusterSecretStore) mantiene isolate le credenziali di ciascun namespace.
Sealed Secrets ⇒ l'operatore garantisce la presenza del controller Sealed Secrets e riconcilia i SealedSecret referenziati.

I workload che impostano secretsRef eseguono il reconcile solo quando quella SecretsManagement è pronta.

Stato

{ phase, backend, storeReady, materializedSecrets[], conditions, observedGeneration }.

Per ogni backend ESO, conditions contiene SecretStoreReady: indica se ESO riesce a raggiungere il secret store e ad autenticarsi. Quando ESO segnala di non riuscirci, la condition — e Ready, poiché nulla può sincronizzarsi — è False con la causa riportata da ESO stesso, ad es. x509: certificate signed by unknown authority (imposta caSecretRef), permission denied (verifica il ruolo e la policy di Vault) oppure un namespace di Vault errato.

Per un backend Azure Key Vault + WorkloadIdentity, conditions contiene inoltre FederatedCredentialReady — il segnale passivo che indica se la federated identity credential di Azure esiste per il subject del ServiceAccount di ESO. Vedi Operazioni sui secret → la federated credential.

SecretsManagement ​

Spec ​

eso ​

hashicorpVault ​

externalSecrets[] ​

sealedSecrets ​

Esempi ​

ESO — Azure Key Vault tramite Workload Identity (predefinito in produzione) ​

ESO — Service Principal (non AKS / Kind) ​

ESO — HashiCorp Vault on-prem (autenticazione Kubernetes, CA privata) ​

ESO — HashiCorp Vault con AppRole ​

ESO — HashiCorp Vault con un token (dev / ermetico) ​

ESO — qualsiasi provider (passthrough grezzo) ​

Sealed Secrets ​

Comportamento ​

Stato ​

SecretsManagement

Spec

`eso`

`hashicorpVault`

`externalSecrets[]`

`sealedSecrets`

Esempi

ESO — Azure Key Vault tramite Workload Identity (predefinito in produzione)

ESO — Service Principal (non AKS / Kind)

ESO — HashiCorp Vault on-prem (autenticazione Kubernetes, CA privata)

ESO — HashiCorp Vault con AppRole

ESO — HashiCorp Vault con un token (dev / ermetico)

ESO — qualsiasi provider (passthrough grezzo)

Sealed Secrets

Comportamento

Stato