Verbindung mit dem AlloyDB Auth-Proxy herstellen

Sie können den AlloyDB Auth-Proxy verwenden, um autorisierte, verschlüsselte Verbindungen zu AlloyDB-Instanzen herzustellen. Weitere Informationen finden Sie unter Informationen zum AlloyDB Auth-Proxy.

Wenn Sie den AlloyDB Auth-Proxy verwenden möchten, müssen Sie mehrere einmalige Einrichtungsschritte ausführen. Anschließend starten Sie den Auth-Proxy-Client und stellen dann darüber eine Verbindung zu einer Datenbank her.

Hinweis

Der Client-Host muss die folgenden Anforderungen erfüllen:

  • Der Client muss Netzwerkzugriff auf das Virtual Private Cloud-Netzwerk (VPC) haben, in dem sich die Instanzen befinden, mit denen Sie eine Verbindung herstellen möchten. Client-Hosts (z. B. Compute Engine-Instanzen) in diesem VPC-Netzwerk (Virtual Private Cloud) haben generell diesen Netzwerkzugriff.

    Client-Hosts in externen Netzwerken (lokale Netzwerke oder andere VPC-Netzwerke) haben diesen Netzwerkzugriff, 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 er ausgehende Verbindungen zu Port 5433 für die IP-Adressen Ihrer AlloyDB-Instanzen und ausgehende Verbindungen zu Port 443 (dem Standard-HTTPS-Port) für alle 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 API verwenden kann. Ändern Sie bei Bedarf den Zugriffsbereich so, dass er diesen umfasst.

Auth-Proxyclient herunterladen

Auf welche Maschine Sie den Auth-Proxy-Client herunterladen, hängt davon ab, ob Sie eine Verbindung zu Ihren AlloyDB-Instanzen innerhalb oder außerhalb des VPC-Netzwerks herstellen möchten.

Wenn Sie über den Zugriff auf private Dienste eine Verbindung zu Ihrem Cluster herstellen möchten, laden Sie den Auth-Proxy-Client auf eine Compute Engine-VM-Instanz herunter, die in dem VPC-Netzwerk mit Zugriff auf private Dienste für Ihren Cluster ausgeführt wird.

Wenn Sie eine Verbindung zu Ihrem Cluster von außerhalb der VPC herstellen möchten, installieren Sie diese auf einer Maschine in Abhängigkeit davon, welche Strategie Sie für externe Verbindungen verwenden. Sie können den Auth-Proxy-Client beispielsweise auf einer in Ihrer App lokalen Maschine mit macOS oder Windows installieren und dann einen SOCKS-Server in Ihrem AlloyDB-VPC-Netzwerk verwenden, der als Zwischenstelle für die Verbindung fungiert. Weitere Informationen finden Sie unter Verbindung zu einem Cluster von außerhalb seiner VPC herstellen.

Linux

64-Bit (AMD)

  1. Auth-Proxy-Client herunterladen

    wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.0/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy

  2. Auth-Proxy-Client ausführbar machen:

    chmod +x alloydb-auth-proxy

  3. Fügen Sie den Auth-Proxy-Client zu Ihrem PATH hinzu:

    mkdir -p ~/.local/bin
mv alloydb-auth-proxy ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

    Damit diese Änderungen sitzungsübergreifend erhalten bleiben, fügen Sie export PATH="$HOME/.local/bin:$PATH" in Ihre ~/.bashrc- oder ~/.zshrc-Datei ein.

32-Bit (AMD)

  1. Auth-Proxy-Client herunterladen

    wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.0/alloydb-auth-proxy.linux.386 -O alloydb-auth-proxy

  2. Auth-Proxy-Client ausführbar machen:

    chmod +x alloydb-auth-proxy

  3. Fügen Sie den Auth-Proxy-Client zu Ihrem PATH hinzu:

    mkdir -p ~/.local/bin
mv alloydb-auth-proxy ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

    Damit diese Änderungen sitzungsübergreifend erhalten bleiben, fügen Sie export PATH="$HOME/.local/bin:$PATH" in Ihre ~/.bashrc- oder ~/.zshrc-Datei ein.

64-Bit (ARM)

  1. Auth-Proxy-Client herunterladen

    wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.0/alloydb-auth-proxy.linux.arm64 -O alloydb-auth-proxy

  2. Auth-Proxy-Client ausführbar machen:

    chmod +x alloydb-auth-proxy

  3. Fügen Sie den Auth-Proxy-Client zu Ihrem PATH hinzu:

    mkdir -p ~/.local/bin
