Verbindung über den AlloyDB Auth-Proxy herstellen

Auf dieser Seite wird beschrieben, 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 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 Datenbanken her:

1. Einrichtung:
   1. Laden Sie den Auth-Proxyclient auf Ihren Clienthost herunter.
   2. Wählen Sie das IAM-Hauptkonto (Identity and Access Management) aus, das für die Autorisierung verwendet werden soll. Achten Sie darauf, dass es die erforderlichen Berechtigungen hat und seine Anmeldedaten auf Ihrem Clienthost verfügbar sind.
   3. Verbindungs-URIs für die AlloyDB-Instanzen, zu denen Sie eine Verbindung herstellen möchten, abrufen.
2. Starten Sie den Auth-Proxyclient auf Ihrem Clienthost.
3. Anwendung mit einer Datenbank verbinden, indem Sie eine lokale Verbindung zum Auth-Proxy-Client herstellen.

Auth-Proxyclient herunterladen

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

Wenn Sie über den Zugriff auf private Dienste eine Verbindung zu Ihrem Cluster 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 der Computer, auf dem Sie ihn installieren, davon ab, welche externe Verbindungsstrategie Sie verwenden. Sie können den Auth-Proxy-Client beispielsweise auf einem macOS- oder Windows-Computer installieren, der sich lokal in Ihrer Anwendung befindet, und dann einen SOCKS-Server verwenden, der in Ihrem AlloyDB-VPC-Netzwerk als Verbindungszwischenstelle ausgeführt wird. Weitere Informationen finden Sie unter Verbindung zu einem Cluster von außerhalb seiner VPC herstellen.

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

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, für die Autorisierung in Produktionsumgebungen ein Dienstkonto zu verwenden.

• 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.

• Das standardmäßige Compute Engine-Dienstkonto. Wenn der Client-Host eine Compute Engine-Instanz ist, können Sie das Compute Engine-Standarddienstkonto 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 die Anmeldedaten auf Ihrem Clienthost verfügbar sind.

Erforderliche IAM-Berechtigungen

Das IAM-Hauptkonto, das Sie zum Autorisieren von Verbindungen verwenden, muss die Berechtigungen haben, die von den vordefinierten Rollen roles/alloydb.client (Cloud AlloyDB Client) und roles/serviceusage.serviceUsageConsumer (Service Usage Consumer) bereitgestellt werden.

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) imGoogle Cloud -Projekt oder eine Rolle, die diese Berechtigungen gewährt:

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

  Bitten Sie Ihren Administrator, Ihnen die Rolle roles/resourcemanager.projectIamAdmin (Project IAM Admin) 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 zum Autorisieren von Verbindungen verwenden:

• Nutzerverwaltetes Dienstkonto

  Wenn Sie IAM-Anmeldedaten für ein vom Nutzer verwaltetes Dienstkonto bereitstellen möchten, erstellen Sie einen Dienstkontoschlüssel im JSON-Format und laden Sie ihn auf Ihren Clienthost herunter. Wenn Sie den Auth Proxy-Client starten, geben Sie den Speicherort der Schlüsseldatei mit dem Flag --credentials-file an.

• Ihr Nutzerkonto

  Wenn Sie IAM-Anmeldedaten für Ihr Nutzerkonto bereitstellen möchten, installieren Sie die Google Cloud CLI auf Ihrem Clienthost und führen Sie dann 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, sofern 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 Compute Engine-Standarddienstkonto bereits auf dem Host vorhanden. Wenn Sie den Auth Proxy-Client starten, werden diese Anmeldedaten automatisch erkannt und verwendet, wenn keine Anmeldedaten für vom Nutzer verwaltete Dienstkonten 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, 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.

Rufen Sie den URI der Instanzverbindung für jede Instanz ab, 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 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-Principals. Dabei wird eine bestimmte Abfolge von Schritten durchlaufen, um nach Anmeldedaten zu suchen.
• Autorisiert automatisch öffentliche IP-Verbindungen zum Quellnetzwerk, wenn für die Instanz die öffentliche IP-Adresse aktiviert ist.
• Konfiguriert eine private TLS 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.

./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 ]

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

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

Beispiele für Start-ups

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 seiner normalen Folge von Autorisierungsschritten folgt. Anschließend beginnt er, auf lokale Verbindungen zur myprimary-Instanz auf 127.0.0.1:5432 zu warten.

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 beginnt er, auf lokale Verbindungen zur myprimary-Instanz auf 127.0.0.1:5432 zu warten.

Startup-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 seiner normalen Folge von Autorisierungsschritten folgt. Anschließend beginnt er, lokale Verbindungen zur myprimary-Instanz auf 127.0.0.1:5432 und zur myreadpool-Instanz auf 127.0.0.1:5433 zu überwachen.

Überwachung an benutzerdefinierten Ports starten

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 seiner normalen Folge von Autorisierungsschritten folgt. Anschließend beginnt er, lokale Verbindungen zur myprimary-Instanz auf 127.0.0.1:5000 und zur myreadpool-Instanz auf 127.0.0.1:5001 zu überwachen.

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

Auf einer benutzerdefinierten IP-Adresse auf Anfragen warten

./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 seiner normalen Folge von Autorisierungsschritten folgt. Anschließend beginnt er, auf lokale Verbindungen zur myprimary-Instanz auf 0.0.0.0:5432 zu warten.

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 AlloyDB Auth-Proxy ist für mehrere Programmiersprachen identisch mit der Verbindung zu 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 127.0.0.1:5432 auf lokale TCP-Verbindungen wartet.

psql -h 127.0.0.1 -p 5432 -U DB_USER

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

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);
  }
}

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);
};

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
}

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;
        }
    }
}

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 }%>

// $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);