Gestire l'autenticazione IAM

Questa pagina fornisce istruzioni sulle attività comuni per la funzionalità di autenticazione IAM per Memorystore for Valkey. Per maggiori dettagli sulla funzionalità, consulta Informazioni sull'autenticazione IAM.

Creare un'istanza con autenticazione IAM

Per creare un'istanza Memorystore for Valkey che utilizza l'autenticazione IAM, esegui il comando create:

gcloud memorystore instances create INSTANCE_ID --region=REGION_ID --network=NETWORK --node-type=NODE_TYPE --shard-count=SHARD_COUNT --authorization-mode=iam-auth

Sostituisci quanto segue:

• INSTANCE_ID è l'ID dell'istanza Memorystore for Valkey che stai creando. L'ID istanza deve contenere da 1 a 63 caratteri e utilizzare solo lettere minuscole, numeri o trattini. Deve iniziare con una lettera minuscola e terminare con una lettera minuscola o un numero.

• REGION_ID è la regione in cui vuoi che si trovi l'istanza.

• NETWORK è la rete utilizzata per creare l'istanza. Deve utilizzare il formato: projects/NETWORK_PROJECT_ID/global/networks/NETWORK_ID. L'ID rete utilizzato qui deve corrispondere all'ID rete utilizzato dalla policy di connessione al servizio. In caso contrario, l'operazione create non riesce. Per maggiori dettagli, consulta Networking.

• NODE_TYPE è il tipo di nodo per l' istanza.

  Attenzione: ti consigliamo di utilizzare il tipo di nodo shared-core-nano solo per scopi di sviluppo o test perché questo tipo di nodo non ha uno SLA. Se esegui Memorystore for Valkey in un ambiente di produzione, ti consigliamo di utilizzare un altro tipo di nodo.

• SHARD_COUNT determina il numero di shard nell'istanza. Il numero di shard determina la capacità di memoria totale per l'archiviazione dei dati dell'istanza. Per visualizzare maggiori dettagli sulla specifica dell'istanza, consulta Specifica dell'istanza e del nodo.

Concedere le autorizzazioni per l'autenticazione IAM

Per concedere un accesso IAM, concedi all'entità il roles/memorystore.dbConnectionUser ruolo utilizzando le istruzioni per la concessione del ruolo IAM.

Per impostazione predefinita, la concessione del ruolo roles/memorystore.dbConnectionUser a un'entità consente all'entità di accedere a tutte le istanze del progetto.

Nota: Per istruzioni su come limitare l'accesso degli utenti in base all'istanza, consulta Concedere l'accesso a un gruppo di risorse in base ai prefissi dei nomi delle risorse. Quando concedi l'accesso limitato per l'istanza, utilizza l'attributo resource.name e il seguente formato per il nome dell'istanza: projects/PROJECT/locations/REGION/instances/INSTANCE_NAME.

Creare un ruolo di amministratore IAM limitato per un'istanza

Potresti voler creare un ruolo che possa modificare le autorizzazioni IAM di connessione all'istanza senza concedere l'accesso completo di amministratore IAM. Per farlo, puoi creare un amministratore IAM limitato per il ruolo roles/memorystore.dbConnectionUser. Per maggiori dettagli, visita Creare amministratori IAM limitati.

Connettersi a un'istanza che utilizza l'autenticazione IAM

1. Se non hai già una VM di Compute Engine che utilizza la stessa rete autorizzata dell'istanza Valkey, creane una e connettiti seguendo Guida rapida all'utilizzo di una VM Linux.

2. Per il tuo progetto, abilita l'ambito dell'API Cloud Platform. Per saperne di più su come abilitare questo ambito di accesso, consulta Collegare il account di servizio e aggiornare l'ambito di accesso. Per saperne di più sulle best practice per questo ambito, consulta Best practice per gli ambiti.

3. Per il tuo progetto, abilita l'API Memorystore for Valkey.

   API Memorystore for Valkey

4. Installa valkey-cli sulla VM di Compute Engine seguendo le istruzioni riportate in Installare Valkey.

5. Esegui il comando seguente per recuperare un token di accesso per il tuo utente IAM:

   gcloud auth print-access-token
   

   I token di accesso scadono dopo un'ora. Per saperne di più, consulta Periodo di validità del token di accesso IAM.

6. Connettiti all'endpoint di rilevamento dell'istanza:

   valkey-cli -h NETWORK_ADDRESS -p PORT -a ACCESS_TOKEN -c
   

   Sostituisci quanto segue:

   • NETWORK_ADDRESS: l'indirizzo di rete dell'istanza. Per visualizzare l' indirizzo di rete, consulta Visualizzare le informazioni sull'istanza.

   • PORT: il numero di porta dell'istanza. Per visualizzare il numero di porta, consulta Visualizzare le informazioni sull'istanza.

   • ACCESS_TOKEN: il token di accesso recuperato nel passaggio precedente.

   Se specifichi un nome utente, devi utilizzare il nome utente default o l'indirizzo email dell'entità IAM. Inoltre, le connessioni autenticate rimangono valide dopo la scadenza del token. Per saperne di più, consulta Periodo di validità del token di accesso IAM.

   Se abiliti la crittografia dei dati in transito sull'istanza, devi aggiungere i flag TLS (Transport Layer Security). Ad esempio:

   valkey-cli -h NETWORK_ADDRESS -p PORT -a ACCESS_TOKEN -c --tls --cacert /tmp/server_ca.pem
   

   Importante: se hai un'istanza con modalità cluster disabilitata, non utilizzare il flag -c.