mv alloydb-auth-proxy ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

    Damit diese Änderungen sitzungsübergreifend erhalten bleiben, fügen Sie export PATH="$HOME/.local/bin:$PATH" in Ihre ~/.bashrc- oder ~/.zshrc-Datei ein.

32-Bit (ARM)

  1. Auth-Proxy-Client herunterladen

    wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.0/alloydb-auth-proxy.linux.arm -O alloydb-auth-proxy

  2. Auth-Proxy-Client ausführbar machen:

    chmod +x alloydb-auth-proxy

  3. Fügen Sie den Auth-Proxy-Client zu Ihrem PATH hinzu:

    mkdir -p ~/.local/bin
mv alloydb-auth-proxy ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

    Damit diese Änderungen sitzungsübergreifend erhalten bleiben, fügen Sie export PATH="$HOME/.local/bin:$PATH" in Ihre ~/.bashrc- oder ~/.zshrc-Datei ein.

macOS

ARM64

  1. Auth-Proxy-Client herunterladen

    curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.17.0/alloydb-auth-proxy.darwin.arm64

  2. Auth-Proxy-Client ausführbar machen:

    chmod +x alloydb-auth-proxy

  3. Fügen Sie den Auth-Proxy-Client zu Ihrem PATH hinzu:

    mkdir -p ~/.local/bin
mv alloydb-auth-proxy ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

    Damit diese Änderungen sitzungsübergreifend erhalten bleiben, fügen Sie export PATH="$HOME/.local/bin:$PATH" in Ihre ~/.bashrc- oder ~/.zshrc-Datei ein.

AMD64

  1. Auth-Proxy-Client herunterladen

    curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.17.0/alloydb-auth-proxy.darwin.amd64

  2. Auth-Proxy-Client ausführbar machen:

    chmod +x alloydb-auth-proxy

  3. Fügen Sie den Auth-Proxy-Client zu Ihrem PATH hinzu:

    mkdir -p ~/.local/bin
mv alloydb-auth-proxy ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

    Damit diese Änderungen sitzungsübergreifend erhalten bleiben, fügen Sie export PATH="$HOME/.local/bin:$PATH" in Ihre ~/.bashrc- oder ~/.zshrc-Datei ein.

Windows

64-Bit

  1. Klicken Sie mit der rechten Maustaste auf https://storage.googleapis.com/alloydb-auth-proxy/v1.17.0/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.

  2. Fügen Sie den Auth-Proxy-Client zu Ihrem PATH hinzu:

    New-Item -ItemType Directory -Force -Path "$HOME\bin"
Move-Item -Path .\alloydb-auth-proxy.exe -Destination "$HOME\bin"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$userPath;$HOME\bin", "User")

32-Bit

  1. Klicken Sie mit der rechten Maustaste auf https://storage.googleapis.com/alloydb-auth-proxy/v1.17.0/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.

  2. Fügen Sie den Auth-Proxy-Client zu Ihrem PATH hinzu:

    New-Item -ItemType Directory -Force -Path "$HOME\bin"
Move-Item -Path .\alloydb-auth-proxy.exe -Destination "$HOME\bin"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$userPath;$HOME\bin", "User")

Docker-Image

Der Einfachheit halber sind mehrere Container-Images, die den Auth-Proxy-Client enthalten, in der Artifact Registry verfügbar.

Mit dem folgenden Befehl übertragen Sie das neueste Image mit Docker auf Ihre lokale Maschine:

docker pull gcr.io/alloydb-connectors/alloydb-auth-proxy:latest

Anderes Betriebssystem

Für andere Betriebssysteme, 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-Hauptkonten, um Verbindungen zwischen Ihrem Client und einer AlloyDB-Instanz zu autorisieren:

  • Ein angehängtes Dienstkonto. Wenn Ihr Client-Host aufGoogle Cloudausgeführt wird, z. B. auf einer Compute Engine-Instanz, können Sie Verbindungen mit dem Dienstkonto autorisieren, das an diese Ressource angehängt ist.

    Wir empfehlen, für die Autorisierung in Produktionsumgebungen ein Dienstkonto zu verwenden. Ein angehängtes Dienstkonto ist die sicherste Option, da kein heruntergeladener Schlüssel erforderlich ist.

  • Ihr Nutzerkonto Sie können Ihr eigenes IAM-Nutzerkonto verwenden, um Verbindungen zu autorisieren.

    Die Verwendung Ihres 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.

  • Ein vom Nutzer verwaltetes Dienstkonto. Sie können ein IAM-Dienstkonto für Ihre Anwendung erstellen und dann Verbindungen damit autorisieren.

    Verwenden Sie ein nutzerverwaltetes Dienstkonto, wenn Ihr Clienthost außerhalb vonGoogle Cloud ausgeführt wird und kein angehängtes Dienstkonto verwendet werden kann.

