Avvia PGAdapter

Questa pagina spiega come avviare PGAdapter in Spanner. Per scoprire di più su PGAdapter, consulta Informazioni su PGAdapter. Per ottenere il file binario di PGAdapter, consulta Ottenere PGAdapter.

Puoi avviare PGAdapter nei seguenti modi:

• Come processo autonomo
• All'interno di un container Docker
• Su Cloud Run
• Utilizzando PGAdapter come proxy sidecar (ad esempio, in un cluster Kubernetes)
• In-process con l'applicazione Java

Prima di iniziare

Prima di avviare PGAdapter, assicurati di aver eseguito l'autenticazione con un account utente o un account di servizio sulla macchina su cui verrà eseguito PGAdapter. Se utilizzi un account di servizio, devi conoscere la posizione del file della chiave JSON (il file delle credenziali). Puoi quindi specificare il percorso delle credenziali con l'opzione -c di PGAdapter o impostando la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS.

Per ulteriori informazioni, vedi:

• Eseguire l'autenticazione in Spanner
• Autorizzare gcloud CLI

Scegliere un metodo per eseguire PGAdapter

Puoi avviare PGAdapter come processo autonomo, all'interno di un container Docker, su Cloud Run o in-process con l'applicazione Java. Quando avvii PGAdapter, devi specificare il progetto, l'ID istanza Spanner e il database a cui connetterti. Puoi anche specificare il percorso di un file delle credenziali in formato JSON (file delle chiavi).

Autonomo

Scarica PGAdapter con il seguente comando.

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

Avvia PGAdapter con il seguente comando.

    java -jar pgadapter.jar -p PROJECT_ID -i INSTANCE_ID -d DATABASE_ID \
    -c CREDENTIALS_FILE_PATH \
    ADDITIONAL_OPTIONS
    

Le seguenti opzioni sono obbligatorie:

-p project_id

ID del progetto in cui è in esecuzione il database Spanner in.

-i instance_id

ID istanza Spanner.

-d database_ID

ID del database Spanner a cui connetterti.

Le seguenti opzioni sono facoltative:

-r databaseRole=database_role

Ruolo del database da utilizzare per la sessione. Per ulteriori informazioni, consulta Autorizzazione con PGAdapter.

-c credentials_file_path

Percorso completo del file delle chiavi contenente le credenziali del account di servizio in formato JSON. Se questa opzione non è impostata, le credenziali vengono lette dal percorso specificato dalla GOOGLE_APPLICATION_CREDENTIALS variabile di ambiente.

Per scoprire come creare un account di servizio e scaricare un file delle chiavi in formato JSON, consulta Creare un account di servizio.

Assicurati di concedere all'account di servizio credenziali sufficienti per accedere al database.

Puoi omettere questa opzione se prima esegui l'autenticazione con Google Cloud CLI con il seguente comando:

gcloud auth application-default login

Per ulteriori informazioni, consulta Configurare l'autenticazione e l'autorizzazione.

-s port

Porta su cui PGAdapter rimane in ascolto. Il valore predefinito è 5432 (la porta PostgreSQL predefinita).

-v version_number

Numero di versione di PostgreSQL da esporre al client durante la connessione. Il valore predefinito è 14.1.

Alcune applicazioni e alcuni driver PostgreSQL abilitano funzionalità aggiuntive a seconda di questo numero di versione. Spanner potrebbe non supportare queste funzionalità. Per un elenco completo dei client supportati, consulta Driver e client.

-x

Abilita le connessioni da host diversi da localhost. Non utilizzare quando avvii PGAdapter in modalità autonoma. Utilizza solo quando avvii all'interno di un container Docker.

Per impostazione predefinita, come misura di sicurezza, PGAdapter accetta connessioni solo da localhost.

L'esempio seguente avvia PGAdapter in modalità autonoma sulla porta 5432 utilizzando le credenziali predefinite dell'applicazione.

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

Docker

Avvia PGAdapter con il seguente comando.

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_ID -i INSTANCE_ID -d DATABASE_ID  \
-c /acct_credentials.json -x OTHER_PGAdapter_OPTIONS

Oltre alle opzioni di PGAdapter per specificare progetto, istanza, database e credenziali, sono necessarie le seguenti opzioni:

-p 127.0.0.1:HOST-PORT:DOCKER-PORT

Questa opzione Docker mappa la porta DOCKER-PORT all'interno del container Docker alla porta HOST-PORT all'esterno del container. DOCKER-PORT deve corrispondere alla configurazione di PGAdapter all'interno del container. Il valore predefinito è 5432. HOST-PORT è la porta su cui Docker deve rimanere in ascolto all'esterno del container per le richieste di connessione. Deve sempre essere una porta disponibile su localhost.

Per ulteriori informazioni, consulta Pubblicare o esporre la porta (-p, --expose) nella documentazione di Docker.

-v CREDENTIALS_FILE_PATH:in_container_mount_point

Questa opzione Docker monta un volume condiviso. Mappa il percorso host all'esterno del container a un volume (punto di montaggio) all'interno del container. I percorsi host e container sono separati da due punti (:).

Questa opzione consente a PGAdapter di accedere al file delle credenziali JSON che si trova all'esterno del container. Nell'esempio precedente, l'opzione -c fa riferimento al punto di montaggio all'interno del container. Questo esempio assegna al punto di montaggio all'interno del container il nome /acct_credentials.json. Puoi assegnargli il nome che preferisci.