7. (Facoltativo) Se hai un'istanza con modalità cluster abilitata, esegui il comando CLUSTER SHARDS per visualizzare la topologia dei nodi. Prendi nota di uno degli indirizzi IP e dei numeri di porta del nodo.

   Se hai un'istanza con modalità cluster disabilitata, puoi saltare questo passaggio.

8. Per utilizzare valkey-cli per autenticare e connetterti al nodo, utilizza il comando seguente:

   valkey-cli -h NODE_IP_ADDRESS -p NODE_PORT -a ACCESS_TOKEN -c
   

   Sostituisci quanto segue:

   • NODE_IP_ADDRESS: l'indirizzo IP del nodo annotato nel passaggio precedente
   • NODE_PORT: il numero di porta del nodo annotato nel passaggio precedente
   • ACCESS_TOKEN: il token di accesso IAM che hai recuperato in precedenza in questa procedura

9. Per verificare di avere una connessione autenticata al nodo, esegui un comando SET e GET di Valkey.

10. Elimina la VM di Compute Engine che hai utilizzato per connetterti all'istanza. In questo modo, eviti di incorrere in addebiti sul tuo account di fatturazione Cloud.

Automatizzare il recupero dei token di accesso

Ti consigliamo vivamente di automatizzare il recupero dei token di accesso nella tua applicazione. A causa della breve durata di un token di accesso, è difficile impostare come hardcoded il token.

1. (Facoltativo) Se non l'hai ancora fatto, crea un account di servizio per la tua applicazione (consulta Creare e gestire un service account).

   gcloud iam service-accounts create SA_NAME \
       --description="DESCRIPTION" \
       --display-name="DISPLAY_NAME"
   

   Sostituisci quanto segue:

   • SA_NAME è il nome del account di servizio.
   • DESCRIPTION è una descrizione facoltativa del account di servizio.
   • DISPLAY_NAME è il nome del account di servizio da visualizzare nella Google Cloud console.

2. Concedi al tuo account di servizio il ruolo memorystore.dbConnectionUser nel tuo progetto.

   gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
   --role=roles/"ROLE_NAME"
   

   Sostituisci quanto segue:

   • PROJECT_ID: l'ID progetto.
   • SA_NAME: il nome del account di servizio.
   • ROLE_NAME: il nome di un ruolo. Per questo esempio: memorystore.dbConnectionUser.

3. Autentica l'applicazione come il account di servizio specificato. Per saperne di più, consulta Service account.

   Per esempi di codice che mostrano come autenticare l'applicazione utilizzando le librerie client più comuni, consulta Esempi di codice della libreria client.

Esempio di codice per connettersi a un'istanza che utilizza l'autenticazione IAM

Per visualizzare un esempio di codice compatibile con Valkey su come configurare una libreria client per connettersi a un' istanza che utilizza l'autenticazione IAM, consulta Esempio di codice per l'autenticazione IAM e la crittografia dei dati in transito.

Risolvere i problemi relativi ai messaggi di errore con l'autenticazione IAM

Messaggio di errore	Comportamento consigliato	Descrizione
-WRONGPASS invalid username-password pair or user is disabled	Verifica il token di accesso fornito al server Memorystore for Valkey e assicurati che l'utente ACL corrispondente sia abilitato.	L'entità IAM non dispone delle autorizzazioni richieste, il token di accesso fornito non è valido o l'utente ACL corrispondente è disabilitato. Verifica che il token di accesso non sia scaduto e che tu l'abbia recuperato seguendo le istruzioni riportate in Connettersi a un'istanza che utilizza l'autenticazione IAM. Se di recente hai modificato le autorizzazioni IAM, la propagazione delle autorizzazioni potrebbe richiedere alcuni minuti.
-NOAUTH Authentication required	Verifica che l'applicazione sia configurata per fornire un token di accesso IAM al server Memorystore for Valkey.	L'applicazione non fornisce un token di accesso al server Memorystore for Valkey. Verifica che l'applicazione sia configurata per fornire un token di accesso e che tu l'abbia recuperato seguendo le istruzioni riportate in Connettersi a un'istanza che utilizza l'autenticazione IAM.
-ERR (ERR_IAM_EXHAUSTED) Memorystore IAM authentication backend quota exceeded.	Riprova con un backoff esponenziale.	Il backend IAM è sovraccarico e ha restituito un errore di superamento della quota al server Memorystore for Valkey. Per evitare ulteriori errori di connessione, ti consigliamo alle applicazioni di riprovare a eseguire questa operazione con un backoff esponenziale.
-ERR (ERR_IAM_OTHER) Memorystore IAM authentication backend error.	Verifica il nome utente o riprova con un backoff esponenziale.	Questo errore si verifica per i seguenti motivi: Il nome utente fornito non è valido. Puoi utilizzare il default nome utente, ometterlo o utilizzare l' indirizzo email dell'entità IAM. Il backend IAM ha restituito un errore temporaneo al Memorystore for Valkey server. Se il nome utente è valido, ti consigliamo alla tua applicazione di riprovare a eseguire questa operazione con un backoff esponenziale per evitare ulteriori errori di connessione.