Nachdem Sie ausgewählt haben, welches IAM-Hauptkonto verwendet werden soll, müssen Sie dafür sorgen, dass es die erforderlichen IAM-Berechtigungen hat und dass die Anmeldedaten auf Ihrem Clienthost verfügbar sind.

Erforderliche IAM-Berechtigungen

Das zum Autorisieren von Verbindungen verwendete IAM-Hauptkonto muss die Berechtigungen der vordefinierten Rollen roles/alloydb.client (Cloud AlloyDB Client) und roles/serviceusage.serviceUsageConsumer (Service Usage Consumer) 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 (Owner) im Google Cloud -Projekt oder eine Rolle, die diese Berechtigungen gewährt:

    • resourcemanager.projects.get
    • resourcemanager.projects.getIamPolicy
    • resourcemanager.projects.setIamPolicy

    Berechtigungen nach dem Prinzip der geringsten Berechtigung erhalten Sie, wenn der Admin Ihnen die Rolle roles/resourcemanager.projectIamAdmin (Project IAM Admin) zuweist.

IAM-Anmeldedaten auf dem Clienthost verfügbar machen

Der Auth-Proxy-Client verwendet Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC), um IAM-Anmeldedaten auf dem Clienthost zu finden. In den meisten Umgebungen sind diese Anmeldedaten bereits vorhanden, sodass Sie nichts konfigurieren müssen. Der Auth-Proxy-Client sucht in der folgenden Reihenfolge nach den folgenden Anmeldedatenquellen:

  • Ihr Nutzerkonto Wenn Sie lokal entwickeln, authentifizieren Sie sich mit Ihrem eigenen Nutzerkonto, indem Sie den folgenden gcloud CLI-Befehl ausführen:

    gcloud auth application-default login

    Der Auth-Proxy-Client erkennt und verwendet diese Anmeldedaten. Sie müssen keinen Dienstkontoschlüssel herunterladen.

  • Ein angehängtes Dienstkonto. Wenn Ihr Clienthost unterGoogle Cloudausgeführt wird, z. B. auf einer Compute Engine-Instanz, stellt der Metadatenserver der Umgebung Anmeldedaten aus dem angehängten Dienstkonto bereit. Der Auth-Proxy-Client erkennt und verwendet diese Anmeldedaten ohne zusätzliche Konfiguration.

Andere Quellen für Anmeldedaten

Verwenden Sie die folgenden Methoden nur, wenn keine Standardanmeldedaten für Anwendungen verfügbar sind, z. B. wenn Sie den Auth-Proxy-Client außerhalb vonGoogle Cloudausführen oder wenn Sie die Anmeldedaten in der Umgebung überschreiben müssen.

  • Einen Dienstkontoschlüssel. Verwenden Sie einen Dienstkontoschlüssel, wenn Ihr Clienthost außerhalb von Google Cloudausgeführt wird, z. B. in einem lokalen Rechenzentrum oder bei einem anderen Cloud-Anbieter, und Sie die Identitätsföderation von Arbeitslasten nicht verwenden können.

    Erstellen Sie einen Dienstkontoschlüssel im JSON-Format und laden Sie ihn auf Ihren Clienthost herunter. Legen Sie dann entweder die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS auf den Pfad der Schlüsseldatei fest:

    export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"

    Optional können Sie den Pfad mit dem Flag --credentials-file angeben, wenn Sie den Auth-Proxy-Client starten:

    alloydb-auth-proxy --credentials-file /path/to/service-account-key.json INSTANCE_URI

  • Ein OAuth 2.0-Zugriffstoken. Verwenden Sie ein Zugriffstoken, wenn ein anderes System bereits kurzlebige Tokens für Sie ausstellt, z. B. eine Continuous Integration-Pipeline, die ein Token abruft, bevor sie den Auth Proxy-Client startet.

    Wenn Sie bereits ein gültiges OAuth 2.0-Zugriffstoken haben, übergeben Sie es direkt beim Starten des Auth-Proxy-Clients:

    alloydb-auth-proxy --token "ACCESS_TOKEN" INSTANCE_URI

  • Anmeldedaten für die gcloud CLI Verwenden Sie das Flag --gcloud-auth nur, wenn Sie eine vorhandene gcloud auth login-Sitzung wiederverwenden müssen und gcloud auth application-default login nicht ausgeführt werden kann.

    Das Flag --gcloud-auth bewirkt, dass der Auth Proxy-Client das Konto verwendet, mit dem Sie sich mit gcloud auth login authentifiziert haben, anstatt Standardanmeldedaten für Anwendungen zu verwenden. Wir empfehlen dieses Flag nicht. Führen Sie stattdessen gcloud auth application-default login aus.

