Cette page a été traduite par l'API Cloud Translation.

Démarrer PGAdapter

Cette page explique comment démarrer PGAdapter dans Spanner. Pour en savoir plus sur PGAdapter, consultez À propos de PGAdapter. Pour obtenir le binaire PGAdapter, consultez 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 comme 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 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écifier le chemin d'accès aux identifiants avec l'option -c de PGAdapter ou en définissant la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS.

Pour en savoir plus, consultez les pages suivantes :

Choisir une méthode pour exécuter 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 à laquelle 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

Démarrez PGAdapter avec 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 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 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 avec 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. Il est possible que Spanner ne soit pas compatible avec ces fonctionnalités. Pour obtenir la liste complète des clients compatibles, consultez Pilotes et clients.

-x

Active les connexions à partir d'hôtes autres que localhost. N'utilisez pas cette option 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 suivant permet de démarrer 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

Démarrez PGAdapter avec 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 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 side-car plutôt que comme un service distinct pour les raisons suivantes :

Cela permet d'éviter 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 avec le nombre d'instances d'application.

Le dépôt GitHub PGAdapter contient plusieurs exemples d'applications fonctionnelles utilisant Cloud Run et PGAdapter comme 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.

Nous vous recommandons d'exécuter PGAdapter dans un modèle side-car plutôt que comme un service distinct, pour les raisons suivantes :

Cela permet d'éviter 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.
Comme PGAdapter consomme les ressources de façon linéaire, ce modèle vous permet de définir plus précisément la portée et les demandes des ressources pour les adapter à vos applications.

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 pas à pas et un exemple d'application. Cet exemple inclut des instructions pour utiliser la fédération d'identité de charge de travail pour GKE avec PGAdapter.

Java In-process

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 au fichier d'identifiants.

Ajoutez google-cloud-spanner-pgadapter en tant que dépendance à votre projet. Pour en savoir plus, consultez Obtenir PGAdapter.
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.

Conseils sur l'allocation de ressources pour le proxy side-car PGAdapter

Les consignes suivantes peuvent vous aider à configurer les ressources de processeur et de mémoire pour le proxy side-car PGAdapter. Les valeurs optimales varient en fonction de votre charge de travail spécifique.

Mémoire

Comme PGAdapter ne met pas en cache beaucoup de données, il a besoin de mémoire pour convertir les résultats des requêtes du format gRPC Spanner au format du protocole réseau PostgreSQL. Cela est particulièrement pertinent pour les charges de travail comportant de grandes colonnes binaires, car Spanner et PostgreSQL gèrent ces types de données différemment.

Pour déterminer la quantité de mémoire à allouer, utilisez la formule suivante, où <var>number of concurrent connections</var> correspond au nombre de connexions simultanées gérées par votre application :

384 Mo + (2 Mo * number of concurrent connections)

Par exemple, si votre application gère 200 connexions simultanées, allouez environ 784 Mo de mémoire :

384 Mo + (2 Mo * 200) = 784 Mo

Commencez par cette allocation de mémoire de référence. Surveillez son utilisation sous une charge réaliste pour affiner la valeur en fonction de vos besoins spécifiques.

Processeur

PGAdapter n'est pas gourmand en ressources processeur. En effet, son rôle principal est d'agir en tant que proxy de transfert. Toutefois, l'utilisation du processeur augmente avec la quantité de données envoyées et reçues.

Tenez compte des facteurs suivants lorsque vous allouez des processeurs :

Charge de travail : les applications qui exécutent des requêtes renvoyant de grandes quantités de données nécessitent plus de puissance de calcul par connexion que celles qui ne renvoient que quelques lignes et colonnes.
Schéma d'accès aux applications : si votre application accède à Spanner de manière synchrone, elle est inactive en attendant les données du proxy. Dans ce cas, l'application et le proxy sont moins susceptibles d'entrer en concurrence pour les ressources de processeur.

Commencez par une allocation de processeur de référence. Surveillez son utilisation sous une charge réaliste pour affiner la valeur en fonction de vos besoins spécifiques.

Démarrer PGAdapter Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.