Inicie o PGAdapter

Esta página explica como iniciar o PGAdapter no Spanner. Para saber mais acerca do PGAdapter, consulte o artigo Acerca do PGAdapter. Para obter o ficheiro binário PGAdapter, consulte o artigo Obtenha o PGAdapter.

Pode iniciar o PGAdapter das seguintes formas:

  • Como um processo autónomo
  • Num contentor Docker
  • No Cloud Run
  • Usar o PGAdapter como um proxy sidecar (por exemplo, num cluster do Kubernetes)
  • No processo com a sua aplicação Java

Antes de começar

Antes de iniciar o PGAdapter, certifique-se de que fez a autenticação com uma conta de utilizador ou uma conta de serviço na máquina onde o PGAdapter vai ser executado. Se estiver a usar uma conta de serviço, tem de saber a localização do ficheiro de chave JSON (o ficheiro de credenciais). Em seguida, pode especificar o caminho das credenciais com a opção -c do PGAdapter ou definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

Para mais informações, consulte:

Escolha um método para executar o PGAdapter

Pode iniciar o PGAdapter como um processo autónomo, num contentor do Docker, no Cloud Run ou no processo com a sua aplicação Java. Quando inicia o PGAdapter, especifica o projeto, a instância do Spanner e a base de dados aos quais se ligar. Também pode especificar o caminho de um ficheiro de credenciais (ficheiro de chave) no formato JSON.

Autónomo

Transfira o PGAdapter com o seguinte comando.

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

Inicie o PGAdapter com o seguinte comando.

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

As seguintes opções são obrigatórias:

-p project_name
Nome do projeto no qual a base de dados do Spanner está a ser executada.
-i instance_name
Nome da instância do Spanner.
-d database_name
Nome da base de dados à qual estabelecer ligação.

As seguintes opções são opcionais:

-r databaseRole=database_role
Função da base de dados a usar para a sessão. Para mais informações, consulte o artigo Autorização com o PGAdapter.
-c credentials_file_path
Caminho completo do ficheiro de chaves que contém as credenciais da conta de serviço no formato JSON. Se esta opção não estiver definida, as credenciais são lidas a partir do caminho especificado pela variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

Para saber como criar uma conta de serviço e transferir um ficheiro de chave formatado em JSON, consulte o artigo Criar uma conta de serviço.

Certifique-se de que concede à conta de serviço credenciais suficientes para aceder à base de dados.

Pode omitir esta opção se se autenticar primeiro com a CLI do Google Cloud com o seguinte comando:

gcloud auth application-default login

Para mais informações, consulte o artigo Configure a autenticação e a autorização.

-s port
Porta em que o PGAdapter está a ouvir. A predefinição é 5432 (a porta PostgreSQL predefinida).
-v version_number

Número da versão do PostgreSQL a expor ao cliente durante a ligação. O valor predefinido é 14,1

Algumas aplicações e controladores PostgreSQL ativam funcionalidades adicionais consoante este número de versão. O Spanner pode não suportar estas funcionalidades. Consulte Controladores e clientes para ver uma lista completa dos clientes suportados.

-x

Ative as ligações de anfitriões que não sejam o anfitrião local. Não use quando iniciar o PGAdapter no modo autónomo. Use apenas quando iniciar num contentor do Docker.

Por predefinição, como medida de segurança, o PGAdapter aceita ligações apenas do anfitrião local.

O exemplo seguinte inicia o PGAdapter no modo autónomo na porta 5432 com as credenciais da aplicação predefinidas. 

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

Docker

Inicie o PGAdapter com o seguinte 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_NAME -i INSTANCE_NAME -d DATABASE_NAME  \
-c /acct_credentials.json -x OTHER_PGAdapter_OPTIONS

Além das opções do PGAdapter para especificar o projeto, a instância, a base de dados e as credenciais, as seguintes opções são obrigatórias:

-p 127.0.0.1:HOST-PORT:DOCKER-PORT

Esta opção do Docker mapeia a porta DOCKER-PORT no contentor do Docker para a porta HOST-PORT fora do contentor. DOCKER-PORT tem de corresponder à forma como o PGAdapter está configurado no contentor. A predefinição é 5432. HOST-PORT é a porta na qual o Docker deve ouvir fora do contentor para pedidos de ligação. Tem de ser sempre uma porta disponível no anfitrião local.

Para mais informações, consulte Publicar ou expor porta (-p, --expose) na documentação do Docker.

-v CREDENTIALS_FILE_PATH:in_container_mount_point

Esta opção do Docker associa um volume partilhado. Mapeia o caminho do anfitrião fora do contentor para um volume (ponto de montagem) dentro do contentor. Os caminhos do anfitrião e do contentor estão separados por dois pontos (:).

Esta opção permite que o PGAdapter aceda ao ficheiro de credenciais JSON que está fora do contentor. No exemplo anterior, a opção -c faz referência ao ponto de montagem no contentor. Este exemplo atribui o nome ao ponto de montagem no contentor /acct_credentials.json. Pode atribuir-lhe o nome que quiser.

