PGAdapter を起動する

このページでは、Spanner で PGAdapter を起動する方法について説明します。PGAdapter の詳細については、 PGAdapter についてをご覧ください。PGAdapter バイナリを取得するには、PGAdapter を取得するをご覧ください。

PGAdapter は次の方法で起動できます。

スタンドアロンプロセスとして
Docker コンテナ内で
Cloud Run で
PGAdapter をサイドカープロキシとして使用（Kubernetes クラスタなど）
Java アプリケーションでの処理中

準備

PGAdapter を起動する前に、PGAdapter を実行するマシンのユーザーアカウントまたはサービスアカウントで認証されていることを確認してください。サービスアカウントを使用している場合は、JSON キーファイル（認証情報ファイル）の場所を把握している必要があります。その場合、PGAdapter -c オプションを使用するか、GOOGLE_APPLICATION_CREDENTIALS 環境変数を使用して、認証情報のパスを指定できます。

詳しくは以下をご覧ください。

PGAdapter を実行する方法を選択する

PGAdapter は、Docker コンテナ内、Cloud Run 上で、または Java アプリケーションを使用してプロセス内でスタンドアロンプロセスとして開始できます。PGAdapter を起動するときは、プロジェクト、Spanner インスタンス、接続先のデータベースを指定します。また、JSON 形式の認証情報ファイル（鍵ファイル）のパスも指定できます。

スタンドアロン

次のコマンドを使用して PGAdapter をダウンロードします。

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

次のコマンドを使用して PGAdapter を起動します。

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

次のオプションは必須です。

-p project_name: Spanner データベースが実行されているプロジェクトの名前。
-i instance_name: Spanner インスタンス名。
-d database_name: 接続先のデータベース名。

次のオプションは省略可能です。

-r databaseRole=database_role

セッションで使用するデータベースのロール。詳細については、PGAdapter による承認をご覧ください。

-c credentials_file_path

サービスアカウントの認証情報を含むキーファイルのフルパス（JSON 形式）。このオプションが設定されていない場合、GOOGLE_APPLICATION_CREDENTIALS 環境変数で指定されたパスから認証情報が読み取られます。

サービスアカウントを作成して JSON 形式のキーファイルをダウンロードする方法については、サービスアカウントの作成をご覧ください。

サービスアカウントには、データベースにアクセスするための十分な資格を付与してください。

最初に Google Cloud CLI で認証する場合は、このオプションを省略できます。

gcloud auth application-default login

詳細については、認証と承認の設定をご覧ください。

-s port

PGAdapter がリッスンするポート。デフォルトは 5432（デフォルトの PostgreSQL ポート）です。

-v version_number

接続中にクライアントに公開する PostgreSQL のバージョン番号。デフォルト値は 14.1 です。

一部の PostgreSQL アプリケーションとドライバでは、このバージョン番号に応じて追加機能が有効にされます。こうした機能は、Spanner でサポートされていない場合があります。サポートされているクライアントの一覧については、ドライバとクライアントをご覧ください。

-x

localhost 以外のホストからの接続を有効にします。PGAdapter をスタンドアロンモードで起動する場合は使用しないでください。Docker コンテナ内で起動する場合にのみ使用します。

デフォルトでは、セキュリティ対策として、PGAdapter は localhost からの接続のみを受け入れます。

次の簡単な例では、デフォルトのアプリケーション認証情報を使用して、ポート 5432 でスタンドアロンモードで PGAdapter を起動します。

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

Docker

次のコマンドを使用して PGAdapter を起動します。

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

プロジェクト、インスタンス、データベース、認証情報を指定する PGAdapter オプションに加え、次のオプションが必要です。

-p 127.0.0.1:HOST-PORT:DOCKER-PORT

この Docker オプションは、Docker コンテナ内のポート DOCKER-PORT をコンテナ外のポート HOST-PORT にマッピングします。 DOCKER-PORT は、コンテナ内での PGAdapter の構成方法と一致する必要があります。デフォルトは 5432 です。HOST-PORT は、Docker がコンテナ外部で接続リクエストをリッスンする必要があるポートです。これは常に localhost の使用可能なポートにする必要があります。

