Sincronizzare i secret con i secret di Kubernetes

Questo documento descrive come sincronizzare i secret archiviati in Secret Manager con i secret di Kubernetes all'interno dei cluster Google Kubernetes Engine (GKE).

La procedura di sincronizzazione consente alle applicazioni in esecuzione su GKE di accedere ai secret di Secret Manager utilizzando i metodi standard di Kubernetes, come le variabili di ambiente o i montaggi di volumi. Questa funzionalità è utile per le applicazioni già progettate per leggere i secret dall'oggetto Secret di Kubernetes, anziché dover essere aggiornate per accedere direttamente a Secret Manager.

Suggerimento: la funzionalità di sincronizzazione dei secret è un'alternativa al componente aggiuntivo Secret Manager, che monta i secret come file in memoria direttamente nei pod. Utilizza il componente aggiuntivo Secret Manager ogni volta che la tua applicazione lo supporta, perché è un metodo più sicuro per accedere ai secret di Secret Manager in GKE.

Prima di iniziare

Completa i seguenti prerequisiti prima di sincronizzare i secret:

  • Abilita le API Secret Manager e Google Kubernetes Engine.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

    Abilita le API

  • Installa e quindi inizializza la gcloud CLI. Se hai già installato gcloud CLI, scarica l'ultima versione eseguendo il comando gcloud components update.

  • Assicurati di avere un cluster GKE in esecuzione. Questa funzionalità richiede GKE versione 1.33 e successive.

  • Assicurati che Workload Identity Federation for GKE sia abilitato sul cluster GKE. È necessario per l'autenticazione. Workload Identity Federation for GKE è abilitato per impostazione predefinita su un cluster Autopilot.

  • Assicurati di disporre delle autorizzazioni di Identity and Access Management necessarie per gestire i cluster GKE e Secret Manager.

Abilitare la sincronizzazione dei secret su un cluster GKE

Abilita la funzionalità di sincronizzazione dei secret quando crei un nuovo cluster o aggiorni un cluster esistente. Questa funzionalità è disponibile sia sui cluster Standard che Autopilot.

Abilitare la sincronizzazione dei secret su un nuovo cluster

Per creare un nuovo cluster con la sincronizzazione dei secret, utilizza uno di questi comandi gcloud CLI:

Cluster Standard

Per utilizzare Secret Manager dalla riga di comando, devi prima installare o eseguire l'upgrade alla versione 378.0.0 o successive di Google Cloud CLI. Su Compute Engine o GKE, devi eseguire l'autenticazione con l'ambito cloud-platform.

Abilita la sincronizzazione dei secret senza rotazione automatica.

gcloud container clusters create CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --workload-pool=PROJECT_ID.svc.id.goog \
    --enable-secret-sync

Abilita la sincronizzazione dei secret con la rotazione automatica. L'intervallo predefinito è di 2 minuti.

gcloud container clusters create CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --workload-pool=PROJECT_ID.svc.id.goog \
    --enable-secret-sync \
    --enable-secret-sync-rotation

Abilita la sincronizzazione dei secret con un intervallo di rotazione personalizzato. L'intervallo minimo è di 1 minuto.

gcloud container clusters create CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --workload-pool=PROJECT_ID.svc.id.goog \
    --enable-secret-sync \
    --enable-secret-sync-rotation \
    --secret-sync-rotation-interval=60s

Sostituisci quanto segue:

  • CLUSTER_NAME: il nome del cluster GKE
  • CONTROL_PLANE_LOCATION: la regione o la zona del control plane del cluster, ad esempio us-central1 o us-east1-a
  • PROJECT_ID: l'ID Google Cloud progetto

Cluster Autopilot

Per utilizzare Secret Manager dalla riga di comando, devi prima installare o eseguire l'upgrade alla versione 378.0.0 o successive di Google Cloud CLI. Su Compute Engine o GKE, devi eseguire l'autenticazione con l'ambito cloud-platform.

Abilita la sincronizzazione dei secret senza rotazione automatica.

gcloud container clusters create-auto CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-secret-sync

Abilita la sincronizzazione dei secret con la rotazione automatica. L'intervallo predefinito è di 2 minuti.

gcloud container clusters create-auto CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-secret-sync \
    --enable-secret-sync-rotation

Abilita la sincronizzazione dei secret con un intervallo di rotazione personalizzato. L'intervallo minimo è di 1 minuto.

gcloud container clusters create-auto CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-secret-sync \
    --enable-secret-sync-rotation \
    --secret-sync-rotation-interval=60s

