PGAdapter starten

Auf dieser Seite wird beschrieben, wie Sie PGAdapter in Spanner starten. Informationen zu PGAdapter finden Sie unter Über PGAdapter. Informationen zum Herunterladen der PGAdapter-Binärdatei finden Sie unter PGAdapter herunterladen.

Sie haben folgende Möglichkeiten, PGAdapter zu starten:

  • Als eigenständigen Prozess
  • In einem Docker-Container
  • In Cloud Run
  • PGAdapter als Sidecar-Proxy verwenden (z. B. in einem Kubernetes-Cluster)
  • In Ihrem Java-Prozess

Hinweise

Bevor Sie PGAdapter starten, müssen Sie sich auf dem Computer, auf dem PGAdapter ausgeführt wird, mit einem Nutzerkonto oder Dienstkonto authentifizieren. Wenn Sie ein Dienstkonto verwenden, müssen Sie den Speicherort der JSON-Schlüsseldatei (Anmeldedatendatei) kennen. Sie können den Anmeldedatenpfad dann entweder mit der PGAdapter-Option -c oder durch Festlegen der Umgebungsvariablen GOOGLE_APPLICATION_CREDENTIALS angeben.

Weitere Informationen finden Sie unter:

Methode zum Ausführen von PGAdapter auswählen

Sie können PGAdapter als eigenständigen Prozess, in einem Docker-Container, in Cloud Run oder als Verarbeitungsprozess mit Ihrer Java-Anwendung starten. Wenn Sie PGAdapter starten, geben Sie das Projekt, die Spanner-Instanz und die Datenbank an, zu denen eine Verbindung hergestellt werden soll. Außerdem geben Sie den Pfad für eine JSON-formatierte Datei mit Anmeldedaten (Schlüsseldatei) an.

Eigenständig

Lade PGAdapter mit dem folgenden Befehl herunter.

    wget https://storage.googleapis.com/pgadapter-jar-releases/pgadapter.tar.gz \
    && tar -xzvf pgadapter.tar.gz

Starten Sie PGAdapter mit dem folgenden Befehl.

    java -jar pgadapter.jar -p PROJECT_NAME -i INSTANCE_NAME -d DATABASE_NAME \
    -c CREDENTIALS_FILE_PATH \
    ADDITIONAL_OPTIONS

Folgende Optionen sind erforderlich:

-p project_name
Name des Projekts, in dem die Spanner-Datenbank ausgeführt wird.
-i instance_name
Name der Spanner-Instanz.
-d database_name
der Name der Datenbank, zu der eine Verbindung hergestellt werden soll.

Folgende Optionen sind optional:

-r databaseRole=database_role
Datenbankrolle, die für die Sitzung verwendet werden soll. Weitere Informationen finden Sie unter Autorisierung mit PGAdapter.
-c credentials_file_path
 Vollständiger Pfad für die Schlüsseldatei, die die Anmeldedaten des Dienstkontos im JSON-Format enthält. Wenn diese Option nicht festgelegt ist, werden Anmeldedaten aus dem Pfad gelesen, der durch die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS angegeben wird.

Informationen zum Erstellen eines Dienstkontos und Herunterladen einer Schlüsseldatei im JSON-Format finden Sie unter Dienstkonto erstellen.

Gewähren Sie dem Dienstkonto ausreichend Anmeldedaten für den Zugriff auf die Datenbank.

Sie können diese Option weglassen, wenn Sie sich zuerst mit dem folgenden Befehl über die Google Cloud CLI authentifizieren:

gcloud auth application-default login

Weitere Informationen finden Sie unter Authentifizierung und Autorisierung einrichten.

-s port
Port, den PGAdapter überwacht. Der Standardwert ist 5432 (der PostgreSQL-Standardport).
-v version_number

PostgreSQL-Versionsnummer, die dem Client während der Verbindung zur Verfügung gestellt werden soll. Der Standardwert ist 14.1.

Einige PostgreSQL-Anwendungen und -Treiber ermöglichen je nach Versionsnummer zusätzliche Funktionen. Spanner unterstützt diese Funktionen möglicherweise nicht. Eine vollständige Liste der unterstützten Clients finden Sie unter Treiber und Clients.

-x

Aktivieren Sie Verbindungen von anderen Hosts als localhost. Nicht verwenden, wenn PGAdapter im eigenständigen Modus gestartet wird. Nur beim Starten in einem Docker-Container verwenden.

Aus Sicherheitsgründen akzeptiert PGAdapter standardmäßig Verbindungen nur vom localhost.

Im folgenden Beispiel wird PGAdapter im eigenständigen Modus auf Port 5432 mit den Standardanmeldedaten für die Anwendung gestartet. 

java -jar pgadapter.jar \
-p my-project \
-i my-instance \
-d my-database \
-s 5432

Docker

Starten Sie PGAdapter mit dem folgenden Befehl.

