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 は ローカルホストからのみ接続できます。

次の簡単な例では、デフォルトのアプリケーション認証情報を使用して、ポート 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 以外のホストからの接続を有効にします。これは、ホストポートにマッピングされるコンテナ内部のポートが、PGAdapter に localhost として表れないため必要になります。

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

-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 環境変数が認証情報ファイルのパスに設定されていることを確認します。

  1. 依存関係として google-cloud-spanner-pgadapter をプロジェクトに追加します。詳細については、PGAdapter を取得するをご覧ください。
  2. <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>google-cloud-spanner-pgadapter</artifactId>
      <version>0.35.0</version>
    </dependency>
  3. com.google.cloud.spanner.pgadapter.ProxyServer クラスを使用してサーバーを構築します。
  4. /**
      * 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 リポジトリには、完全なサンプル アプリケーションが含まれています。

次のステップ