Per ulteriori informazioni, consulta VOLUME (file system condivisi) nella documentazione di Docker.

-x

Abilita le connessioni da host diversi da localhost. Questa opzione è necessaria perché la porta all'interno del container mappata alla porta host non viene visualizzata da PGAdapter come localhost.

Le seguenti opzioni sono facoltative:

-r databaseRole=database_role

Ruolo del database da utilizzare per la sessione. Per ulteriori informazioni, consulta Autorizzazione con PGAdapter.

Nell'esempio seguente, sia la porta Docker sia la porta host sono impostate sulla porta predefinita del servizio di database PostgreSQL, ovvero 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

Non puoi eseguire il deployment di PGAdapter come servizio autonomo su Cloud Run, ma puoi eseguirne il deployment come proxy sidecar.

L'esecuzione di PGAdapter in un pattern sidecar è consigliata rispetto all'esecuzione come servizio separato per i seguenti motivi:

• Impedisce un singolo punto di errore. L'accesso di ogni applicazione al database è indipendente dalle altre, il che le rende più resilienti.
• Il numero di istanze PGAdapter viene scalato automaticamente in modo lineare con il numero di istanze dell'applicazione.

Il repository GitHub di PGAdapter contiene diversi esempi di applicazioni funzionanti che utilizzano Cloud Run e PGAdapter come proxy sidecar per vari linguaggi di programmazione.

Il seguente file di configurazione mostra come aggiungere PGAdapter come proxy sidecar a 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 sidecar

Puoi utilizzare PGAdapter come proxy sidecar, ad esempio, in un cluster Kubernetes. I container sidecar di Kubernetes vengono eseguiti in parallelo con il container principale nel pod.

L'esecuzione di PGAdapter in un pattern sidecar è consigliata rispetto all'esecuzione come servizio separato per i seguenti motivi:

• Impedisce un singolo punto di errore. L'accesso di ogni applicazione al database è indipendente dalle altre, il che le rende più resilienti.
• Poiché PGAdapter consuma risorse in relazione lineare all'utilizzo, questo pattern ti consente di definire e richiedere le risorse in modo più accurato in base alle tue applicazioni man mano che vengono scalate.

Il seguente file di configurazione mostra come aggiungere PGAdapter come proxy sidecar al 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"

Il repository GitHub di PGAdapter contiene una guida passo passo e un'applicazione di esempio. Questo esempio include le istruzioni per l'utilizzo di Workload Identity Federation for GKE con PGAdapter.

Java in-process

Crea e avvia un'istanza PGAdapter con il codice Java. Questa è la configurazione consigliata per le applicazioni Java.

Se utilizzi un account di servizio per l'autenticazione, assicurati che la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sia impostata sul percorso del file delle credenziali.

1. Aggiungi google-cloud-spanner-pgadapter come dipendenza al tuo progetto. Per maggiori dettagli, consulta Ottenere PGAdapter.
2. Crea un server utilizzando 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);
}

Il repository GitHub di PGAdapter contiene un'applicazione di esempio completa.

Indicazioni per l'allocazione delle risorse per il proxy sidecar PGAdapter

Le seguenti linee guida possono aiutarti a configurare le risorse CPU e memoria per il proxy sidecar PGAdapter. I valori ottimali variano a seconda del carico di lavoro specifico.

Memoria

Poiché PGAdapter non memorizza nella cache molti dati, richiede memoria per convertire i risultati delle query dal formato gRPC di Spanner al formato del protocollo wire PostgreSQL. Ciò è particolarmente importante per i carichi di lavoro con colonne binarie di grandi dimensioni, perché Spanner e PostgreSQL gestiscono questi tipi di dati in modo diverso.

Per determinare la quantità di memoria da allocare, utilizza la seguente formula per l'allocazione della memoria, dove <var>number of concurrent connections</var> è il numero di connessioni simultanee gestite dall'applicazione:

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

Ad esempio, se l'applicazione gestisce 200 connessioni simultanee, alloca circa 784 MB di memoria:

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

Inizia con questa allocazione della memoria di base. Monitora il suo utilizzo con un carico realistico per ottimizzare il valore in base alle tue esigenze specifiche.

CPU

PGAdapter non richiede un utilizzo intensivo della CPU. Questo perché il suo ruolo principale è quello di fungere da proxy pass-through. Tuttavia, l'utilizzo della CPU aumenta con la quantità di dati inviati e ricevuti.

Quando allochi la CPU, tieni in considerazione i seguenti fattori:

• Carico di lavoro: le applicazioni che eseguono query che restituiscono grandi quantità di dati richiedono più potenza della CPU per connessione rispetto a quelle che restituiscono solo poche righe e colonne.
• Pattern di accesso all'applicazione: se l'applicazione accede a Spanner in modo sincrono, rimane inattiva mentre attende i dati dal proxy. In questo caso, è meno probabile che l'applicazione e il proxy competano per le risorse CPU.

Inizia con un'allocazione di base della CPU. Monitora il suo utilizzo con un carico realistico per ottimizzare il valore in base alle tue esigenze specifiche.

Passaggi successivi

• Connettere psql a un database PostgreSQL
• Connettere JDBC a un database PostgreSQL
• Connettere pgx a un database PostgreSQL
• Connettere psycopg2 a un database PostgreSQL
• Connettere psycopg3 a un database PostgreSQL
• Connettere node-postgres a un database PostgreSQL
• Visualizzare una panoramica dei driver e degli ORM supportati per Spanner