Auf dieser Seite erfahren Sie, wie Sie den AlloyDB Auth-Proxy einrichten und verwenden, um autorisierte, verschlüsselte Verbindungen zu AlloyDB-Instanzen herzustellen. Eine konzeptionelle Übersicht über den Auth-Proxy finden Sie unter AlloyDB Auth-Proxy.
Wenn Sie den AlloyDB Auth-Proxy verwenden möchten, führen Sie einige einmalige Einrichtungsschritte aus, starten Sie den Auth-Proxy-Client und stellen Sie dann über ihn eine Verbindung zu Datenbanken her:
- Einrichtungsschritte:
- Laden Sie den Auth-Proxy-Client auf Ihren Clienthost herunter.
- Wählen Sie das IAM-Hauptkonto (Identity and Access Management) für die Autorisierung aus, prüfen Sie, ob es die erforderlichen Berechtigungen hat, und sorgen Sie dafür, dass die Anmeldedaten auf Ihrem Clienthost verfügbar sind.
- Erfassen Sie die Verbindungs-URIs für die AlloyDB-Instanzen, zu denen Sie eine Verbindung herstellen möchten.
- Starten Sie den Auth-Proxy-Client auf Ihrem Clienthost.
- Verbinden Sie eine Anwendung mit einer Datenbank, indem Sie eine lokale Verbindung zum Auth-Proxy-Client herstellen.
Hinweise
-
Der Clienthost muss die folgenden Anforderungen erfüllen:
Es muss Netzwerksichtbarkeit für das Virtual Private Cloud-Netzwerk (VPC) haben, in dem sich die Instanzen befinden, mit denen Sie eine Verbindung herstellen möchten. Clienthosts (z. B. Compute Engine-Instanzen) in diesem VPC-Netzwerk (Virtual Private Cloud) haben diese Sichtbarkeit von Natur aus. Clienthosts in externen Netzwerken (lokalen Netzwerken oder anderen VPC-Netzwerken) haben diese Sichtbarkeit, wenn das VPC-Netzwerk der AlloyDB-Instanz über einen Cloud-VPN-Tunnel oder einen VLAN-Anhang für Dedicated Interconnect oder Partner Interconnect mit dem externen Netzwerk verbunden ist.
Wenn der Clienthost eine Firewallrichtlinie für ausgehende Verbindungen hat, muss sie ausgehende Verbindungen zu Port
5433
auf den IP-Adressen Ihrer AlloyDB-Instanzen und ausgehende Verbindungen zu Port443
(dem Standard-HTTPS-Port) zu allen IP-Adressen zulassen.Wenn Sie eine Compute Engine-Instanz als Clienthost verwenden, muss sie den Zugriffsbereich
https://www.googleapis.com/auth/cloud-platform
haben, damit sie die AlloyDB Admin API verwenden kann. Ändern Sie bei Bedarf den Zugriffsbereich, um diesen Bereich einzubeziehen.
Auth-Proxyclient herunterladen
Der Computer, auf den Sie den Auth-Proxy-Client herunterladen, hängt davon ab, ob Sie eine Verbindung zu Ihren AlloyDB-Instanzen von innerhalb oder außerhalb des VPC-Netzwerks herstellen möchten.
Wenn Sie eine Verbindung zu Ihrem Cluster über den Zugriff auf private Dienste herstellen möchten, können Sie den Auth-Proxy-Client auf eine Compute Engine-VM-Instanz herunterladen, die in dem VPC-Netzwerk ausgeführt wird, das Zugriff auf private Dienste für Ihren Cluster hat.
Wenn Sie eine Verbindung zu Ihrem Cluster von außerhalb der VPC herstellen möchten, hängt die Maschine, auf der Sie die Installation vornehmen, von der verwendeten Strategie für externe Verbindungen ab. Sie können den Auth-Proxy-Client beispielsweise auf einem macOS- oder Windows-Computer installieren, der lokal für Ihre Anwendung ist, und dann einen SOCKS-Server verwenden, der in Ihrem AlloyDB-VPC-Netzwerk ausgeführt wird, als Verbindungsvermittler. Weitere Informationen finden Sie unter Verbindung zu einem Cluster von außerhalb des VPC herstellen.
Linux
64-Bit (AMD)
Laden Sie den Auth-Proxy-Client herunter:
wget https://storage.googleapis.com/alloydb-auth-proxy/v1.12.2/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy
Machen Sie den Auth-Proxyclient ausführbar:
chmod +x alloydb-auth-proxy
32-Bit (AMD)
Laden Sie den Auth-Proxy-Client herunter:
wget https://storage.googleapis.com/alloydb-auth-proxy/v1.12.2/alloydb-auth-proxy.linux.386 -O alloydb-auth-proxy
Machen Sie den Auth-Proxyclient ausführbar:
chmod +x alloydb-auth-proxy
64-Bit (ARM)
Laden Sie den Auth-Proxy-Client herunter:
wget https://storage.googleapis.com/alloydb-auth-proxy/v1.12.2/alloydb-auth-proxy.linux.arm64 -O alloydb-auth-proxy
Machen Sie den Auth-Proxyclient ausführbar:
chmod +x alloydb-auth-proxy
32-Bit (ARM)
Laden Sie den Auth-Proxy-Client herunter:
wget https://storage.googleapis.com/alloydb-auth-proxy/v1.12.2/alloydb-auth-proxy.linux.arm -O alloydb-auth-proxy
Machen Sie den Auth-Proxyclient ausführbar:
chmod +x alloydb-auth-proxy
macOS
M1
Laden Sie den Auth-Proxy-Client herunter:
curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.12.2/alloydb-auth-proxy.darwin.arm64
Machen Sie den Auth-Proxyclient ausführbar:
chmod +x alloydb-auth-proxy
64-Bit
Laden Sie den Auth-Proxy-Client herunter:
curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.12.2/alloydb-auth-proxy.darwin.amd64
Machen Sie den Auth-Proxyclient ausführbar:
chmod +x alloydb-auth-proxy
32-Bit
Laden Sie den Auth-Proxy-Client herunter:
curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.12.2/alloydb-auth-proxy.darwin.386
Machen Sie den Auth-Proxyclient ausführbar:
chmod +x alloydb-auth-proxy
Windows
64-Bit
Klicken Sie mit der rechten Maustaste auf https://storage.googleapis.com/alloydb-auth-proxy/v1.12.2/alloydb-auth-proxy-x64.exe und wählen Sie Link speichern unter aus, um den Auth Proxy-Client herunterzuladen.
Benennen Sie die Datei in alloydb-auth-proxy.exe
um.
32-Bit
Klicken Sie mit der rechten Maustaste auf https://storage.googleapis.com/alloydb-auth-proxy/v1.12.2/alloydb-auth-proxy-x86.exe und wählen Sie Link speichern unter aus, um den Auth-Proxy-Client herunterzuladen.
Benennen Sie die Datei in alloydb-auth-proxy.exe
um.
Docker-Image
Der Einfachheit halber sind mehrere Container-Images, die den Auth-Proxy-Client enthalten, in der Container Registry verfügbar.
Mit folgendem Befehl können Sie das neueste Image mithilfe von Docker auf Ihren lokalen Computer übertragen:
docker pull gcr.io/alloydb-connectors/alloydb-auth-proxy:latest
Andere Betriebssysteme
Bei anderen Betriebssystemen, die hier nicht aufgeführt sind, können Sie den Auth-Proxy-Client aus der Quelle kompilieren.
IAM-Hauptkonto auswählen und für die Autorisierung vorbereiten
Der AlloyDB Auth-Proxy unterstützt die Verwendung dieser Arten von IAM-Principals, um Verbindungen zwischen Ihrem Client und einer AlloyDB-Instanz zu autorisieren:
Ein vom Nutzer verwaltetes Dienstkonto Sie können ein IAM-Dienstkonto für Ihre Anwendung erstellen und dann Verbindungen damit autorisieren.
Google empfiehlt dringend, in Produktionsumgebungen ein Dienstkonto für die Autorisierung zu verwenden.
Ihr Nutzerkonto Sie können Verbindungen mit Ihrem eigenen IAM-Nutzerkonto autorisieren.
Die Verwendung eines eigenen Nutzerkontos ist in Entwicklungsumgebungen praktisch, in denen Sie AlloyDB-Ressourcen mit der gcloud CLI verwalten, die Datenbank mit einem Tool wie
psql
entwickeln und Anwendungscode auf demselben Host entwickeln.Das standardmäßige Compute Engine-Dienstkonto Wenn der Clienthost eine Compute Engine-Instanz ist, können Sie das Standarddienstkonto der Compute Engine verwenden, um Verbindungen zu autorisieren.
Nachdem Sie das zu verwendende IAM-Hauptkonto ausgewählt haben, müssen Sie dafür sorgen, dass es die erforderlichen IAM-Berechtigungen hat und dass seine Anmeldedaten auf Ihrem Clienthost verfügbar sind.
Erforderliche IAM-Berechtigungen
Das IAM-Hauptkonto, das Sie zum Autorisieren von Verbindungen verwenden, muss die Berechtigungen der vordefinierten Rollen roles/alloydb.client
(Cloud AlloyDB-Client) und roles/serviceusage.serviceUsageConsumer
(Nutzer der Servicenutzung) haben.
So weisen Sie einem IAM-Principal die Rolle „Cloud AlloyDB-Client“ zu:
Die Cloud Resource Manager API muss im Google Cloud-Projekt aktiviert sein.
Sie benötigen die grundlegende IAM-Rolle
roles/owner
(Inhaber) im Google Cloud-Projekt oder eine Rolle mit den folgenden Berechtigungen:resourcemanager.projects.get
resourcemanager.projects.getIamPolicy
resourcemanager.projects.setIamPolicy
Bitten Sie Ihren Administrator, Ihnen die Rolle
roles/resourcemanager.projectIamAdmin
(IAM-Administrator für das Projekt) zuzuweisen, damit Sie diese Berechtigungen erhalten und dabei dem Prinzip der geringsten Berechtigung folgen.
IAM-Anmeldedaten auf dem Clienthost verfügbar machen
Wie Sie IAM-Anmeldedaten auf dem Clienthost verfügbar machen, hängt davon ab, welchen Typ von IAM-Hauptkonto Sie für die Autorisierung von Verbindungen verwenden:
Nutzerverwaltetes Dienstkonto
Wenn Sie IAM-Anmeldedaten für ein nutzerverwaltetes Dienstkonto angeben möchten, erstellen Sie einen Dienstkontoschlüssel im JSON-Format und laden Sie ihn auf Ihren Clienthost herunter. Geben Sie beim Starten des Auth Proxy-Clients den Speicherort der Schlüsseldatei mit dem Flag
--credentials-file
an.Ihr Nutzerkonto
Wenn Sie IAM-Anmeldedaten für Ihr Nutzerkonto angeben möchten, installieren Sie die Google Cloud CLI auf Ihrem Clienthost und führen Sie den Befehl
gcloud init
aus, um sie mit Ihrem Nutzerkonto zu initialisieren. Wenn Sie den Auth-Proxy-Client starten, werden Ihre Nutzerkonto-Anmeldedaten automatisch erkannt und verwendet, wenn Sie keine nutzerverwalteten Dienstkonto-Anmeldedaten angeben.Standardmäßiges Compute Engine-Dienstkonto
Wenn Sie eine Compute Engine-Instanz als Clienthost verwenden, sind die Anmeldedaten für das Standarddienstkonto der Compute Engine bereits auf dem Host vorhanden. Wenn Sie den Auth Proxy-Client starten, werden diese Anmeldedaten automatisch erkannt und verwendet, wenn keine vom Nutzer verwalteten Anmeldedaten für Dienst- und Nutzerkonten verfügbar sind.
Verbindungs-URIs für die AlloyDB-Instanzen erfassen
Wenn Sie den Auth-Proxy-Client starten, geben Sie die AlloyDB-Instanz oder ‑Instanzen an, mit denen Sie eine Verbindung herstellen möchten. Verwenden Sie dazu das folgende Format für den Verbindungs-URI:
projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID
Verwenden Sie den Befehl alloydb instances list
der gcloud CLI, um eine Liste der Verbindungs-URIs aller Instanzen aufzurufen.
Erfassen Sie den URI der Instanzverbindung für jede Instanz, zu der Sie eine Verbindung herstellen möchten.
Auth-Proxy-Client starten
Wenn Sie den Auth-Proxy-Client starten, geben Sie Informationen dazu an, mit welchen AlloyDB-Instanzen eine Verbindung hergestellt werden soll, und gegebenenfalls Anmeldedaten, die bei der Autorisierung dieser Verbindungen verwendet werden sollen.
Beim Starten führt der Auth-Proxy-Client folgende Schritte aus:
- Autorisiert Verbindungen zu AlloyDB-Instanzen mit den Anmeldedaten und IAM-Berechtigungen des von Ihnen konfigurierten IAM-Principals. Dabei wird eine bestimmte Abfolge von Schritten ausgeführt.
- Autorisiert öffentliche IP-Verbindungen zum Quellnetzwerk automatisch, wenn für die Instanz die öffentliche IP-Adresse aktiviert ist.
- Konfiguriert eine private TLS 1.3-Verbindung zum Auth-Proxy-Server jeder Instanz.
- Es wird damit begonnen, auf lokale Clientverbindungsanfragen zu warten.
Standardmäßig wartet der Auth-Proxy-Client auf TCP-Verbindungen an der IP-Adresse 127.0.0.1, beginnend bei Port 5432 und mit einer Erhöhung der Portnummer um eins für jede AlloyDB-Instanz nach der ersten. Sie können beim Starten des Auth-Proxy-Clients eine andere Listeneradresse und andere Ports angeben.
Befehlszeile
./alloydb-auth-proxy INSTANCE_URI... \
[ --credentials-file PATH_TO_KEY_FILE \ ]
[ --token OAUTH_ACCESS_TOKEN \ ]
[ --port INITIAL_PORT_NUMBER \ ]
[ --address LOCAL_LISTENER_ADDRESS \ ]
[ --auto-iam-authn ] \
[ --psc] \
[ --public-ip]
Ersetzen Sie Folgendes:
INSTANCE_URI
: der Instanzverbindungs-URI einer AlloyDB-Instanz, mit der eine Verbindung hergestellt werden soll, im folgenden Format:projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID
Sie können den Standard-lokalen Listener-Port, den der Auth-Proxy-Client für die Instanz verwendet, überschreiben, indem Sie dem URI den Abfrageparameter
port
hinzufügen:"projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"
Optional:
PATH_TO_KEY_FILE
: Der Pfad zur JSON-Schlüsseldatei des nutzerverwalteten Dienstkontos, das für die Verbindungsautorisierung verwendet werden soll.Optional:
OAUTH_ACCESS_TOKEN
: Ein OAuth2-Tokenwert, der für die Verbindungsautorisierung verwendet werden soll.Optional:
INITIAL_PORT_NUMBER
: Die Startportnummer, die anstelle des Standardports5432
verwendet werden soll, wenn auf lokale TCP-Verbindungen gewartet wird.Optional:
LOCAL_LISTENER_ADDRESS
: Die Listeneradresse, die anstelle der Standardadresse127.0.0.1
verwendet werden soll, wenn auf lokale TCP-Verbindungen gewartet wird.
Mit dem optionalen Flag --auto-iam-authn
wird die automatische Authentifizierung bei der Instanz ermöglicht. Dies funktioniert nur für den Datenbanknutzer, der mit dem IAM-Konto verknüpft ist, auf dem der Auth-Proxy-Client ausgeführt wird. Weitere Informationen finden Sie unter Automatische Authentifizierung über den Auth-Proxy.
Mit dem optionalen Flag --psc
kann der Auth-Proxy eine Verbindung zu einer Instanz herstellen, für die Private Service Connect aktiviert ist. Weitere Informationen zum Einrichten von DNS mit Private Service Connect finden Sie unter Eine verwaltete DNS-Zone und einen DNS-Eintrag konfigurieren.
Mit dem optionalen Flag --public-ip
kann der Auth-Proxy über die öffentliche IP-Adresse einer Instanz eine Verbindung zu einer Instanz herstellen, für die eine öffentliche IP-Adresse aktiviert ist. Weitere Informationen zu öffentlichen IP-Adressen finden Sie unter Verbindung über öffentliche IP-Adresse herstellen.
Docker-Container
Starten Sie den Auth-Proxy-Client mit dem Befehl docker run
.
Wenn Sie die von Ihrer Compute Engine-Instanz bereitgestellten Anmeldedaten verwenden, können Sie einen Befehl wie den folgenden verwenden:
docker run \
--publish 127.0.0.1:PORT:PORT \
gcr.io/alloydb-connectors/alloydb-auth-proxy:latest \
--address 0.0.0.0 \
--port PORT \
INSTANCE_URI
Ersetzen Sie Folgendes:
PORT
: Der Port, der für lokale Verbindungen zum Auth-Proxy-Client verwendet werden soll. Der Standardwert ist5432
.INSTANCE_URI
: Der Instanzverbindungs-URI einer AlloyDB-Instanz, mit der eine Verbindung hergestellt werden soll. Er muss im folgenden Format angegeben werden:projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID
Sie können den Standard-lokalen Listener-Port, den der Auth-Proxy-Client für die Instanz verwendet, überschreiben, indem Sie dem URI den Abfrageparameter
port
hinzufügen:"projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"
Geben Sie in --publish
immer das Präfix 127.0.0.1
an, damit der Auth-Proxy-Client nicht außerhalb des lokalen Hosts bereitgestellt wird.
Der Wert 0.0.0.0
im Flag --address
ist erforderlich, damit der Listener von außerhalb des Docker-Containers zugänglich ist.
Wenn Sie Anmeldedaten angeben möchten, die Sie in einer lokalen JSON-Datei gespeichert haben, fügen Sie beim Ausführen des Befehls docker run
die Flags --volume
und --credentials-file
hinzu:
docker run \
--volume PATH_TO_KEY_FILE:/key.json \
--publish 127.0.0.1:PORT:PORT \
gcr.io/alloydb-connectors/alloydb-auth-proxy:latest \
--address 0.0.0.0 \
--port PORT \
--credentials-file=/key.json \
INSTANCE_URI
Ersetzen Sie PATH_TO_KEY_FILE
durch den Pfad zur JSON-Schlüsseldatei des nutzerverwalteten Dienstkontos, das für die Verbindungsautorisierung verwendet werden soll.
Beispiele für Start-ups
Die folgenden Beispiele zeigen verschiedene Möglichkeiten, den Auth-Proxy-Client zu starten. Dabei werden die folgenden Beispiel-URIs für die Instanzverbindung verwendet:
projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary
projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool
Einfacher Start
./alloydb-auth-proxy \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary"
In diesem Beispiel autorisiert der Auth-Proxy-Client die Verbindung, indem er der normalen Abfolge der Autorisierungsschritte folgt, und beginnt dann, auf lokale Verbindungen zur myprimary
-Instanz auf 127.0.0.1:5432
zu warten.
Start mit einem vom Nutzer verwalteten Dienstkonto
./alloydb-auth-proxy \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \\
--credentials-file "myappaccount/key.json"
In diesem Beispiel autorisiert der Auth-Proxy-Client die Verbindung mit dem JSON-Schlüssel des nutzerverwalteten Dienstkontos, der unter myappaccount/key.json
gespeichert ist, und beginnt dann, auf lokale Verbindungen zur myprimary
-Instanz unter 127.0.0.1:5432
zu warten.
Startzeit bei Verbindung zu mehreren Instanzen
./alloydb-auth-proxy \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool"
In diesem Beispiel autorisiert der Auth-Proxy-Client die Verbindung, indem er der normalen Abfolge der Autorisierungsschritte folgt, und überwacht dann lokale Verbindungen zur myprimary
-Instanz auf 127.0.0.1:5432
und zur myreadpool
-Instanz auf 127.0.0.1:5433
.
Starten und Überwachen von benutzerdefinierten Ports
Die Verwendung benutzerdefinierter Ports für den Auth-Proxy-Client kann nützlich sein, wenn Sie Port 5432
für andere PostgreSQL-Verbindungen reservieren müssen.
./alloydb-auth-proxy \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary?port=5000" \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool?port=5001"
In diesem Beispiel autorisiert der Auth-Proxy-Client die Verbindung, indem er der normalen Abfolge der Autorisierungsschritte folgt, und überwacht dann lokale Verbindungen zur myprimary
-Instanz auf 127.0.0.1:5000
und zur myreadpool
-Instanz auf 127.0.0.1:5001
.
Da diese benutzerdefinierten Ports sequenziell sind, kann derselbe Effekt mit diesem Startbefehl erzielt werden:
./alloydb-auth-proxy \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool" \
--port 5000
Starten und Zuhören auf einer benutzerdefinierten IP-Adresse
./alloydb-auth-proxy \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
--address "0.0.0.0"
In diesem Beispiel autorisiert der Auth-Proxy-Client die Verbindung, indem er der normalen Abfolge der Autorisierungsschritte folgt, und beginnt dann, auf lokale Verbindungen zur myprimary
-Instanz auf 0.0.0.0:5432
zu warten.
Anwendung über den AlloyDB Auth-Proxy mit einer Datenbank verbinden
In den folgenden Beispielen wird gezeigt, wie Sie eine Anwendung mithilfe des AlloyDB Auth-Proxy mit einer Datenbank verbinden.
Das psql
-Beispiel zeigt, wie eine Verbindung zu einem Befehlszeilentool hergestellt wird.
Das Herstellen einer Verbindung zu einer AlloyDB-Instanz über den AlloyDB Auth-Proxy entspricht für mehrere Programmiersprachen dem Herstellen einer Verbindung zu einer Cloud SQL for PostgreSQL-Instanz über den Cloud SQL Auth-Proxy. Die Sprachbeispiele hier sind daher mit denen für Cloud SQL for PostgreSQL identisch.
Diese Beispiele basieren auf einem standardmäßigen Start des Auth-Proxy-Clients, sodass er auf lokale TCP-Verbindungen an 127.0.0.1:5432
wartet.
psql
psql -h 127.0.0.1 -p 5432 -U DB_USER
Ersetzen Sie DB_USER
durch den Datenbanknutzer, als der Sie eine Verbindung herstellen möchten, z. B. postgres
.
Sie werden aufgefordert, das Passwort des Nutzers DB_USER
einzugeben.
Python
Java
Node.js
Go
Wenn Sie dieses Snippet im Kontext einer Webanwendung sehen möchten, rufen Sie die README-Datei auf GitHub auf.
C#
Wenn Sie dieses Snippet im Kontext einer Webanwendung sehen möchten, rufen Sie die README-Datei auf GitHub auf.
Ruby
Wenn Sie dieses Snippet im Kontext einer Webanwendung sehen möchten, rufen Sie die README-Datei auf GitHub auf.
PHP
Wenn Sie dieses Snippet im Kontext einer Webanwendung sehen möchten, rufen Sie die README-Datei auf GitHub auf.