Para mais informações, consulte VOLUME (sistemas de ficheiros partilhados) na documentação do Docker.

-x

Ative as ligações de anfitriões que não sejam o anfitrião local. Isto é necessário porque a porta no contentor mapeada para a porta do anfitrião não aparece no PGAdapter como localhost.

As seguintes opções são opcionais:

-r databaseRole=database_role
Função da base de dados a usar para a sessão. Para mais informações, consulte o artigo Autorização com o PGAdapter.

No exemplo seguinte, a porta do Docker e a porta do anfitrião estão ambas definidas para a porta predefinida do serviço de base de dados 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

Não pode implementar o PGAdapter como um serviço autónomo no Cloud Run, mas pode implementá-lo como um proxy sidecar.

Recomendamos a execução do PGAdapter num padrão sidecar em vez de o executar como um serviço separado pelos seguintes motivos:
  • Evita um ponto único de falha. O acesso de cada aplicação à sua base de dados é independente das outras, o que as torna mais resilientes.
  • O número de instâncias do PGAdapter é dimensionado automaticamente de forma linear com o número de instâncias da aplicação.

O repositório do GitHub do PGAdapter contém várias aplicações de exemplo funcionais que usam o Cloud Run e o PGAdapter como um proxy sidecar para várias linguagens de programação.

O ficheiro de configuração seguinte mostra como adicionar o PGAdapter como um proxy sidecar ao 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 complementar

Pode usar o PGAdapter como um proxy sidecar, por exemplo, num cluster do Kubernetes. Os contentores secundários do Kubernetes são executados em paralelo com o contentor principal no pod.

Recomendamos a execução do PGAdapter num padrão sidecar em vez de o executar como um serviço separado pelos seguintes motivos:

  • Evita um ponto único de falha. O acesso de cada aplicação à sua base de dados é independente das outras, o que as torna mais resilientes.
  • Uma vez que o PGAdapter consome recursos numa relação linear com a utilização, este padrão permite-lhe definir e pedir recursos com maior precisão para corresponder às suas aplicações à medida que são dimensionadas.

O ficheiro de configuração seguinte mostra como adicionar o PGAdapter como um proxy sidecar ao seu cluster do 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"

O repositório do GitHub do PGAdapter contém um guia passo a passo e uma aplicação de exemplo. Este exemplo inclui instruções para usar a Workload Identity Federation para o GKE com o PGAdapter.

Java In-process

Crie e inicie uma instância do PGAdapter com o seu código Java. Esta é a configuração recomendada para aplicações Java.

Se estiver a usar uma conta de serviço para autenticação, certifique-se de que a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS está definida para o caminho do ficheiro de credenciais.

  1. Adicione google-cloud-spanner-pgadapter como uma dependência ao seu projeto. Para obter detalhes, consulte o artigo Obtenha o PGAdapter.
  2. Crie um servidor através da 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);
}

O repositório do GitHub do PGAdapter contém uma aplicação de exemplo completa.

Orientações de atribuição de recursos para o proxy complementar PGAdapter

As diretrizes seguintes podem ajudar a configurar os recursos de CPU e memória para o proxy sidecar do PGAdapter. Os valores ideais variam consoante a sua carga de trabalho específica.

Memória

Uma vez que o PGAdapter não armazena em cache muitos dados, requer memória para converter os resultados das consultas do formato gRPC do Spanner para o formato do protocolo de rede do PostgreSQL. Isto é especialmente relevante para cargas de trabalho com grandes colunas binárias, porque o Spanner e o PostgreSQL processam estes tipos de dados de forma diferente.

Para determinar a quantidade de memória a atribuir, use a seguinte fórmula para a atribuição de memória, em que <var>number of concurrent connections</var> é o número de ligações simultâneas processadas pela sua aplicação:

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

Por exemplo, se a sua aplicação processar 200 ligações simultâneas, atribua aproximadamente 784 MB de memória:

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

Comece com esta atribuição de memória de base. Monitorize a respetiva utilização sob uma carga realista para ajustar o valor às suas necessidades específicas.

CPU

O PGAdapter não consome muitos recursos da CPU. Isto deve-se ao facto de a sua função principal ser a de atuar como um proxy de passagem. No entanto, a utilização da CPU aumenta com a quantidade de dados enviados e recebidos.

Considere os seguintes fatores ao atribuir CPU:

  • Carga de trabalho: as aplicações que executam consultas que devolvem grandes quantidades de dados requerem mais capacidade de processamento da CPU por ligação do que as que devolvem apenas algumas linhas e colunas.
  • Padrão de acesso à aplicação: se a sua aplicação aceder ao Spanner de forma síncrona, fica inativa enquanto aguarda dados do proxy. Neste caso, é menos provável que a aplicação e o proxy compitam por recursos da CPU.

Comece com uma atribuição de CPU base. Monitorize a respetiva utilização sob uma carga realista para ajustar o valor às suas necessidades específicas.

O que se segue?