docker run -d -p HOST-PORT:DOCKER-PORT \
-v CREDENTIALS_FILE_PATH:/acct_credentials.json \
gcr.io/cloud-spanner-pg-adapter/pgadapter:latest \
-p PROJECT_NAME -i INSTANCE_NAME -d DATABASE_NAME  \
-c /acct_credentials.json -x OTHER_PGAdapter_OPTIONS

Zusätzlich zu den PGAdapter-Optionen zum Festlegen von Projekt, Instanz, Datenbank und Anmeldedaten sind folgende Optionen erforderlich:

-p 127.0.0.1:HOST-PORT:DOCKER-PORT

Mit dieser Docker-Option wird der Port DOCKER-PORT im Docker-Container dem Port HOST-PORT außerhalb des Containers zugeordnet. DOCKER-PORT muss der Konfiguration von PGAdapter im Container entsprechen. Die Standardeinstellung ist 5432. HOST-PORT ist der Port, den Docker außerhalb des Containers auf Verbindungsanfragen überwachen soll. Es muss immer ein verfügbarer Port auf localhost sein.

Weitere Informationen finden Sie in der Docker-Dokumentation unter Port veröffentlichen oder freigeben (-p, --expose).

-v CREDENTIALS_FILE_PATH:in_container_mount_point

Diese Docker-Option bindet ein freigegebenes Volume. Sie ordnet den Hostpfad außerhalb des Containers einem Volume (Bereitstellungspunkt) innerhalb des Containers zu. Die Host- und Containerpfade werden durch einen Doppelpunkt (:) getrennt.

Mit dieser Option kann PGAdapter auf die JSON-Anmeldedatendatei außerhalb des Containers zugreifen. Im vorherigen Beispiel verweist die Option -c auf den Bereitstellungspunkt innerhalb des Containers. In diesem Beispiel wird der im Container enthaltene Bereitstellungspunkt /acct_credentials.json genannt. Sie können ihm einen beliebigen Namen geben.

Weitere Informationen finden Sie in der Docker-Dokumentation unter VOLUME (freigegebene Dateisysteme).

-x

Aktivieren Sie Verbindungen von anderen Hosts als localhost. Dies ist erforderlich, da der Port innerhalb des Containers, der dem Hostport zugeordnet ist, PGAdapter nicht als localhost angezeigt wird.

Folgende Optionen sind optional:

-r databaseRole=database_role
Datenbankrolle, die für die Sitzung verwendet werden soll. Weitere Informationen finden Sie unter Autorisierung mit PGAdapter.

Im folgenden Beispiel sind der Docker-Port und der Hostport auf den Standardport 5432 des PostgreSQL-Datenbankdienstes festgelegt.

docker run -d -p 127.0.0.1:5432:5432 \
-v /tmp/credentials.json:/acct_credentials.json \
gcr.io/cloud-spanner-pg-adapter/pgadapter:latest \
-p my_project -i my_instance -d my_database \
-c /acct_credentials.json -x

Cloud Run

Sie können PGAdapter nicht als eigenständigen Dienst in Cloud Run bereitstellen, aber als Sidecar-Proxy.

Aus den folgenden Gründen wird empfohlen, PGAdapter im Sidecar-Muster auszuführen, anstatt ihn als separaten Dienst auszuführen:
  • Verhindert einen Single Point of Failure. Der Zugriff jeder Anwendung auf Ihre Datenbank ist unabhängig von den anderen, was die Ausfallsicherheit erhöht.
  • Die Anzahl der PGAdapter-Instanzen wird automatisch linear mit der Anzahl der Anwendungsinstanzen skaliert.

Das GitHub-Repository von PGAdapter enthält mehrere funktionierende Beispielanwendungen, die Cloud Run und PGAdapter als Sidecar-Proxy verwenden, und zwar für verschiedene Programmiersprachen.