Sostituisci quanto segue:

  • CLUSTER_NAME: il nome del cluster GKE
  • CONTROL_PLANE_LOCATION: la regione o la zona del control plane del cluster, ad esempio us-central1 o us-east1-a

Abilitare la sincronizzazione dei secret su un cluster esistente

Per aggiornare i cluster esistenti con la sincronizzazione dei secret, utilizza uno dei seguenti comandi gcloud CLI:

gcloud

Per utilizzare Secret Manager dalla riga di comando, devi prima installare o eseguire l'upgrade alla versione 378.0.0 o successive di Google Cloud CLI. Su Compute Engine o GKE, devi eseguire l'autenticazione con l'ambito cloud-platform.

Abilita la sincronizzazione dei secret su un cluster esistente

gcloud container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-secret-sync

Abilita la rotazione con un intervallo personalizzato

gcloud container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-secret-sync-rotation \
    --secret-sync-rotation-interval=300s

Disabilita la rotazione

gcloud container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --no-enable-secret-sync-rotation

Sostituisci quanto segue:

  • CLUSTER_NAME: il nome del cluster GKE
  • CONTROL_PLANE_LOCATION: la regione o la zona del control plane del cluster, ad esempio us-central1 o us-east1-a

Configurare la sincronizzazione dei secret

Per sincronizzare i secret, completa i seguenti passaggi:

  1. Crea un ServiceAccount Kubernetes utilizzando il seguente comando:

    kubectl create serviceaccount KSA_NAME --namespace NAMESPACE

    Sostituisci quanto segue:

    • KSA_NAME: il nome del ServiceAccount Kubernetes
    • NAMESPACE: lo spazio dei nomi Kubernetes in cui vuoi creare il ServiceAccount

  2. Crea un criterio di autorizzazione IAM che faccia riferimento al nuovo ServiceAccount Kubernetes e concedi al ServiceAccount l'autorizzazione per accedere al secret:

    gcloud

    Per utilizzare Secret Manager dalla riga di comando, devi prima installare o eseguire l'upgrade alla versione 378.0.0 o successive di Google Cloud CLI. Su Compute Engine o GKE, devi eseguire l'autenticazione con l'ambito cloud-platform. 

    gcloud secrets add-iam-policy-binding SECRET_NAME \
   --role=roles/secretmanager.secretAccessor \
   --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME

    Sostituisci quanto segue:

    • SECRET_NAME: il nome del secret in Secret Manager
    • PROJECT_NUMBER: il numero del Google Cloud progetto
    • PROJECT_ID: l'ID Google Cloud progetto
    • NAMESPACE: lo spazio dei nomi Kubernetes
    • KSA_NAME: il nome del ServiceAccount Kubernetes

  3. Crea una risorsa personalizzata SecretProviderClass utilizzando un manifest YAML. La risorsa SecretProviderClass definisce i secret specifici da recuperare da Secret Manager, inclusi i nomi e i percorsi delle risorse. Il componente aggiuntivo Secret Manager utilizza anche la risorsa SecretProviderClass per elencare i secret da montare e il nome file con cui montarli.

    Crea un file spc.yaml con i seguenti contenuti:

    apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: SECRET_PROVIDER_CLASS_NAME
  namespace: NAMESPACE
spec:
  provider: gke
  parameters:
    secrets: |
      -   resourceName: "projects/SECRET_PROJECT_ID/secrets/SECRET_NAME_1/versions/SECRET_VERSION_1"
          path: "FILENAME.txt"
      -   resourceName: "projects/SECRET_PROJECT_ID/secrets/SECRET_NAME_2/versions/SECRET_VERSION_2"
          path: "FILENAME1.txt"

    Sostituisci quanto segue:

    • SECRET_PROVIDER_CLASS_NAME: il nome dell'oggetto SecretProviderClass.
    • NAMESPACE: lo spazio dei nomi Kubernetes in cui stai creando questa risorsa.
    • resourceName: l'identificatore completo della risorsa per il secret in Secret Manager. Deve includere l'ID progetto, il nome del secret e la versione nel formato: projects/SECRET_PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION.
      • SECRET_PROJECT_ID: l'ID del Google Cloud progetto in cui è archiviato il secret. Può essere uguale a PROJECT_ID se il secret è archiviato nello stesso progetto del cluster GKE.
      • SECRET_NAME: il nome del secret.
      • SECRET_VERSION: la versione del secret. La versione del secret deve trovarsi nella stessa regione del cluster.
    • path: il nome file locale o l'alias con cui il valore del secret verrà esposto nell'ambiente Kubernetes. È l'identificatore univoco che collega una versione specifica di Secret Manager alla rappresentazione locale utilizzata dal cluster. Quando il secret viene sincronizzato con un secret Kubernetes utilizzando la risorsa SecretSync, questo percorso viene fatto riferimento dal campo sourcePath per individuare il valore del secret da sincronizzare. Puoi mappare più secret (definiti da resourceName) a nomi di percorso diversi all'interno della stessa SecretProviderClass.

  4. Per applicare il manifest, esegui il seguente comando:

    kubectl apply -f spc.yaml

  5. Crea una risorsa personalizzata SecretSync utilizzando un manifest YAML. Questa risorsa indica al controller di sincronizzazione di creare o aggiornare un secret Kubernetes in base ai contenuti definiti in SecretProviderClass.

    Crea un file secret-sync.yaml con i seguenti contenuti:

    apiVersion: secret-sync.gke.io/v1