Verbindungs-URIs für die AlloyDB-Instanzen erfassen

Wenn Sie den Auth-Proxy-Client starten, geben Sie die AlloyDB-Instanzen an, zu denen Sie eine Verbindung herstellen möchten. Verwenden Sie dazu das folgende Verbindungs-URI-Format:

projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

Wenn Sie eine Liste aller Verbindungs-URIs Ihrer Instanzen aufrufen möchten, verwenden Sie den gcloud CLI-Befehl alloydb instances list:

gcloud alloydb instances list \
    --region=REGION_ID \
    --cluster=CLUSTER_ID \
    --project=PROJECT_ID

Ersetzen Sie Folgendes:

  • REGION_ID: die Region, in der sich die Instanzen befinden
  • CLUSTER_ID: Die ID des Clusters, in dem sich die Instanzen befinden.
  • PROJECT_ID: die ID des Projekts, in dem sich der Cluster befindet

Rufen Sie den URI der Instanzverbindung für jede Instanz ab, zu der Sie eine Verbindung herstellen möchten.

Auth-Proxy-Client starten

Geben Sie beim Start des Auth-Proxy-Client Informationen dazu an, mit welchen AlloyDB-Instanzen eine Verbindung hergestellt werden soll, und bei Bedarf Anmeldedaten, die zur Autorisierung dieser Verbindungen verwendet werden sollen.

Wenn der Auth-Proxy-Client gestartet wird, führt er folgende Schritte aus:

  • Autorisiert Verbindungen zu AlloyDB-Instanzen mit den Anmeldedaten und IAM-Berechtigungen des konfigurierten IAM-Hauptkontos. Dabei wird in einer bestimmten Abfolge von Schritten nach Anmeldedaten gesucht.
  • Autorisiert automatisch öffentliche IP-Verbindungen zum Quellnetzwerk, wenn für die Instanz die öffentliche IP-Adresse aktiviert ist.
  • Konfiguriert eine private mTLS 1.3-Verbindung zum Auth-Proxy-Server jeder Instanz.
  • Beginnt mit dem Empfang von Verbindungsanfragen von lokalen Clients.

Standardmäßig überwacht der Auth-Proxy-Client TCP-Verbindungen auf der IP-Adresse 127.0.0.1. Er beginnt mit Port 5432 und erhöht die Portnummer für jede AlloyDB-Instanz nach der ersten um eins. Sie können beim Starten des Auth-Proxy-Clients eine andere Listener-Adresse 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 \ ]
    [ --disable-built-in-telemetry ]

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 Standardport für den lokalen Listener, den der Auth-Proxy-Client für die Instanz verwendet, überschreiben, indem Sie den Abfrageparameter port dem URI 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 vom Nutzer verwalteten 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 Standardports 5432 verwendet werden soll, wenn auf lokale TCP-Verbindungen gewartet wird.

  • Optional: LOCAL_LISTENER_ADDRESS: Die Listener-Adresse, die anstelle der Standardadresse 127.0.0.1 verwendet werden soll, wenn auf lokale TCP-Verbindungen gewartet wird.

Das optionale Flag --auto-iam-authn ermöglicht die automatische Authentifizierung für die Instanz. Dies funktioniert nur für den Datenbanknutzer, der dem IAM-Konto zugeordnet ist, auf dem der Auth-Proxy-Client ausgeführt wird. Weitere Informationen finden Sie unter Automatische Authentifizierung mit dem Auth-Proxy.

Mit dem optionalen Flag --psc kann der Auth-Proxy eine Verbindung zu einer Instanz mit aktiviertem Private Service Connect herstellen. Weitere Informationen zum Einrichten von DNS mit Private Service Connect finden Sie unter DNS-verwaltete Zone und DNS-Eintrag konfigurieren.

