Démarrer PGAdapter

Cette page explique comment démarrer PGAdapter dans Spanner. Pour en savoir plus sur PGAdapter, consultez la page À propos de PGAdapter. Pour obtenir le binaire PGAdapter, consultez Obtenir PGAdapter.

Pour démarrer PGAdapter, procédez comme suit:

  • En tant que processus autonome
  • Dans un conteneur Docker
  • Sur Cloud Run
  • Utiliser PGAdapter en tant que proxy side-car (par exemple, dans un cluster Kubernetes)
  • En cours de traitement avec votre application Java

Avant de commencer

Avant de démarrer PGAdapter, assurez-vous de vous être authentifié avec un compte utilisateur ou un compte de service sur la machine sur laquelle PGAdapter sera exécuté. Si vous utilisez un compte de service, vous devez connaître l'emplacement du fichier de clé JSON (fichier d'identifiants). Vous pouvez ensuite spécifier le chemin d'accès aux identifiants avec l'option PGAdapter -c ou en définissant la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS.

Pour en savoir plus, consultez cette page :

Choisir une méthode d'exécution de PGAdapter

Vous pouvez démarrer PGAdapter en tant que processus autonome, dans un conteneur Docker, sur Cloud Run ou en cours de traitement avec votre application Java. Lorsque vous démarrez PGAdapter, vous spécifiez le projet, l'instance Spanner et la base de données auxquels vous souhaitez vous connecter. Vous pouvez également spécifier le chemin d'accès à un fichier d'identifiants au format JSON (fichier de clé).

Autonome

Téléchargez PGAdapter à l'aide de la commande suivante.

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

Lancez PGAdapter à l'aide de la commande suivante.

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

Les options suivantes sont requises :

-p project_name
Nom du projet dans lequel la base de données Spanner est exécutée.
-i instance_name
Nom de l'instance Spanner.
-d database_name
Nom de la base de données à laquelle se connecter.

Les options suivantes sont facultatives :

-r databaseRole=database_role
Rôle de base de données à utiliser pour la session. Pour en savoir plus, consultez la section Autorisation avec PGAdapter.
-c credentials_file_path
Chemin d'accès complet au fichier de clés contenant les identifiants du compte de service au format JSON. Si cette option n'est pas définie, les identifiants sont lus à partir du chemin spécifié par la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS.

Pour savoir comment créer un compte de service et télécharger un fichier de clé au format JSON, consultez Créer un compte de service.

Assurez-vous d'accorder au compte de service des identifiants suffisants pour accéder à la base de données.

Vous pouvez omettre cette option si vous vous authentifiez d'abord auprès de la Google Cloud CLI à l'aide de la commande suivante:

gcloud auth application-default login

Pour en savoir plus, consultez Configurer l'authentification et l'autorisation.

-s port
Port sur lequel PGAdapter écoute. Le port par défaut est 5432 (le port PostgreSQL par défaut).
-v version_number

Numéro de version de PostgreSQL à exposer au client pendant la connexion. La valeur par défaut est 14,1

Certains pilotes et applications PostgreSQL permettent des fonctionnalités supplémentaires en fonction de ce numéro de version. Spanner n'est peut-être pas compatible avec ces fonctionnalités. Consultez la section Pilotes et clients pour obtenir la liste complète des clients compatibles.

-x

Active les connexions à partir d'hôtes autres que localhost. Ne l'utilisez pas lorsque vous démarrez PGAdapter en mode autonome. N'utilisez cette option que lors du démarrage dans un conteneur Docker

Par défaut, par mesure de sécurité, PGAdapter n'accepte que les connexions de "localhost".

L'exemple simple suivant démarre PGAdapter en mode autonome sur le port 5432 à l'aide des identifiants d'application par défaut. 

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

Docker

Lancez PGAdapter à l'aide de la commande suivante.

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

Outre les options de PGAdapter nécessaires pour spécifier un projet, une instance, une base de données et des identifiants, les options suivantes sont requises :

-p 127.0.0.1:HOST-PORT:DOCKER-PORT

Cette option Docker mappe le port DOCKER-PORT du conteneur Docker au port HOST-PORT en dehors du conteneur. DOCKER-PORT doit correspondre à la configuration de PGAdapter dans le conteneur. La valeur par défaut est 5432. HOST-PORT est le port sur lequel Docker doit écouter en dehors du conteneur pour les requêtes de connexion. Il doit toujours s'agir d'un port disponible sur localhost.