kind: SecretSync
metadata:
  name: KUBERNETES_SECRET_NAME
  namespace: NAMESPACE
spec:
  serviceAccountName: KSA_NAME
  secretProviderClassName: SECRET_PROVIDER_CLASS_NAME
  secretObject:
    type: KUBERNETES_SECRET_TYPE
    data:
      -   sourcePath: "FILENAME.txt"
          targetKey: "TARGET_KEY1"
      -   sourcePath: "FILENAME1.txt"
          targetKey: "TARGET_KEY2"

    Sostituisci quanto segue:

    • KUBERNETES_SECRET_NAME: il nome che vuoi assegnare al nuovo secret Kubernetes che verrà creato dalla risorsa SecretSync.
    • NAMESPACE: lo spazio dei nomi Kubernetes in cui viene creata la nuova risorsa. Deve essere lo stesso spazio dei nomi di SecretProviderClass.
    • KSA_NAME: il nome del ServiceAccount Kubernetes utilizzato dal controller SecretSync per creare e aggiornare il secret Kubernetes di destinazione. Questo ServiceAccount deve disporre delle autorizzazioni necessarie per accedere ai secret esterni da Secret Manager.
    • SECRET_PROVIDER_CLASS_NAME: il nome dell'oggetto SecretProviderClass creato nel passaggio precedente. La risorsa SecretSync lo utilizza per trovare la configurazione corretta per i secret.
    • KUBERNETES_SECRET_TYPE: il tipo di secret Kubernetes da creare, ad esempio Opaque, tls o docker-registry. Determina il modo in cui Kubernetes gestisce i dati del secret.
    • sourcePath: il nome file locale o l'alias (il valore del campo path in SecretProviderClass) che identifica i dati del secret da recuperare. Il controller SecretSync utilizza questo sourcePath per richiedere i contenuti specifici del secret e convertirli in un nuovo secret Kubernetes.
    • targetKey: la chiave che verrà utilizzata nella sezione data del nuovo secret Kubernetes in fase di creazione. Definisce il modo in cui i contenuti del secret recuperati utilizzando sourcePath vengono denominati e archiviati nell'oggetto Secret Kubernetes finale. L'utilizzo di più voci nell'array di dati consente di definire più coppie chiave-valore all'interno dello stesso secret di destinazione.

  6. Per applicare il manifest, esegui il seguente comando:

    kubectl apply -f secret-sync.yaml

    Il controller di sincronizzazione crea un secret Kubernetes nello spazio dei nomi specificato. Questo secret contiene i dati mappati da Secret Manager.

  7. Verifica che il secret Kubernetes sia stato creato:

    kubectl get secret KUBERNETES_SECRET_NAME -n NAMESPACE -o yaml

    Sostituisci quanto segue:

    • KUBERNETES_SECRET_NAME: il nome del nuovo secret Kubernetes
    • NAMESPACE: lo spazio dei nomi Kubernetes in cui viene creato il nuovo secret

  8. Per risolvere un problema di sincronizzazione, utilizza il seguente comando:

    kubectl describe secretSync KUBERNETES_SECRET_NAME -n NAMESPACE

    Sostituisci quanto segue:

    • KUBERNETES_SECRET_NAME: il nome del nuovo secret Kubernetes
    • NAMESPACE: lo spazio dei nomi Kubernetes in cui deve esistere il nuovo secret

Gestire la rotazione dei secret

Se abiliti il flag --enable-secret-sync-rotation, sul cluster, il controller di sincronizzazione controlla periodicamente Secret Manager per verificare la presenza di nuove versioni dei secret specificati nella risorsa SecretProviderClass. Il flag --secret-sync-rotation-interval determina la frequenza con cui il controller verifica la presenza di aggiornamenti.

