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.

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.

Iniciar o AlloyDB Omni

Único servidor

Para iniciar um contêiner do AlloyDB Omni interrompido, execute o comando docker container start ou o comando podman container start:

Docker 

docker container start CONTAINER_NAME

Substitua CONTAINER_NAME pelo nome atribuído ao contêiner AlloyDB Omni quando ele foi instalado.

Podman 

podman container start CONTAINER_NAME

Substitua CONTAINER_NAME pelo nome atribuído ao contêiner AlloyDB Omni quando ele foi instalado.

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 DB_CLUSTER_NAME \
-p '{"spec":{"primarySpec":{"isStopped":false}}}' --type=merge

Substitua DB_CLUSTER_NAME pelo nome do cluster de banco de dados, por exemplo, my-db-cluster.

Verificar o status do AlloyDB Omni

Servidor único

Para verificar o status de todos os contêineres em execução, execute o comando docker container ls ou o comando podman container ls:

Docker 

docker container ls

Podman 

podman container ls

Se o contêiner do AlloyDB Omni estiver em execução, o nome dele vai aparecer na coluna NAMES da tabela de saída. A linha correspondente resume o estado do contêiner.

Se o nome do contêiner não aparecer na coluna NAMES, o AlloyDB Omni não estará em execução.

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

Para interromper um contêiner do AlloyDB Omni, execute o comando docker container stop ou o comando podman container stop:

Docker 

 docker container stop CONTAINER_NAME

Substitua CONTAINER_NAME pelo nome que você atribuiu ao contêiner AlloyDB Omni quando o instalou.

Podman 

 podman container stop CONTAINER_NAME

Substitua CONTAINER_NAME pelo nome que você atribuiu ao contêiner AlloyDB Omni quando o instalou.

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 DB_CLUSTER_NAME -p '{"spec":{"primarySpec":{"isStopped":true}}}' --type=merge

Substitua DB_CLUSTER_NAME pelo nome do cluster de banco de dados, por exemplo, my-db-cluster.

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:

Docker 

  docker exec -it CONTAINER_NAME psql -U postgres

Substitua CONTAINER_NAME pelo nome atribuído ao contêiner AlloyDB Omni quando ele foi instalado.

Podman 

  podman exec -it CONTAINER_NAME psql -U postgres

Substitua CONTAINER_NAME pelo nome atribuído ao contêiner AlloyDB Omni quando ele foi instalado.

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, exponha a rede do contêiner do AlloyDB Omni para a máquina host adicionando --network=host ou -p 5432:5432 ao comando docker run ou podman run ao iniciar o AlloyDB Omni.

Para selecionar um número de porta personalizado, use -p [HOST_PORT]:5432 ao iniciar o AlloyDB Omni. Em seguida, use qualquer cliente ou biblioteca de código compatível com PostgreSQL para se conectar à porta 5432 ou ao número de porta personalizado especificado.

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 -- 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