詳細については、Docker ドキュメントのポートのパブリッシュまたは公開（-p、--expose）をご覧ください。

-v CREDENTIALS_FILE_PATH:in_container_mount_point

この Docker オプションは、共有ボリュームをバインドマウントします。これにより、コンテナ外のホストパスがコンテナ内のボリューム（マウントポイント）にマッピングされます。ホストとコンテナのパスは、コロン（:）で区切られます。

このオプションを使用すると、PGAdapter はコンテナの外部にある JSON 認証情報ファイルにアクセスできます。上記の例では、-c オプションはコンテナ内のマウントポイントを参照します。この例では、コンテナ内マウントポイント /acct_credentials.json に名前を付けます。任意の名前を付けることができます。

詳細については、Docker ドキュメントの VOLUME（共有ファイルシステム）をご覧ください。

-x

localhost 以外のホストからの接続を有効にします。これは、ホストポートにマッピングされているコンテナ内のポートが localhost として PGAdapter に認識されないためです。

次のオプションは省略可能です。

-r databaseRole=database_role: セッションで使用するデータベースのロール。詳細については、PGAdapter による承認をご覧ください。

次の例では、Docker ポートとホストポートの両方が、PostgreSQL データベースサービスのデフォルトポート 5432 に設定されています。

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

PGAdapter をスタンドアロンサービスとして Cloud Run にデプロイすることはできませんが、サイドカープロキシとしてデプロイすることはできます。

次の理由から、PGAdapter を別のサービスとして実行するのではなく、サイドカーパターンで実行することをおすすめします。

単一障害点を回避します。各アプリケーションのデータベースへのアクセスは他のアプリケーションから独立しているため、復旧しやすくなります。
PGAdapter インスタンスの数は、アプリケーションインスタンスの数に比例して自動的にスケーリングされます。

PGAdapter GitHub リポジトリには、さまざまなプログラミング言語の Cloud Run と PGAdapter をサイドカープロキシとして使用する作業サンプルアプリケーションが含まれています。

次の構成ファイルは、PGAdapter をサイドカープロキシとして Cloud Run に追加する方法を示しています。

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

サイドカープロキシ

PGAdapter は、Kubernetes クラスタなどでサイドカープロキシとして使用できます。Kubernetes サイドカーコンテナは、Pod のメインコンテナと並行して実行されます。

次の理由から、PGAdapter を別のサービスとして実行するのではなく、サイドカーパターンで実行することをおすすめします。

単一障害点を回避します。各アプリケーションのデータベースへのアクセスは他のアプリケーションから独立しているため、復旧しやすくなります。
PGAdapter はリソースを使用量に比例して消費するため、このパターンにより、アプリケーションのスケーリングに合わせて、リソースをより正確にスコープして、リクエストできます。

次の構成ファイルは、PGAdapter をサイドカープロキシとして Kubernetes クラスタに追加する方法を示しています。

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"

PGAdapter GitHub リポジトリには、手順ガイドとサンプルアプリケーションが含まれています。このサンプルには、PGAdapter で Workload Identity を使用する手順が含まれています。

Java プロセス内

Java コードを使用して PGAdapter インスタンスを作成し、開始します。これは Java アプリケーションの推奨設定です。

認証にサービスアカウントを使用している場合は、GOOGLE_APPLICATION_CREDENTIALS 環境変数が認証情報ファイルのパスに設定されていることを確認します。

依存関係として google-cloud-spanner-pgadapter をプロジェクトに追加します。詳細については、PGAdapter を取得するをご覧ください。

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-spanner-pgadapter</artifactId>
  <version>0.33.0</version>
</dependency>

com.google.cloud.spanner.pgadapter.ProxyServer クラスを使用してサーバーを構築します。

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

PGAdapter GitHub リポジトリには、完全なサンプルアプリケーションが含まれています。

PGAdapter を起動する

準備

PGAdapter を実行する方法を選択する

スタンドアロン

次のオプションは必須です。

次のオプションは省略可能です。

Docker

Cloud Run

サイドカー プロキシ

Java プロセス内

次のステップ

サイドカープロキシ