Mit dem optionalen Flag --public-ip kann der Auth-Proxy eine Verbindung zu einer Instanz mit aktivierter öffentlicher IP-Adresse über die öffentliche IP-Adresse der Instanz herstellen. Weitere Informationen zu öffentlichen IP-Adressen finden Sie unter Verbindung über öffentliche IP-Adresse herstellen.

Mit dem optionalen Flag --disable-built-in-telemetry wird der interne Messwertmelder, den der Auth-Proxy verwendet, um Informationen zum Verbindungs- und Netzwerkstatus zu melden, deaktiviert. Standardmäßig werden die internen Vorgänge des Auth-Proxys unter dem Systemmesswert-Präfix alloydb.googleapis.com gemeldet. Mithilfe dieser Messwerte kann AlloyDB die Leistung verbessern und Probleme mit der Clientverbindung erkennen. Diese Option ist nützlich beim Ausführen von Apps in Umgebungen, in denen der Export von Messwerten nach außen eingeschränkt ist. Wenn Sie diese Telemetriedaten deaktivieren möchten, verwenden Sie dieses Flag.

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 ist 5432.

  • INSTANCE_URI: Der Instanzverbindungs-URI einer AlloyDB-Instanz, mit der eine Verbindung hergestellt werden soll. Er wird im folgenden Format angegeben:

    projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

    Sie können den Standardport für den lokalen Listener, den der Auth-Proxy-Client für die Instanz verwendet, überschreiben, indem Sie den Abfrageparameter port dem URI hinzufügen:

    "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"

Geben Sie im --publish-Flag 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 aus zugänglich ist.

Wenn Sie Anmeldedaten aus einer lokalen JSON-Datei angeben möchten, fügen Sie beim Ausführen des docker run-Befehls die Flags --volume und --credentials-file ein:

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 vom Nutzer verwalteten Dienstkontos, das für die Verbindungsautorisierung verwendet werden soll.

Beispiele für den Start

Die folgenden Beispiele zeigen verschiedene Möglichkeiten, den Auth-Proxy-Client zu starten. Dabei werden die folgenden Beispiel-Verbindungs-URIs für Instanzen 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 die normale Folge von Autorisierungsschritten durchläuft. Anschließend wartet er auf lokale Verbindungen zur myprimary-Instanz auf 127.0.0.1:5432.

Starten 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 vom Nutzer verwalteten Dienstkontos, der unter myappaccount/key.json gespeichert ist. Anschließend wartet er auf lokale Verbindungen zur myprimary-Instanz auf 127.0.0.1:5432.

Start mit Verbindungen 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 die normale Folge von Autorisierungsschritten durchläuft. Anschließend wartet er auf lokale Verbindungen zur Instanz myprimary auf 127.0.0.1:5432 und zur Instanz myreadpool auf 127.0.0.1:5433.

Start mit Überwachung an 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 die normale Folge von Autorisierungsschritten durchläuft. Anschließend wartet er auf lokale Verbindungen zur Instanz myprimary auf 127.0.0.1:5000 und zur Instanz myreadpool 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

Start mit Überwachung 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 die normale Folge von Autorisierungsschritten durchläuft. Anschließend wartet er auf lokale Verbindungen zur myprimary-Instanz auf 0.0.0.0:5432.

Anwendung über den AlloyDB Auth-Proxy mit einer Datenbank verbinden

Die folgenden Beispiele zeigen, wie Sie eine Anwendung mithilfe des AlloyDB Auth-Proxys mit einer Datenbank verbinden können.

Im psql-Beispiel wird gezeigt, wie Sie ein Befehlszeilentool verbinden.

Die Verbindung zu einer AlloyDB-Instanz mit dem Auth-Proxy funktioniert für mehrere Programmiersprachen identisch zur Verbindung einer Cloud SQL for PostgreSQL-Instanz mit dem Cloud SQL Auth-Proxy. Die Sprachbeispiele hier sind also dieselben wie für Cloud SQL for PostgreSQL.

Diese Beispiele basieren auf einem Standardstart des Auth-Proxy-Clients, sodass er auf lokale TCP-Verbindungen zu 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, mit dem Sie eine Verbindung herstellen möchten, z. B. postgres.

Sie werden aufgefordert, das Passwort des Nutzers DB_USER einzugeben.

Python

import os

import sqlalchemy


# connect_tcp_socket initializes a TCP connection pool
# for an AlloyDB instance.
def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.
    INSTANCE_HOST = os.environ[
        "INSTANCE_HOST"
    ]  # e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
    db_user = os.environ["DB_USER"]  # e.g. 'my-db-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-db-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    db_port = os.environ["DB_PORT"]  # e.g. 5432

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # postgresql+pg8000://<db_user>:<db_pass>@<INSTANCE_HOST>:<db_port>/<db_name>
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,
            password=db_pass,
            host=INSTANCE_HOST,
            port=db_port,
            database=db_name,
        ),
        # ...
    )
    return pool

