Executar e se conectar ao AlloyDB Omni

Esta página descreve como executar e se conectar ao AlloyDB Omni depois de instalá-lo na sua máquina ou implantá-lo no cluster do Kubernetes.

Antes de começar

Servidor único

A maioria dos comandos nesta página usa a CLI do AlloyDB Omni.

Para instalar essa ferramenta de linha de comando na sua máquina, consulte Instalar a CLI Omni do AlloyDB.

Kubernetes

É necessário instalar o AlloyDB Omni Kubernetes Operator no cluster do Kubernetes para realizar as tarefas descritas nesta página.

As instruções específicas do Kubernetes nesta página pressupõem que você tenha familiaridade básica com a operação do Kubernetes.

Executar o AlloyDB Omni

Os procedimentos usados para executar o AlloyDB Omni dependem se você está executando o AlloyDB Omni em um contêiner em um servidor único ou em um cluster do Kubernetes. Esta seção divide as instruções entre esses estilos de implantação.

Servidor único

A instalação do AlloyDB Omni configura um serviço do sistema chamado alloydb-dataplane, que é configurado para ser iniciado sempre que a máquina é inicializada.

Para controle e monitoramento básico do AlloyDB Omni, use o comando sudo alloydb, conforme demonstrado nas seções a seguir.

Kubernetes

Para controlar e monitorar o AlloyDB Omni, atualize os manifestos do seu cluster do Kubernetes, conforme demonstrado nas seções a seguir.

Iniciar o AlloyDB Omni

Servidor único 

sudo alloydb database-server start

Para realizar uma conexão de teste, consulte Conectar usando o psql contêinerizado.

Kubernetes

Inicie um cluster de banco de dados interrompido definindo isStopped como false na definição do manifesto.

É possível fazer isso na linha de comando usando kubectl:

kubectl patch dbclusters.alloydbomni.dbadmin.goog dbcluster-sample \
-p '{"spec":{"primarySpec":{"isStopped":false}}}' --type=merge

Verificar o status do AlloyDB Omni

Servidor único 

sudo alloydb database-server status

Kubernetes 

kubectl get dbclusters.alloydbomni.dbadmin.goog DB_CLUSTER_NAME

Substitua DB_CLUSTER_NAME pelo nome do cluster de banco de dados.

Parar o AlloyDB Omni

Servidor único 

sudo alloydb database-server stop

Kubernetes

Para interromper um cluster de banco de dados, defina isStopped como true na definição do manifesto.

É possível fazer isso na linha de comando usando kubectl:

kubectl patch dbclusters.alloydbomni.dbadmin.goog dbcluster-sample -p '{"spec":{"primarySpec":{"isStopped":true}}}' --type=merge

Desativar a inicialização

A execução do comando a seguir impede que o AlloyDB Omni seja iniciado automaticamente quando a máquina é inicializada.

Servidor único 

sudo systemctl disable alloydb-dataplane

Kubernetes

Esta tarefa não se aplica ao uso do operador AlloyDB Omni Kubernetes.

Ativar novamente a inicialização

Servidor único 

sudo systemctl enable alloydb-dataplane

Kubernetes

Esta tarefa não se aplica ao uso do operador AlloyDB Omni Kubernetes.

Conectar-se ao AlloyDB Omni em execução em um único servidor

O contêiner AlloyDB Omni inclui a própria cópia de psql, que permite abrir uma sessão de shell SQL interativa com o servidor de banco de dados.

Também é possível se conectar ao AlloyDB Omni fora do contêiner usando o software compatível com PostgreSQL de sua escolha.

Para informações sobre como se conectar a um cluster de banco de dados do AlloyDB Omni em execução em um cluster do Kubernetes, consulte Conectar-se ao AlloyDB Omni em execução no Kubernetes.

Conectar usando o psql contêinerizado

Para se conectar ao servidor de banco de dados do AlloyDB Omni usando a própria cópia contêinerizada de psql, execute o seguinte comando:

Servidor único 

docker exec -it pg-service psql -h localhost -U postgres

Esse comando conecta você ao servidor como a função do usuário postgres e exibe um prompt de comando postgres=#. Agora é possível executar comandos psql e consultas SQL.

Para sair do psql, execute o comando \q.

Conectar usando seus próprios aplicativos

Qualquer aplicativo que funcione com o PostgreSQL também pode funcionar com o AlloyDB Omni, sem a necessidade de modificações.

Para se conectar ao servidor de banco de dados do AlloyDB Omni, use qualquer cliente ou biblioteca de códigos compatível com o PostgreSQL para se conectar à porta 5432, a porta padrão do servidor de banco de dados PostgreSQL da máquina que executa o AlloyDB Omni.

Isso funciona porque o contêiner do AlloyDB Omni expõe a própria porta 5432 à mesma porta da máquina em que ele é executado.

Depois de se conectar ao servidor de banco de dados, você pode definir, consultar e modificar seus bancos de dados usando consultas DML e SQL com protocolos de comunicação padrão do PostgreSQL.

Como o AlloyDB Omni é executado no seu ambiente, é possível controlar como você se conecta a ele. Isso inclui permitir ou restringir o acesso de rede a esse serviço de acordo com as necessidades do seu aplicativo, assim como você faria com um servidor PostgreSQL comum.

Conectar ao AlloyDB Omni em execução no Kubernetes

