IAM-Authentifizierung verwalten

Auf dieser Seite finden Sie eine Anleitung zu häufigen Aufgaben für das Feature zur IAM-Authentifizierung für Memorystore for Valkey. Weitere Informationen zu diesem Feature finden Sie unter IAM-Authentifizierung.

Instanz mit IAM-Authentifizierung erstellen

Führen Sie den Befehl create aus, um eine Memorystore for Valkey-Instanz zu erstellen, die die IAM-Authentifizierung verwendet:

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

Ersetzen Sie Folgendes:

• INSTANCE_ID ist die ID der Memorystore for Valkey-Instanz, die Sie erstellen. Die Instanz-ID muss zwischen 1 und 63 Zeichen lang sein und darf nur Kleinbuchstaben, Ziffern oder Bindestriche enthalten. Sie muss mit einem Kleinbuchstaben beginnen und mit einem Kleinbuchstaben oder einer Ziffer enden.

• REGION_ID ist die Region, in der die Instanz platziert werden soll.

• NETWORK ist das Netzwerk, das zum Erstellen der Instanz verwendet wird. Es muss das Format projects/NETWORK_PROJECT_ID/global/networks/NETWORK_ID haben. Die hier verwendete Netzwerk-ID muss mit der Netzwerk-ID übereinstimmen, die von der Richtlinie für die Dienstverbindung verwendet wird. Andernfalls schlägt der Vorgang create fehl. Weitere Informationen finden Sie unter Netzwerke.

• NODE_TYPE ist der Knotentyp für die Instanz.

  Achtung: Wir empfehlen, den shared-core-nano Knotentyp nur für Entwicklungs- oder Testzwecke zu verwenden da für diesen Knotentyp kein SLA gilt. Wenn Sie Memorystore for Valkey in einer Produktionsumgebung ausführen, empfehlen wir, einen anderen Knotentyp zu verwenden.

• SHARD_COUNT bestimmt die Anzahl der Shards in Ihrer Instanz. Die Anzahl der Shards bestimmt die Gesamtspeicherkapazität zum Speichern von Instanzdaten. Weitere Informationen zu den Instanzspezifikationen finden Sie unter Instanz- und Knotenspezifikationen.

Berechtigungen für die IAM-Authentifizierung gewähren

Wenn Sie einen IAM-Zugriff gewähren möchten, weisen Sie dem Hauptkonto die roles/memorystore.dbConnectionUser Rolle zu. Folgen Sie dazu der Anleitung unter IAM-Rolle gewähren.

Standardmäßig kann ein Hauptkonto nach dem Zuweisen der Rolle roles/memorystore.dbConnectionUser auf alle Instanzen in Ihrem Projekt zugreifen.

Hinweis: Eine Anleitung zum Einschränken des Nutzerzugriffs pro Instanz finden Sie unter Zugriff auf eine Gruppe von Ressourcen anhand von Ressourcennamenspräfixen gewähren. Wenn Sie den Zugriff auf Ihre Instanz einschränken, verwenden Sie das Attribut resource.name und das folgende Format für den Instanznamen: projects/PROJECT/locations/REGION/instances/INSTANCE_NAME.

Eingeschränkte IAM-Administratorrolle für eine Instanz erstellen

Möglicherweise möchten Sie eine Rolle erstellen, mit der IAM-Berechtigungen für die Instanzverbindung geändert werden können, ohne vollständigen IAM-Administratorzugriff zu gewähren. Dazu können Sie einen eingeschränkten IAM-Administrator für die Rolle roles/memorystore.dbConnectionUser erstellen. Weitere Informationen finden Sie unter Eingeschränkte IAM-Administratoren erstellen.

Verbindung zu einer Instanz herstellen, die die IAM-Authentifizierung verwendet

1. Wenn Sie noch keine Compute Engine-VM haben, die dasselbe autorisierte Netzwerk wie Ihre Valkey-Instanz verwendet, erstellen Sie eine VM und stellen Sie eine Verbindung zu ihr her. Folgen Sie dazu der Kurzanleitung: Linux-VM verwenden.

2. Aktivieren Sie für Ihr Projekt den Cloud Platform API-Bereich. Weitere Informationen zum Aktivieren dieses Zugriffsbereichs finden Sie unter Dienstkonto anhängen und Zugriffsbereich aktualisieren. Weitere Informationen zu Best Practices für diesen Bereich finden Sie unter Best Practices für Bereiche.

3. Aktivieren Sie für Ihr Projekt die Memorystore for Valkey API.

   Memorystore for Valkey API

4. Installieren Sie valkey-cli auf der Compute Engine-VM. Folgen Sie dazu der Anleitung unter Valkey installieren.

5. Führen Sie den folgenden Befehl aus, um ein Zugriffstoken für Ihren IAM-Nutzer abzurufen:

   gcloud auth print-access-token
   

   Zugriffstokens laufen nach einer Stunde ab. Weitere Informationen finden Sie unter Zeitraum für IAM-Zugriffstoken.

6. Stellen Sie eine Verbindung zum Discovery-Endpunkt Ihrer Instanz her:

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

   Ersetzen Sie Folgendes:

   • NETWORK_ADDRESS: die Netzwerkadresse der Instanz. Informationen zum Aufrufen der Netzwerkadresse finden Sie unter Instanzinformationen ansehen.

   • PORT: die Portnummer der Instanz. Informationen zum Aufrufen der Portnummer finden Sie unter Instanzinformationen ansehen.

   • ACCESS_TOKEN: das Zugriffstoken, das Sie in dem vorherigen Schritt abgerufen haben.

   Authentifizierte Verbindungen sind 12 Stunden lang gültig. Weitere Informationen finden Sie unter Zeitraum für IAM-Zugriffstoken.

   Wenn Sie die Verschlüsselung während der Übertragung für die Instanz aktivieren, müssen Sie die TLS-Flags (Transport Layer Security) anhängen. Beispiel:

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