Se il controller rileva una nuova versione del secret in Secret Manager, aggiorna il secret Kubernetes corrispondente. Il controller confronta gli hash dei contenuti del secret per aggiornare i secret solo quando si verificano modifiche.

Le applicazioni che utilizzano questi secret devono rilevare e ricaricare i valori dei secret aggiornati dal secret Kubernetes. La modalità di gestione dipende dalla progettazione dell'applicazione.

Disabilitare la sincronizzazione dei secret

Per disabilitare la sincronizzazione dei secret, esegui il seguente comando gcloud CLI:

gcloud

Per utilizzare Secret Manager dalla riga di comando, devi prima installare o eseguire l'upgrade alla versione 378.0.0 o successive di Google Cloud CLI. Su Compute Engine o GKE, devi eseguire l'autenticazione con l'ambito cloud-platform. 

gcloud container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --no-enable-secret-sync

Sostituisci quanto segue:

  • CLUSTER_NAME: il nome del cluster GKE
  • CONTROL_PLANE_LOCATION: la regione o la zona del control plane del cluster, ad esempio us-central1 o us-east1-a

Questo comando arresta il controller di sincronizzazione. Non elimina i secret Kubernetes già creati. Se non ti servono più, devi eliminare manualmente i secret Kubernetes sincronizzati.

Eliminare i secret sincronizzati

Per eliminare un secret Kubernetes sincronizzato, elimina la risorsa SecretSync utilizzando il seguente comando:

    kubectl delete secretsync KUBERNETES_SECRET_NAME --namespace NAMESPACE

Sostituisci quanto segue:

  • KUBERNETES_SECRET_NAME: il nome del secret Kubernetes
  • NAMESPACE: lo spazio dei nomi Kubernetes in cui esiste il secret

Eseguire la migrazione dal driver CSI Secrets Store esistente

Se stai eseguendo la migrazione dall'installazione esistente del driver CSI Secrets Store, segui questi passaggi:

  1. Aggiorna il campo provider in SecretProviderClass da gcp a gke. L'esempio seguente mostra come aggiornare il campo provider:

    apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: app-secrets-gke
spec:
  provider: gke
  parameters:
    secrets: |
      -   resourceName: "projects/87654321/secrets/api-key-secret/versions/2"
          path: "good1.txt"

  2. Crea una risorsa SecretSync. Utilizza la seguente configurazione di esempio:

    apiVersion: secret-sync.gke.io/v1
kind: SecretSync
metadata:
  name: my-kube-secret
  namespace: NAMESPACE
spec:
  serviceAccountName: KSA_NAME
  secretProviderClassName: my-app-secrets
  secretObject:
    type: Opaque # Or other Kubernetes Secret types
    data:
      -   sourcePath: "my-secret.txt"
          targetKey: "USERNAME"
      -   sourcePath: "another-secret.txt"
          targetKey: "PASSWORD"

Considerazioni sulla sicurezza

Secret Manager offre funzionalità di sicurezza come il controllo dell'accesso con IAM, le chiavi di crittografia gestite dal cliente (CMEK) e l'audit logging. I secret vengono criptati at-rest e in transito all'interno di Secret Manager. Quando sincronizzi i secret con i secret Kubernetes, la loro sicurezza all'interno del cluster dipende dalla configurazione del cluster GKE. Considera quanto segue:

  • Archiviazione: i secret Kubernetes vengono archiviati in etcd, che è l'archivio dati principale di GKE. Per impostazione predefinita, GKE cripta i dati at-rest. Per una maggiore sicurezza, cripta i secret Kubernetes a livello di applicazione utilizzando una chiave che gestisci in Cloud Key Management Service(Cloud KMS). La crittografia dei secret fornisce un ulteriore livello di sicurezza per i carichi di lavoro sensibili.

  • Controllo dell'accesso: GKE supporta più opzioni per la gestione dell'accesso alle risorse all'interno dei progetti e dei relativi cluster utilizzando il controllo degli accessi basato sui ruoli (RBAC). Le autorizzazioni RBAC eccessivamente ampie possono esporre i secret a carichi di lavoro o utenti non previsti. Concedi l'accesso seguendo il principio del privilegio minimo ed esegui regolarmente l'audit dell'accesso sia a Secret Manager sia ai secret Kubernetes.

  • Variabili di ambiente: per migliorare la sicurezza, monta i secret Kubernetes come volumi anziché utilizzarli come variabili di ambiente. In questo modo si riduce il rischio di logging accidentale o di esposizione ad altri processi.

Passaggi successivi