Pour en savoir plus, consultez la section Publier ou exposer le port (-p, --expose) dans la documentation de Docker.

-v CREDENTIALS_FILE_PATH:in_container_mount_point

Cette option Docker crée un montage lié (bind mount) d'un volume partagé. Elle mappe le chemin d'accès de l'hôte en dehors du conteneur avec un volume (point d'installation) à l'intérieur du conteneur. Les chemins d'accès à l'hôte et au conteneur sont séparés par un signe deux-points (:).

Cette option permet à PGAdapter d'accéder au fichier d'identifiants JSON qui se trouve en dehors du conteneur. Dans l'exemple précédent, l'option -c fait référence au point d'installation intégré au conteneur. Cet exemple nomme le point d'installation intégré au conteneur /acct_credentials.json. Vous pouvez le nommer comme vous le souhaitez.

Pour en savoir plus, consultez la page VOLUME (systèmes de fichiers partagés) dans la documentation de Docker.

-x

Active les connexions à partir d'hôtes autres que localhost. Cela est nécessaire, car le port interne au conteneur mappé au port hôte n'apparaît pas dans PGAdapter en tant que localhost.

Les options suivantes sont facultatives :

-r databaseRole=database_role
Rôle de base de données à utiliser pour la session. Pour en savoir plus, consultez la section Autorisation avec PGAdapter.

Dans l'exemple suivant, le port Docker et le port hôte sont tous deux définis sur le port par défaut du service de base de données PostgreSQL (port 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

Vous ne pouvez pas déployer PGAdapter en tant que service autonome sur Cloud Run, mais vous pouvez le déployer en tant que proxy side-car.

Il est recommandé d'exécuter PGAdapter dans un modèle side-car plutôt que de l'exécuter en tant que service distinct pour les raisons suivantes :
  • Prévention de l'existence d'un point de défaillance unique. L'accès de chaque application à votre base de données est indépendant des autres, ce qui les rend plus résilientes.
  • Le nombre d'instances PGAdapter évolue automatiquement de manière linéaire en fonction du nombre d'instances d'application.

Le dépôt GitHub PGAdapter contient plusieurs exemples d'applications fonctionnelles utilisant Cloud Run et PGAdapter en tant que proxy side-car pour différents langages de programmation.

Le fichier de configuration suivant montre comment ajouter PGAdapter en tant que proxy side-car à 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

Proxy side-car

Vous pouvez utiliser PGAdapter comme proxy side-car dans un cluster Kubernetes, par exemple. Les conteneurs side-car Kubernetes s'exécutent en parallèle du conteneur principal du pod.

Il est recommandé d'exécuter PGAdapter dans un modèle side-car plutôt que de l'exécuter en tant que service distinct pour les raisons suivantes:

  • Prévention de l'existence d'un point de défaillance unique. L'accès de chaque application à votre base de données est indépendant des autres, ce qui les rend plus résilientes.
  • Étant donné que PGAdapter consomme les ressources de façon linéaire par rapport à l'utilisation, ce modèle vous permet de définir plus précisément la portée et la demande des ressources afin qu'elles correspondent à vos applications à mesure qu'elles évoluent.

Le fichier de configuration suivant montre comment ajouter PGAdapter en tant que proxy side-car à votre cluster 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"

Le dépôt GitHub PGAdapter contient un guide par étapes et un exemple d'application. Cet exemple inclut des instructions pour utiliser Workload Identity avec PGAdapter.

Java en cours de traitement

Créez et démarrez une instance PGAdapter avec votre code Java. Il s'agit de la configuration recommandée pour les applications Java.

Si vous utilisez un compte de service pour l'authentification, assurez-vous que la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS est définie sur le chemin d'accès du fichier d'identifiants.

  1. Ajoutez google-cloud-spanner-pgadapter en tant que dépendance à votre projet. Pour en savoir plus, consultez Obtenir PGAdapter. 
    2. <dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-spanner-pgadapter</artifactId>
  <version>0.33.2</version>
</dependency>
  2. Créez un serveur à l'aide de la classe 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);
}

Le dépôt GitHub PGAdapter contient un exemple d'application complet.

Étapes suivantes