7. Führen Sie den Befehl CLUSTER SHARDS aus, um die Knotentopologie aufzurufen. Notieren Sie sich die IP-Adresse und die Portnummer eines der Knoten.

8. Verwenden Sie den folgenden Befehl, um sich mit valkey-cli zu authentifizieren und eine Verbindung zu Ihrem Knoten herzustellen:

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

   Ersetzen Sie Folgendes:

   • NODE_IP_ADDRESS: die IP-Adresse des Knotens, die Sie im vorherigen Schritt notiert haben
   • NODE_PORT: die Portnummer des Knotens, die Sie im vorherigen Schritt notiert haben
   • ACCESS_TOKEN: das IAM-Zugriffstoken, das Sie zuvor in dieser Anleitung abgerufen haben

9. Führen Sie einen Valkey-Befehl SET und GET aus, um zu prüfen, ob Sie eine authentifizierte Verbindung zu Ihrem Knoten haben.

10. Löschen Sie die Compute Engine-VM die Sie zum Herstellen einer Verbindung zur Instanz verwendet haben. So vermeiden Sie, dass Ihrem Cloud-Rechnungskonto Gebühren in Rechnung gestellt werden.

Abrufen von Zugriffstokens automatisieren

Wir empfehlen dringend, das Abrufen von Zugriffstokens in Ihrer Anwendung zu automatisieren. Aufgrund der kurzen Lebensdauer eines Zugriffstokens ist es schwierig, das Token hartzucodieren.

1. (Optional) Wenn Sie es noch nicht getan haben, erstellen Sie ein Dienstkonto für Ihre Anwendung. Weitere Informationen finden Sie unter Dienstkonto erstellen und verwalten.

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

   Ersetzen Sie Folgendes:

   • SA_NAME ist der Name des Dienstkontos.
   • DESCRIPTION ist eine optionale Beschreibung des Dienstkontos.
   • DISPLAY_NAME ist ein Dienstkontoname, der in der Google Cloud Console angezeigt werden soll.

2. Weisen Sie Ihrem Dienstkonto die Rolle memorystore.dbConnectionUser für Ihr Projekt zu.

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

   Ersetzen Sie Folgendes:

   • PROJECT_ID: die Projekt-ID.
   • SA_NAME: der Name des Dienstkontos.
   • ROLE_NAME: ein Rollenname. In diesem Beispiel: memorystore.dbConnectionUser.

3. Authentifizieren Sie Ihre Anwendung als das angegebene Dienstkonto. Weitere Informationen finden Sie unter Dienstkonten.

   Codebeispiele, die zeigen, wie Sie Ihre Anwendung mit gängigen Clientbibliotheken authentifizieren können, finden Sie unter Codebeispiele für Clientbibliotheken.

Codebeispiel für das Herstellen einer Verbindung zu einer Instanz, die die IAM-Authentifizierung verwendet

Ein mit Valkey kompatibles Codebeispiel zum Einrichten einer Clientbibliothek für die Verbindung zu einer Instanz, die die IAM-Authentifizierung verwendet, finden Sie unter Codebeispiel für IAM-Authentifizierung und Verschlüsselung während der Übertragung.

Fehlermeldungen bei der IAM-Authentifizierung beheben

Fehlermeldung	Empfohlene Maßnahmen	Beschreibung
-WRONGPASS invalid username-password pair or user is disabled	Überprüfen Sie den Nutzernamen und das Zugriffstoken, die dem Memorystore for Valkey-Server bereitgestellt wurden.	Der angegebene Nutzername oder das Zugriffstoken ist ungültig. „default“ ist der einzige unterstützte Nutzername. Wenn Ihre Anwendung bereits den Nutzernamen „default“ verwendet, prüfen Sie, ob das Zugriffstoken nicht abgelaufen ist und gemäß der Anleitung unter Verbindung zu einer Instanz herstellen, die die IAM-Authentifizierung verwendet abgerufen wurde. Es kann einige Minuten dauern, bis IAM-Berechtigungen übernommen werden, wenn sie vor Kurzem geändert wurden.
-NOAUTH Authentication required	Prüfen Sie, ob die Anwendung so konfiguriert ist, dass sie dem Memorystore for Valkey-Server ein IAM-Zugriffstoken bereitstellt.	Die Anwendung stellt dem Memorystore for Valkey-Server kein Zugriffstoken bereit. Prüfen Sie, ob die Anwendung so konfiguriert ist, dass sie ein Zugriffstoken gemäß der Anleitung unter Verbindung zu einer Instanz herstellen, die die IAM-Authentifizierung verwendet bereitstellt.
-ERR (ERR_IAM_EXHAUSTED) Memorystore IAM authentication backend quota exceeded.	Mit exponentiellem Backoff wiederholen.	Das IAM-Backend ist überlastet und hat dem Memorystore for Valkey-Server einen Fehler wegen überschrittenem Kontingent zurückgegeben. Anwendungen sollten versuchen, diesen Fehler mit exponentiellem Backoff zu wiederholen, um weitere Verbindungsfehler zu vermeiden.
-ERR (ERR_IAM_OTHER) Memorystore IAM authentication backend error.	Mit exponentiellem Backoff wiederholen.	Das IAM-Backend hat dem Memorystore for Valkey-Server einen vorübergehenden Fehler zurückgegeben. Anwendungen sollten versuchen, diesen Fehler mit exponentiellem Backoff zu wiederholen, um weitere Verbindungsfehler zu vermeiden.