Démarrer PGAdapter

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

Vous pouvez démarrer PGAdapter de différentes manières:

  • 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 cluster)
  • Dans le processus 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 s'exécutera. 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écifiez le chemin d'accès des identifiants avec l'-c de PGAdapter. ou définissez la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS.

Pour en savoir plus, consultez les pages suivantes :

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 lancez PGAdapter, indiquez le projet, l'instance Spanner et à la base de données auxquels se connecter. Vous pouvez également spécifier le chemin d'accès pour un chemin d'accès fichier d'identifiants (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 s'exécute.
-i instance_name
Nom d'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 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 la section 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 avec la Google Cloud CLI en exécutant la commande suivante:

gcloud auth application-default login

Pour plus d'informations, voir Configurez 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 peuvent ne pas être compatibles avec ces fonctionnalités. Voir <ph type="x-smartling-placeholder"></ph> Pilotes et clients pour obtenir la liste complète des clients pris en charge.

-x

Active les connexions à partir d'hôtes autres que localhost. Ne pas utiliser au démarrage de 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. Sa 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.

Nous vous recommandons d'exécuter PGAdapter dans un modèle de sidecar plutôt que de l'exécuter en tant que service distinct pour les raisons suivantes :
  • Évite les points de défaillance uniques. L'accès de chaque application à votre base de données est indépendant des autres, ce qui rend l'ensemble plus résilient.
  • Le nombre d'instances PGAdapter évolue automatiquement de façon linéaire avec le nombre d'instances de l'application.

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

Le fichier de configuration suivant montre comment ajouter PGAdapter en tant que proxy sidecar à 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, par exemple, un cluster Kubernetes. Les conteneurs side-car Kubernetes s'exécutent en parallèle avec le conteneur principal du pod.

Nous vous recommandons 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:

  • Évite les points de défaillance uniques. L'accès de chaque application à votre base de données est indépendant des autres, ce qui rend l'ensemble plus résilient.
  • Comme PGAdapter consomme des ressources en relation linéaire avec l'utilisation, ce modèle vous permet de définir plus précisément la portée et la demande des ressources 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 d'utilisation de la fédération d'identité de charge de travail pour GKE avec PGAdapter.

Java en cours

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éfini sur le chemin 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.39.0</version>
</dependency>
  • Créez un serveur à l'aide de la classe 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);
}

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

    Étape suivante