In der folgenden Konfigurationsdatei wird gezeigt, wie PGAdapter als Sidecar-Proxy zu Cloud Run hinzugefügt wird:

  apiVersion: serving.knative.dev/v1
  kind: Service
  metadata:
  annotations:
    # This example uses an in-memory volume for Unix domain sockets.
    # This is a Cloud Run beta feature.
    run.googleapis.com/launch-stage: BETA
  name: pgadapter-sidecar-example
  spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/execution-environment: gen1
        # This registers 'pgadapter' as a dependency of 'app' and ensures that pgadapter starts
        # before the app container.
        run.googleapis.com/container-dependencies: '{"app":["pgadapter"]}'
    spec:
      # Create an in-memory volume that can be used for Unix domain sockets.
      volumes:
        - name: sockets-dir
          emptyDir:
            # This directory contains the virtual socket files that are used to
            # communicate between your application and PGAdapter.
            sizeLimit: 50Mi
            medium: Memory
      containers:
        # This is the main application container.
        - name: app
          # Example: europe-north1-docker.pkg.dev/my-test-project/cloud-run-source-deploy/pgadapter-sidecar-example
          image: MY-REGION.pkg.dev/MY-PROJECT/cloud-run-source-deploy/pgadapter-sidecar-example
          # The PGADAPTER_HOST variable is set to point to /sockets, which is the shared in-memory
          # volume that is used for Unix domain sockets.
          env:
            - name: SPANNER_PROJECT
              value: my-project
            - name: SPANNER_INSTANCE
              value: my-instance
            - name: SPANNER_DATABASE
              value: my-database
            - name: PGADAPTER_HOST
              value: /sockets
            - name: PGADAPTER_PORT
              value: "5432"
          ports:
            - containerPort: 8080
          volumeMounts:
            - mountPath: /sockets
              name: sockets-dir
        # This is the PGAdapter sidecar container.
        - name: pgadapter
          image: gcr.io/cloud-spanner-pg-adapter/pgadapter
          volumeMounts:
            - mountPath: /sockets
              name: sockets-dir
          args:
            - -dir /sockets
            - -x
          # Add a startup probe that checks that PGAdapter is listening on port 5432.
          startupProbe:
            initialDelaySeconds: 10
            timeoutSeconds: 10
            periodSeconds: 10
            failureThreshold: 3
            tcpSocket:
              port: 5432

Sidecar-Proxy

Sie können PGAdapter beispielsweise als Sidecar-Proxy in einem Kubernetes-Cluster verwenden. Kubernetes-Sidecar-Container werden parallel zum Hauptcontainer im Pod ausgeführt.

Aus den folgenden Gründen wird empfohlen, PGAdapter im Sidecar-Muster auszuführen, anstatt ihn als separaten Dienst auszuführen:

  • Verhindert einen Single Point of Failure. Der Zugriff jeder Anwendung auf Ihre Datenbank ist unabhängig von den anderen, was die Ausfallsicherheit erhöht.
  • Da der PGAdapter Ressourcen linear zur Nutzung verbraucht, können Sie mit diesem Muster Ressourcen genauer bestimmen und entsprechend der Skalierung Ihrer Anwendungen anfordern.

In der folgenden Konfigurationsdatei wird gezeigt, wie Sie PGAdapter Ihrem Kubernetes-Cluster als Sidecar-Proxy hinzufügen:

containers:
- name: pgadapter
image: gcr.io/cloud-spanner-pg-adapter/pgadapter
ports:
  - containerPort: 5432
args:
  - "-p my-project"
  - "-i my-instance"
  - "-d my-database"
  - "-x"
resources:
  requests:
    # PGAdapter's memory use scales linearly with the number of active
    # connections. Fewer open connections will use less memory. Adjust
    # this value based on your application's requirements.
    memory: "512Mi"
    # PGAdapter's CPU use scales linearly with the amount of IO between
    # the database and the application. Adjust this value based on your
    # application's requirements.
    cpu: "1"

Das GitHub-Repository von PGAdapter enthält eine detaillierte Anleitung und eine Beispielanwendung. Dieses Beispiel enthält eine Anleitung zur Verwendung der Workload Identity-Föderation für GKE mit PGAdapter.

Java In-Process

Erstellen und starten Sie eine PGAdapter-Instanz mit Ihrem Java-Code. Dies ist die empfohlene Konfiguration für Java-Anwendungen.

Wenn Sie ein Dienstkonto für die Authentifizierung verwenden, muss die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS auf den Pfad der Anmeldedatendatei festgelegt sein.

  1. Fügen Sie Ihrem Projekt google-cloud-spanner-pgadapter als Abhängigkeit hinzu. Weitere Informationen finden Sie unter PGAdapter herunterladen.
  2. Erstellen Sie einen Server mit der Klasse com.google.cloud.spanner.pgadapter.ProxyServer.
    3. /**
* Starts PGAdapter in-process and returns a reference to the server. Use this reference to
* gracefully shut down the server when your application shuts down.
*
* @param project the Google Cloud project that PGAdapter should connect to
* @param instance the Spanner instance that PGAdapter should connect to
* @param credentialsFile the full path of a credentials file that PGAdapter should use, or 
*     null if PGAdapter should use the application default credentials
*/
static Server startPGAdapter(String project, String instance, String credentialsFile) {
OptionsMetadata.Builder builder =
    OptionsMetadata.newBuilder()
        .setProject(project)
        .setInstance(instance)
        // Start PGAdapter on any available port.
        .setPort(0);
if (credentialsFile != null) {
  builder.setCredentialsFile(credentialsFile);
}
ProxyServer server = new ProxyServer(builder.build());
server.startServer();
server.awaitRunning();

return new PGAdapter(server);
}

Das GitHub-Repository von PGAdapter enthält eine vollständige Beispielanwendung.

Nächste Schritte