Configura i secret per le istanze

Anteprima — Istanze Cloud Run

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

La tua istanza potrebbe richiedere chiavi API, password, certificati o altre informazioni sensibili per le sue dipendenze. Per Cloud Run, Google consiglia di archiviare queste informazioni sensibili in un secret creato in Secret Manager.

Rendi disponibile un secret ai tuoi contenitori in uno dei seguenti modi:

• Quando monti ogni secret come volume, Cloud Run rende il secret disponibile al container come file. Quando legge un volume, Cloud Run recupera sempre il valore del secret da Secret Manager per utilizzare il valore con la versione più recente. Questo metodo funziona bene anche con la rotazione dei secret.
• Passa un secret utilizzando le variabili di ambiente. Le variabili di ambiente vengono risolte all'avvio dell'istanza, quindi se utilizzi questo metodo, Google ti consiglia di bloccare il secret su una versione specifica anziché utilizzare latest come versione.

Per saperne di più, consulta le best practice di Secret Manager.

Come vengono controllati i secret durante il deployment e l'esecuzione

Durante il deployment dell'istanza, Cloud Run controlla tutti i secret che utilizzi. Il controllo garantisce che il account di servizio che esegue il container abbia l'autorizzazione per accedere a questi secret.

Durante l'esecuzione, all'avvio delle istanze:

• Se il secret è una variabile di ambiente, Cloud Run recupera il valore del secret prima di avviare l'istanza. Se il processo di recupero del secret non riesce, l'istanza non viene avviata.
• Se monti il secret come volume, Cloud Run non esegue controlli durante l'avvio dell'istanza. Tuttavia, durante l'esecuzione, se un secret è inaccessibile, i tentativi di lettura del volume montato non vanno a buon fine.

Proprietà del volume

La proprietà di un volume secret Cloud Run varia in base all'ambiente di esecuzione e al tipo di deployment.

Quando monti un volume secret utilizzando l'ambiente di esecuzione di seconda generazione, che è sempre il caso dell'istanza, root è il proprietario del volume.

Prima di iniziare

1. Abilita l'API Secret Manager, se non è già abilitata.

   Ruoli richiesti per abilitare le API

   Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

   Abilitare l'API

2. Utilizza un secret esistente o creane uno in Secret Manager, come descritto in Crea un secret.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per configurare i secret, chiedi all'amministratore di concederti i seguenti ruoli IAM:

• Cloud Run Admin (roles/run.admin) sull'istanza Cloud Run
• Service Account User (roles/iam.serviceAccountUser) sull'identità di servizio

Per consentire a Cloud Run di accedere al secret, l'identità del servizio deve disporre del seguente ruolo:

• Secret Manager Secret Accessor (roles/secretmanager.secretAccessor)

Per istruzioni su come aggiungere l'entità di servizio al ruolo Secret Manager Secret Accessor, consulta Gestire l'accesso ai secret.

Per un elenco di ruoli e autorizzazioni IAM associati a Cloud Run, consulta Ruoli IAM di Cloud Run e Autorizzazioni IAM di Cloud Run. Se la tua istanza Cloud Run interagisce con le APIGoogle Cloud , come le librerie client Cloud, consulta la guida alla configurazione dell'identità del servizio. Per saperne di più sulla concessione dei ruoli, consulta Autorizzazioni di deployment e Gestisci l'accesso.

Rendere un secret accessibile a Cloud Run

Puoi rendere un secret accessibile alla tua istanza utilizzando Google Cloud CLI o YAML quando esegui il deployment di una nuova istanza o aggiorni un'istanza esistente:

gcloud

• Per esporre il secret come variabile di ambiente quando esegui il deployment di un'istanza, esegui questo comando:

  gcloud beta run instances deploy INSTANCE \
    --image IMAGE_URL \
    --update-secrets=ENV_VAR_NAME=SECRET_NAME:VERSION

  Sostituisci quanto segue:

  • INSTANCE: il nome dell'istanza.
  • IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/hello:latest.
  • ENV_VAR_NAME: il nome della variabile di ambiente che vuoi utilizzare con il secret.
  • SECRET_NAME: il nome del secret nello stesso progetto, ad esempio mysecret.
  • VERSION: la versione del secret. Utilizza latest per l'ultima versione o un numero, ad esempio 2.

• Per aggiornare più secret contemporaneamente, separa le opzioni di configurazione di ogni secret con una virgola. Il seguente comando aggiorna un secret montato come volume e un altro secret esposto come variabile di ambiente. Per aggiornare i secret esistenti, esegui questo comando:

  gcloud beta run instances deploy INSTANCE \
  --image IMAGE_URL \
  --update-secrets=PATH=SECRET_NAME:VERSION,ENV_VAR_NAME=SECRET_NAME:VERSION