O operador AlloyDB Omni Kubernetes permite conexões ao cluster de banco de dados no mesmo cluster do Kubernetes, usando opcionalmente certificados para autenticação.

Conectar usando o psql pré-instalado

É possível fazer uma conexão de teste usando um cliente psql já instalado no pod que executa o banco de dados.

Para fazer isso, execute os seguintes comandos:

export DBPOD=`kubectl get pod --selector=alloydbomni.internal.dbadmin.goog/dbcluster=DB_CLUSTER_NAME,alloydbomni.internal.dbadmin.goog/task-type=database -o jsonpath='{.items[0].metadata.name}'`
kubectl exec -ti $DBPOD -c database -- /bin/psql -h localhost -U postgres

Substitua DB_CLUSTER_NAME pelo nome do cluster do banco de dados. É o mesmo nome do cluster de banco de dados que você declarou ao criar o cluster.

Depois de inserir o comando, o servidor de banco de dados vai solicitar uma senha. Digite a senha com a versão codificada em base64 que você forneceu como um segredo do Kubernetes ao criar o cluster de banco de dados. Por exemplo, se você criou o cluster de banco de dados com um secret de Q2hhbmdlTWUxMjM=, a senha de login a ser usada aqui é ChangeMe123.

O operador AlloyDB Omni conecta você ao servidor como a função do usuário postgres e exibe um prompt de comando postgres=#. Agora é possível executar comandos psql e consultas SQL.

Para sair do psql, execute o comando \q.

Conectar-se de um pod separado no mesmo cluster

O pod que executa o cluster de banco de dados do AlloyDB Omni permite conexões no mesmo cluster do Kubernetes, por padrão. Como prática recomendada, recomendamos proteger todas as conexões ao cluster de banco de dados usando TLS.

Para fornecer seu próprio certificado TLS do servidor, especifique um segredo de certificado ao configurar o cluster de banco de dados. Se você não especificar um segredo de certificado, o operador AlloyDB Omni Kubernetes vai criar um segredo de certificado TLS com base em um certificado assinado por uma autoridade de certificação autoassinada. Em ambos os casos, é possível exigir que o pod de cliente do banco de dados exija a validação do certificado em cada conexão, garantindo a segurança do TLS.

Para estabelecer conexões seguras de banco de dados usando o TLS, realize as seguintes ações:

  • No manifesto que define o pod que faz as conexões do cliente, especifique um certificado TLS secreto. Pode ser um destes:

    • Um secret de certificado TLS que você já criou no cluster do Kubernetes. Para mais informações sobre como trabalhar com segredos de certificado TLS no Kubernetes, consulte Segredos TLS.

    • O secret de certificado padrão que o AlloyDB Omni Kubernetes Operator cria para você, chamado DB_CLUSTER_NAME-ca-cert, se você não especificar um secret TLS como parte do manifesto do cluster de banco de dados.

  • Sempre que o pod do cliente se conectar ao cluster do banco de dados, ele precisará definir as seguintes variáveis de ambiente antes de estabelecer a conexão:

    • Defina PGSSLMODE como "verify-ca".

    • Defina PGSSLROOTCERT como o caminho absoluto, no sistema de arquivos do pod do cliente, do arquivo ca.crt relevante.

O exemplo de manifesto a seguir mostra como configurar um pod que instala a imagem oficial do PostgreSQL, que inclui o cliente de linha de comando psql. O exemplo presume que você não especifique nenhuma configuração secreta do TLS no manifesto que define seu cluster de banco de dados. Portanto, o operador do Kubernetes do AlloyDB Omni usa o secret TLS padrão, chamado dbs-al-cert-DB_CLUSTER_NAME.

apiVersion: v1
kind: Pod
metadata:
  name: postgres
spec:
  containers:
  - image: "docker.io/library/postgres:latest"
    command:
      - "sleep"
      - "604800"
    imagePullPolicy: IfNotPresent
    name: db-client
    volumeMounts:
    - name: ca-cert
      mountPath: "/DB_CLUSTER_NAME-ca-cert"
      readOnly: true
  volumes:
  - name: ca-cert
    secret:
      secretName: dbs-al-cert-DB_CLUSTER_NAME
  restartPolicy: Always

Substitua DB_CLUSTER_NAME pelo nome do cluster do banco de dados. É o mesmo nome do cluster de banco de dados que você declarou ao criar o cluster.

Agora você pode usar o pod para se conectar com segurança ao cluster do banco de dados seguindo estas etapas:

  1. Determine o endereço IP interno do cluster do banco de dados:

    kubectl get dbclusters.alloydbomni.dbadmin.goog

    A saída será assim:

    NAME              PRIMARYENDPOINT   PRIMARYPHASE   DBCLUSTERPHASE
DB_CLUSTER_NAME   IP_ADDRESS        Ready          DBClusterReady

    Anote IP_ADDRESS e use na próxima etapa.

  2. Use psql para se conectar ao cluster pelo pod do cliente, definindo as variáveis de ambiente que ativam e exigem a verificação de certificado TLS:

    kubectl exec -it postgres -- bash
PGSSLMODE="verify-ca" PGSSLROOTCERT=/DB_CLUSTER_NAME-ca-cert/ca.crt psql -h IP_ADDRESS -p 5432 -U postgres -d postgres

    Substitua IP_ADDRESS pelo endereço IP interno que você determinou na etapa anterior.

A seguir