Java


import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  private static final String DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  private static final String INSTANCE_HOST = System.getenv("INSTANCE_HOST");
  private static final String DB_PORT = System.getenv("DB_PORT");


  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

    // The following URL is equivalent to setting the config options below:
    // jdbc:postgresql://<INSTANCE_HOST>:<DB_PORT>/<DB_NAME>?user=<DB_USER>&password=<DB_PASS>l

    // Configure which instance and what database user to connect with.
    config.setJdbcUrl(String.format("jdbc:postgresql://%s:%s/%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "postgres"
    config.setPassword(DB_PASS); // e.g. "my-password"



    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

const Knex = require('knex');
const fs = require('fs');

// createTcpPool initializes a TCP connection pool for an AlloyDB cluster.
const createTcpPool = async config => {
  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  const dbConfig = {
    client: 'pg',
    connection: {
      host: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
      port: process.env.DB_PORT, // e.g. '5432'
      user: process.env.DB_USER, // e.g. 'my-user'
      password: process.env.DB_PASS, // e.g. 'my-user-password'
      database: process.env.DB_NAME, // e.g. 'my-database'
    },
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return Knex(dbConfig);
};

Go

Wenn Sie dieses Snippet im Kontext einer Webanwendung sehen möchten, rufen Sie die README-Datei auf GitHub auf.

package alloydb

import (
	"database/sql"
	"fmt"
	"log"
	"os"

	// Note: If connecting using the App Engine Flex Go runtime, use
	// "github.com/jackc/pgx/stdlib" instead, since v4 requires
	// Go modules which are not supported by App Engine Flex.
	_ "github.com/jackc/pgx/v5/stdlib"
)

// connectTCPSocket initializes a TCP connection pool for an AlloyDB cluster.
func connectTCPSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Warning: %s environment variable not set.", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser    = mustGetenv("DB_USER")       // e.g. 'my-db-user'
		dbPwd     = mustGetenv("DB_PASS")       // e.g. 'my-db-password'
		dbTCPHost = mustGetenv("INSTANCE_HOST") // e.g. '127.0.0.1' or IP Address of Cluster
		dbPort    = mustGetenv("DB_PORT")       // e.g. '5432'
		dbName    = mustGetenv("DB_NAME")       // e.g. 'my-database'
	)

	dbURI := fmt.Sprintf("host=%s user=%s password=%s port=%s database=%s",
		dbTCPHost, dbUser, dbPwd, dbPort, dbName)

	// dbPool is the pool of database connections.
	dbPool, err := sql.Open("pgx", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %v", err)
	}

	// ...

	return dbPool, nil
}

C#

Wenn Sie dieses Snippet im Kontext einer Webanwendung sehen möchten, rufen Sie die README-Datei auf GitHub auf.

using Npgsql;
using System;

namespace CloudSql
{
    public class PostgreSqlTcp
    {
        public static NpgsqlConnectionStringBuilder NewPostgreSqlTCPConnectionString()
        {
            // Equivalent connection string:
            // "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new NpgsqlConnectionStringBuilder()
            {
                // Note: Saving credentials in environment variables is convenient, but not
                // secure - consider a more secure solution such as
                // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
                // keep secrets safe.
                Host = Environment.GetEnvironmentVariable("INSTANCE_HOST"),     // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                Username = Environment.GetEnvironmentVariable("DB_USER"), // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = SslMode.Disable,
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Ruby

Wenn Sie dieses Snippet im Kontext einer Webanwendung sehen möchten, rufen Sie die README-Datei auf GitHub auf.

development:
  adapter: postgresql
  # Configure additional properties here.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  host: <%= ENV.fetch("DB_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT")  { 5432 }%>

PHP

Wenn Sie dieses Snippet im Kontext einer Webanwendung sehen möchten, rufen Sie die README-Datei auf GitHub auf.

// $username = 'your_db_user';
// $password = 'yoursupersecretpassword';
// $dbName = 'your_db_name';
// $dbHost = "127.0.0.1";

// Connect using TCP
$dsn = sprintf('pgsql:dbname=%s;host=%s', $dbName, $dbHost);

// Connect to the database
$conn = new PDO($dsn, $username, $password, $connConfig);