• Per cancellare i secret esistenti e rendere accessibile un nuovo secret all'istanza, utilizza il flag --set-secrets:

  gcloud beta run instances update INSTANCE \
   --set-secrets="ENV_VAR_NAME=SECRET_NAME:VERSION"

YAML

1. Se stai creando una nuova istanza, ignora questo passaggio. Se stai aggiornando un'istanza esistente, scarica la relativa configurazione YAML:

   gcloud beta run instances describe INSTANCE --format export > instance.yaml

2. Per i secret esposti come variabili di ambiente:

   apiVersion: run.googleapis.com/v1
   kind: Instance
   metadata:
     name: INSTANCE
     annotations:
       run.googleapis.com/launch-stage: BETA
   spec:
     containers:
     - image: IMAGE_URL
       env:
       - name: ENV_VAR
         valueFrom:
           secretKeyRef:
             key: SECRET_VERSION
             name: SECRET_NAME

   Sostituisci quanto segue:

   • INSTANCE: il nome dell'istanza Cloud Run.
   • IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/hello:latest.
   • ENV_VAR: il nome della variabile di ambiente.
   • SECRET_VERSION: la versione del secret. Utilizza latest per l'ultima versione o un numero, ad esempio 2.
   • SECRET_NAME: il nome del secret, ad esempio mysecret.

3. Per i secret montati come percorsi di file:

   apiVersion: run.googleapis.com/v1
   kind: Instance
   metadata:
     name: INSTANCE
     annotations:
       run.googleapis.com/launch-stage: BETA
   spec:
     containers:
     - image: IMAGE_URL
       volumeMounts:
       - name: VOLUME_NAME
         mountPath: MOUNT_PATH
     volumes:
     - name: VOLUME_NAME
       secret:
         secretName: SECRET_NAME
         items:
         - key: SECRET_VERSION
           path: SECRET_NAME

   Sostituisci quanto segue:

   • INSTANCE: il nome dell'istanza Cloud Run.
   • IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/hello:latest.
   • VOLUME_NAME: il nome che vuoi assegnare al volume.
   • MOUNT_PATH: il percorso relativo in cui stai montando il volume, ad esempio /mnt/my-volume.
   • SECRET_NAME: il nome del secret, ad esempio mysecret.
   • SECRET_VERSION: la versione del secret. Utilizza latest per l'ultima versione o un numero, ad esempio 2.

4. Sostituisci l'istanza con la nuova configurazione utilizzando il seguente comando:

   gcloud beta run services replace service.yaml

Fare riferimento ai secret di altri progetti

Per fare riferimento a un secret che si trova in un altro progetto, verifica che l'account istanza del tuo progetto abbia accesso al secret.

gcloud

Per fare riferimento a un secret come variabile di ambiente, esegui questo comando:

gcloud beta run instances deploy INSTANCE \
    --image IMAGE_URL \
    --update-secrets=ENV_VAR_NAME=projects/PROJECT_NUMBER/secrets/SECRET_NAME:VERSION

Sostituisci quanto segue:

• INSTANCE: il nome dell'istanza.
• IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/hello:latest.
• PROJECT_NUMBER: il numero del progetto in cui è stato creato il secret.
• SECRET_NAME: il nome del secret, ad esempio mysecret.
• VERSION: la versione del secret. Utilizza latest per l'ultima versione o un numero, ad esempio 2.

YAML

1. Se stai creando una nuova istanza, ignora questo passaggio. Se stai aggiornando un'istanza esistente, scarica la relativa configurazione YAML:

   gcloud beta run instances describe INSTANCE --format export > instance.yaml

2. Per i secret esposti come variabili di ambiente:

   apiVersion: run.googleapis.com/v1
   kind: Instance
   metadata:
     name: INSTANCE
     annotations:
       run.googleapis.com/launch-stage: BETA
       metadata:
         annotations:
           run.googleapis.com/secrets: SECRET_LOOKUP_NAME:projects/PROJECT_NUMBER/secrets/SECRET_NAME
       spec:
         containers:
         - image: IMAGE_URL
           env:
           - name: ENV_VAR
             valueFrom:
               secretKeyRef:
                 key: SECRET_VERSION
                 name: SECRET_LOOKUP_NAME

   Sostituisci quanto segue:

   • INSTANCE: il nome dell'istanza Cloud Run.
   • SECRET_LOOKUP_NAME: qualsiasi nome con una sintassi valida per il nome secret, ad esempio my-secret, che può essere uguale a SECRET_NAME.
   • PROJECT_NUMBER: il numero del progetto in cui è stato creato il secret.
   • SECRET_NAME: il nome del secret, ad esempio mysecret.
   • IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/hello:latest.
   • ENV_VAR: il nome della variabile di ambiente.
   • SECRET_VERSION: la versione del secret. Utilizza latest per l'ultima versione o un numero, ad esempio 2.

3. Per i secret montati come percorsi di file:

   apiVersion: run.googleapis.com/v1
   kind: Instance
   metadata:
     name: INSTANCE
     annotations:
       run.googleapis.com/launch-stage: BETA
   metadata:
     annotations:
       run.googleapis.com/secrets: SECRET_LOOKUP_NAME:projects/PROJECT_NUMBER/secrets/SECRET_NAME
   spec:
     containers:
     - image: IMAGE_URL
       volumeMounts:
       - name: VOLUME_NAME
         mountPath: MOUNT_PATH
     volumes:
     - name: VOLUME_NAME
       secret:
         secretName: SECRET_NAME
         items:
         - key: SECRET_VERSION
           path: SECRET_LOOKUP_NAME

   Sostituisci quanto segue:

   • INSTANCE: il nome dell'istanza Cloud Run.
   • SECRET_LOOKUP_NAME: qualsiasi nome con una sintassi valida per il nome secret, ad esempio my-secret. Può essere uguale a SECRET_NAME.
   • PROJECT_NUMBER: il numero del progetto in cui è stato creato il secret.
   • SECRET_NAME: il nome del secret, ad esempio mysecret.
   • IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/hello:latest.
   • VOLUME_NAME: il nome che vuoi assegnare al volume.
   • MOUNT_PATH: il percorso relativo in cui stai montando il volume, ad esempio /mnt/my-volume.
   • SECRET_VERSION: la versione del secret. Utilizza latest per l'ultima versione o un numero, ad esempio 2.

4. Sostituisci l'istanza con la nuova configurazione utilizzando il seguente comando:

   gcloud beta run instances replace instance.yaml

Visualizza le impostazioni dei secret

Per visualizzare le impostazioni dei secret attuali per l'istanza Cloud Run:

gcloud

1. Esegui questo comando:

   gcloud beta run instances describe INSTANCE

2. Individua l'impostazione dei secret nella configurazione restituita.

Rimuovere i secret da un'istanza

Puoi rimuovere i secret da un'istanza utilizzando gcloud CLI:

gcloud

Puoi rimuovere tutti i secret da un'istanza o specificare uno o più secret da rimuovere.

Per rimuovere tutti i secret, esegui questo comando:

  gcloud beta run instances deploy INSTANCE --image IMAGE_URL \
      --clear-secrets

Sostituisci quanto segue:

• INSTANCE: il nome dell'istanza.
• IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/hello:latest.

Per specificare un elenco di secret da rimuovere, utilizza il flag --remove-secrets. Il seguente comando rimuove un secret montato come volume e un altro secret esposto come variabile di ambiente:

  gcloud beta run instances deploy INSTANCE --image IMAGE_URL \
      --remove-secrets=ENV_VAR_NAME,SECRET_FILE_PATH

Sostituisci quanto segue:

• INSTANCE: il nome dell'istanza.
• IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/hello:latest.
• ENV_VAR_NAME: il nome della variabile di ambiente.

• SECRET_FILE_PATH: il percorso completo del secret. Ad esempio, /mnt/secrets/primary/latest, dove /mnt/secrets/primary/ è il percorso di montaggio e latest è il percorso del secret. Puoi anche specificare i percorsi di montaggio e del secret separatamente:

  --set-secrets MOUNT_PATH:SECRET_PATH=SECRET:VERSION

Utilizzare i secret nel codice

Per esempi di accesso ai secret nel codice come variabili di ambiente, consulta il tutorial sull'autenticazione degli utenti finali, in particolare la sezione Gestione della configurazione sensibile con Secret Manager.

Limitazioni

Le sezioni seguenti descrivono le limitazioni che si applicano al montaggio dei secret.

Percorsi non consentiti

• Cloud Run non consente di montare i secret in /dev, /proc e /sys o nelle relative sottodirectory.
• Cloud Run non consente di montare più secret nello stesso percorso perché non è possibile montare due volumi nella stessa posizione.

Secret regionali

Cloud Run non supporta i secret regionali.

Eseguire l'override di una directory

Se il secret viene montato come volume in Cloud Run e l'ultima directory nel percorso di montaggio del volume esiste già, tutti i file o le cartelle nella directory esistente diventano inaccessibili.

Ad esempio, se un secret denominato my-secret viene montato sul percorso /etc/app_data, tutti i contenuti all'interno della directory app_data verranno sovrascritti e l'unico file visibile è /etc/app_data/my-secret.

Per evitare di sovrascrivere i file in una directory esistente, crea una nuova directory per il montaggio del secret, ad esempio /etc/app_data/secrets, in modo che il percorso di montaggio del secret sia /etc/app_data/secrets/my-secret.