Implantar e gerenciar o AlloyDB Omni no Kubernetes (GKE ou cluster próprio)

1. Introdução

Neste codelab, você vai aprender a instalar o operador do AlloyDB Omni para Kubernetes (o orquestrador de contêineres) em um cluster do Autopilot do Google Kubernetes Engine (GKE) ou no seu próprio cluster do Kubernetes, além de gerenciar fluxos de trabalho completos do ciclo de vida do banco de dados e jornadas ideais do usuário (CUJs, na sigla em inglês).

O AlloyDB Omni é uma edição para download do AlloyDB projetada para ser executada em qualquer lugar, desde ambientes locais até o Google Cloud ou a computação de borda. Com o orquestrador de contêineres, o AlloyDB Omni automatiza a alta disponibilidade, os failovers automáticos, a autorrecuperação, a manutenção contínua com inatividade mínima, o pool de conexões, os backups automatizados e a recuperação pontual.

Escolha o caminho do ambiente

É possível concluir este codelab usando um dos dois caminhos a seguir:

  1. Caminho 1: ter uma conta do Google Cloud (Autopilot do GKE): provisione um cluster do Autopilot do GKE totalmente gerenciado usando o Google Cloud Shell ou o console do Google Cloud.
  2. Caminho 2: não tenho uma conta do Google Cloud (traga seu próprio cluster do Kubernetes): use um cluster do Kubernetes (v1.21 ou mais recente) com kubectl e helm configurados na sua estação de trabalho. Não é necessário ter uma conta do Google Cloud ou a CLI gcloud.

Pré-requisitos

  • Conhecimento básico dos conceitos do Kubernetes (kubectl, Helm, definições de recursos personalizados).
  • Para o Caminho 1 (Google Cloud / Autopilot do GKE):
    • Ter um projeto do Google Cloud com o faturamento ativado.
    • Acesso ao Google Cloud Shell ou a uma estação de trabalho configurada com gcloud, kubectl e helm.
  • Para o Caminho 2 (Traga seu próprio cluster do Kubernetes):
    • Um cluster do Kubernetes que executa a versão 1.21 ou mais recente com um StorageClass padrão para provisionamento dinâmico de PersistentVolume.
    • Nós de trabalho que executam o kernel do Linux 4.18+ com o cgroup v2 ativado (x86-64/AMD64) e pelo menos 8 vCPUs e 24 GiB de RAM alocável em todo o cluster.
    • Uma estação de trabalho configurada com kubectl e helm conectada ao cluster.

O que você vai aprender

  • Como provisionar um cluster do GKE Autopilot (Caminho 1) ou validar um cluster do Kubernetes (Caminho 2).
  • Como instalar o cert-manager e o operador do AlloyDB Omni no Kubernetes usando o Helm.
  • Como implantar um AlloyDB Omni de instância única DBCluster.
  • Como escalonar para alta disponibilidade (HA) com standbys síncronos e ativar o recurso de standby somente leitura.
  • Como configurar backups automatizados programados para o armazenamento do repositório local (e, opcionalmente, para o Google Cloud Storage no Caminho 1).
  • Como realizar backups on demand e verificar a restauração de dados para um estado anterior.
  • Como realizar a recuperação pontual (PITR) em um novo cluster de banco de dados clonado.
  • Como implantar o pool de conexões do PgBouncer para escalonamento de conexões de clientes.
  • Como implantar o pgAdmin4 para gerenciar e consultar o banco de dados visualmente.
  • Como executar a manutenção com pouco tempo de inatividade (LDTM, na sigla em inglês) para escalonamento de recursos de CPU e memória.

O que é necessário

  • Caminho 1: Google Cloud Shell com os utilitários gcloud, kubectl e helm pré-instalados.
  • Caminho 2: um terminal com kubectl e helm conectados ao cluster do Kubernetes.
  • Para ver a documentação de referência, consulte o guia oficial de implantação do AlloyDB Omni.

2. Configuração e requisitos

Escolha o Caminho 1 se estiver usando uma conta do Google Cloud para criar um cluster do Autopilot do GKE ou o Caminho 2 se estiver usando seu próprio cluster do Kubernetes sem uma conta do Google Cloud.

Caminho 1: configuração do projeto na nuvem do Google Cloud (Autopilot do GKE)

  1. No Console do Google Cloud, selecione ou crie um projeto do Google Cloud.
  2. Confirme se o faturamento está ativado no projeto. Saiba como verificar o status de faturamento.
  3. Abra o Google Cloud Shell clicando no ícone Ativar o Cloud Shell no canto superior direito do console do Google Cloud ou acessando shell.cloud.google.com. O Cloud Shell provisiona um ambiente de computação carregado com gcloud, kubectl e helm.
  4. Defina o ID do projeto como uma variável de ambiente e configure gcloud:
export PROJECT_ID="<YOUR_PROJECT_ID>"
export REGION="us-central1"
export CLUSTER_NAME="omni-autopilot-cluster"

gcloud config set project ${PROJECT_ID}
gcloud config set compute/region ${REGION}
  1. Ative as APIs do Google Cloud necessárias para o GKE e o Cloud Storage:
gcloud services enable container.googleapis.com \
    storage.googleapis.com \
    cloudresourcemanager.googleapis.com

Caminho 2: configuração de cluster próprio (sem conta do Google Cloud)

Se você não tiver uma conta do Google Cloud e estiver usando seu próprio cluster do Kubernetes, verifique os seguintes pré-requisitos no terminal antes de continuar:

  1. Verifique se kubectl e helm podem acessar o cluster e se os nós estão Ready:
kubectl get nodes
helm version
  1. Verifique se o cluster tem um StorageClass padrão marcado como (default). Os manifestos DBCluster e BackupPlan provisionam dinamicamente PersistentVolumeClaims usando o StorageClass padrão do cluster:
kubectl get storageclass

Se nenhum StorageClass estiver marcado como (default), designe um como padrão antes de continuar:

kubectl patch storageclass <YOUR_STORAGE_CLASS_NAME> \
  -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'
  1. Confirme se os nós de trabalho atendem aos requisitos de hardware e SO do operador:
    • SO e kernel: kernel do Linux 4.18 ou mais recente com o cgroup v2 ativado em nós x86-64/AMD64.
    • Capacidade do cluster: pelo menos 8 vCPUs e 24 GiB de memória alocável nos nós de trabalho para executar as instâncias de banco de dados de alta disponibilidade (escalonadas para 2 vCPUs e 8 GiB cada na Etapa 12), a instância clonada de PITR, o PgBouncer e o pgAdmin4 simultaneamente.
    • Acesso à rede: acesso de saída à Internet para extrair imagens de contêiner de gcr.io/alloydb-omni, quay.io/jetstack e docker.io.

3. Provisionar ou conectar-se ao cluster do Kubernetes

Se você estiver seguindo o Caminho 1 (conta do Google Cloud), o GKE Autopilot oferece um modo do Kubernetes totalmente gerenciado e sem intervenção, em que o Google gerencia a infraestrutura do cluster, o provisionamento de nós e o escalonamento automático. É possível criar o cluster do Autopilot do GKE usando a CLI do Google Cloud ou o console do Google Cloud.

Opção A: criar um cluster do Autopilot do GKE usando a CLI (caminho 1)

Execute o seguinte comando gcloud no Cloud Shell:

gcloud container clusters create-auto ${CLUSTER_NAME} \
    --region=${REGION} \
    --project=${PROJECT_ID}

Opção B: criar um cluster do Autopilot do GKE pelo console (caminho 1)

  1. Abra o Kubernetes Engine no console do Google Cloud.
  2. No painel de navegação à esquerda, clique em Clusters.
  3. Clique em Criar.
  4. Na seção Autopilot do GKE, clique em Configurar.
  5. Especifique o nome do cluster (por exemplo, omni-autopilot-cluster) e selecione a região de sua preferência (us-central1).
  6. Clique em Criar.

Verificar a conectividade do cluster (Caminho 1 e Caminho 2)

Se você criou um cluster do Autopilot do GKE no Caminho 1, configure as credenciais do kubectl:

gcloud container clusters get-credentials ${CLUSTER_NAME} --region=${REGION} --project=${PROJECT_ID}

Para o Caminho 1 e o Caminho 2, verifique a conectividade com o cluster do Kubernetes:

kubectl get nodes

4. Instalar os pré-requisitos do operador e o operador

O operador do AlloyDB Omni para Kubernetes requer o cert-manager para gerenciar os certificados TLS do webhook de admissão.

1. Instalar o cert-manager

Instale o cert-manager usando o gráfico oficial do Helm:

helm install \
  cert-manager oci://quay.io/jetstack/charts/cert-manager \
  --version v1.21.2 \
  --namespace cert-manager \
  --create-namespace \
  --set crds.enabled=true \
  --set global.leaderElection.namespace=cert-manager

Verifique se os pods do cert-manager estão em execução:

kubectl wait --namespace cert-manager \
  --for=condition=ready pod \
  --selector=app.kubernetes.io/instance=cert-manager \
  --timeout=120s

2. Instalar o operador do AlloyDB Omni

Implante o operador do AlloyDB Omni no Kubernetes no namespace alloydb-omni-system usando o Helm:

helm install alloydbomni-operator oci://gcr.io/alloydb-omni/alloydbomni-operator \
  --version 1.8.2 \
  --create-namespace \
  --namespace alloydb-omni-system \
  $(helm install --help | grep -q -- '--rollback-on-failure' && echo '--rollback-on-failure' || echo '--atomic') \
  --timeout 5m

Verifique se os pods do operador estão íntegros e em execução:

kubectl get pods -n alloydb-omni-system

5. Criar um cluster de banco de dados de instância única

Nesta etapa, você vai criar um namespace de aplicativo dedicado e implantar um DBCluster do AlloyDB Omni de instância única.

1. Criar namespace e secret de credenciais de administrador

Crie um namespace omni-demo para cargas de trabalho de banco de dados:

kubectl create namespace omni-demo

Crie um Secret do Kubernetes que armazene a senha do usuário administrador padrão do banco de dados postgres:

kubectl apply -n omni-demo -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: db-pw-adbo
type: Opaque
data:
  adbo: "Q2hhbmdlTWUxMjM=" # Base64 for "ChangeMe123"
EOF

2. Implantar DBCluster de instância única

Crie um manifesto DBCluster de instância única:

kubectl apply -n omni-demo -f - <<EOF
apiVersion: alloydbomni.dbadmin.goog/v1
kind: DBCluster
metadata:
  name: adbo
spec:
  databaseVersion: "18.3.0"
  primarySpec:
    adminUser:
      passwordRef:
        name: db-pw-adbo
    resources:
      cpu: 1
      memory: 4Gi
      disks:
      - name: DataDisk
        size: 10Gi
EOF

3. Verificar se o cluster está pronto

Monitore o status do cluster até que DBCLUSTERPHASE alcance DBClusterReady. O provisionamento inicial pode levar vários minutos: o operador precisa criar o volume permanente e extrair a imagem do banco de dados. No Autopilot do GKE, talvez seja necessário provisionar um novo nó primeiro.

kubectl get dbcluster -n omni-demo -w

Pressione Ctrl+C para sair do modo de observação quando DBCLUSTERPHASE chegar a DBClusterReady.

Exemplo de resposta:

NAME   PRIMARYENDPOINT   PRIMARYPHASE   DBCLUSTERPHASE   HAREADYSTATUS   HAREADYREASON
adbo   10.128.0.45       Ready          DBClusterReady

Anote o endereço IP PRIMARYENDPOINT, que é o ClusterIP do serviço do Kubernetes de leitura e gravação al-adbo-rw-ilb. O AlloyDB Omni detecta a porta padrão do PostgreSQL 5432.

Inspecione os recursos que o operador reconciliou do manifesto DBCluster único: o pod do banco de dados, o PersistentVolumeClaim DataDisk e o serviço al-adbo-rw-ilb:

kubectl get pods,svc,pvc -n omni-demo

6. Fazer upgrade para alta disponibilidade (HA) e ativar o modo de espera somente leitura

O AlloyDB Omni oferece alta disponibilidade (HA) integrada com replicação de streaming, monitoramento de integridade automático, failover automatizado e disponibilização de réplicas de leitura.

1. Ativar a capacidade de alta disponibilidade e réplica de leitura

Atualize a especificação DBCluster para configurar uma instância em espera e ativar o roteamento em espera somente leitura:

kubectl patch dbcluster adbo -n omni-demo --type=merge -p '{
  "spec": {
    "availability": {
      "numberOfStandbys": 1,
      "enableStandbyAsReadReplica": true
    }
  }
}'

2. Verificar a estabilização da alta disponibilidade

Aguarde até que a instância em espera seja provisionada e alcance a replicação de streaming íntegra (HAREADYSTATUS alcança True e HAREADYREASON alcança Ready). Em seguida, pressione Ctrl+C para sair do modo de monitoramento:

kubectl get dbcluster adbo -n omni-demo -w

Verifique a condição de status de HAReady:

kubectl get dbcluster.alloydbomni.dbadmin.goog adbo -n omni-demo -o jsonpath='{.status.conditions[?(@.type == "HAReady")]}'

Verifique se os endpoints de leitura e gravação e somente leitura foram publicados:

kubectl describe dbcluster adbo -n omni-demo | grep -A 8 "Endpoints:"

Exemplo de resposta:

Endpoints:
  Name: Read-Write
  Value: 10.128.0.45:5432
  Name: Read-Only
  Value: 10.128.0.46:5432

O endpoint de leitura e gravação (serviço al-adbo-rw-ilb) encaminha para o banco de dados principal, enquanto o endpoint somente leitura (serviço al-adbo-ro-ilb) distribui as consultas de leitura entre as instâncias em espera.

7. Configurar BackupPlans automatizados (local e GCS)

O AlloyDB Omni oferece backups físicos e arquivamento de WAL pelo recurso personalizado BackupPlan. É possível configurar a retenção de backup, as programações cron automatizadas e os destinos de backup (volumes permanentes locais ou Google Cloud Storage).

1. Criar BackupPlan local

Crie um BackupPlan que grave backups no armazenamento local do Kubernetes anexado às instâncias do banco de dados:

kubectl apply -n omni-demo -f - <<EOF
apiVersion: alloydbomni.dbadmin.goog/v1
kind: BackupPlan
metadata:
  name: backupplan-local
spec:
  dbclusterRef: adbo
  backupSchedules:
    full: "0 2 * * *" # Daily at 02:00 UTC
    incremental: "0 */4 * * *" # Every 4 hours
  backupRetainDays: 7
EOF

Verifique se o BackupPlan local está pronto:

kubectl get backupplan backupplan-local -n omni-demo

Aguarde até que PHASE informe Ready e NEXTBACKUPTIME seja programado.

2. Criar o BackupPlan do GCS (Caminho 1: somente Google Cloud — opcional)

Para armazenar backups externamente em um bucket do Google Cloud Storage, crie um bucket do GCS, configure um secret de chave de conta de serviço e aplique um BackupPlan de nuvem.

  1. Crie um bucket do Cloud Storage:
export BUCKET_NAME="${PROJECT_ID}-omni-backups"
gcloud storage buckets create gs://${BUCKET_NAME} --location=${REGION}
  1. Crie uma conta de serviço com permissões de Administrador de objetos do Storage e uma chave para ela:

export SA_NAME="omni-backup-sa"
gcloud iam service-accounts create ${SA_NAME} --display-name="AlloyDB Omni Backup SA"

gcloud projects add-iam-policy-binding ${PROJECT_ID} \
  --member="serviceAccount:${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/storage.objectAdmin"

gcloud iam service-accounts keys create /tmp/gcs-key.json \
  --iam-account="${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"
  1. Crie o secret no namespace do Kubernetes:
kubectl create secret generic gcs-backup-secret \
  --from-file=key.json=/tmp/gcs-key.json \
  -n omni-demo
rm /tmp/gcs-key.json
  1. Aplique o manifesto BackupPlan do GCS. O campo key é a pasta no bucket em que o operador grava backups. Ele precisa começar com /.
kubectl apply -n omni-demo -f - <<EOF
apiVersion: alloydbomni.dbadmin.goog/v1
kind: BackupPlan
metadata:
  name: backupplan-gcs
spec:
  dbclusterRef: adbo
  backupSchedules:
    full: "0 1 * * *"
    incremental: "0 */6 * * *"
  backupRetainDays: 14
  backupLocation:
    type: GCS
    gcsOptions:
      bucket: ${BUCKET_NAME}
      key: /omni-backups/adbo
      secretRef:
        name: gcs-backup-secret
        namespace: omni-demo
EOF

Verifique o status do BackupPlan do GCS:

kubectl get backupplan backupplan-gcs -n omni-demo

Aguarde até que PHASE informe Ready e NEXTBACKUPTIME seja programado.

8. Inserir dados, acionar backup e testar restauração

Nesta etapa, você vai preencher os dados iniciais no banco de dados principal, acionar um backup manual on demand, adicionar dados subsequentes e restaurar o backup para comprovar a reversão de dados.

1. Preencher dados iniciais

Execute um pod cliente temporário do PostgreSQL para se conectar ao banco de dados pelo serviço de leitura e gravação al-adbo-rw-ilb como o usuário postgres:

kubectl run pg-client --rm -i --tty --image=postgres:16 --restart=Never -n omni-demo -- \
  psql -h al-adbo-rw-ilb -U postgres -d postgres -c "
    CREATE TABLE customers (id SERIAL PRIMARY KEY, name TEXT, created_at TIMESTAMPTZ DEFAULT pg_catalog.now());
    INSERT INTO customers (name) VALUES ('Alpha Co'), ('Beta LLC');
    SELECT * FROM customers;
  "

Quando a senha for solicitada, digite ChangeMe123. Essa é a senha que você codificou em base64 no Secret db-pw-adbo na Etapa 5.

2. Acionar um backup on demand

Crie um recurso personalizado Backup manual que faça referência ao BackupPlan local:

kubectl apply -n omni-demo -f - <<EOF
apiVersion: alloydbomni.dbadmin.goog/v1
kind: Backup
metadata:
  name: initial-customer-backup
spec:
  dbclusterRef: adbo
  backupPlanRef: backupplan-local
  manual: true
EOF

Monitore o progresso do backup:

kubectl get backup initial-customer-backup -n omni-demo -w

Aguarde até que PHASE mude para Succeeded.

3. Modificar dados (adicionar novos registros)

Insira outros registros após o backup:

kubectl run pg-client --rm -i --tty --image=postgres:16 --restart=Never -n omni-demo \
  --env="PGPASSWORD=ChangeMe123" -- \
  psql -h al-adbo-rw-ilb -U postgres -d postgres -c "
    INSERT INTO customers (name) VALUES ('Gamma Inc'), ('Delta Corp');
    SELECT * FROM customers;
  "

O banco de dados agora contém quatro linhas.

4. Restaurar usando o backup

Acione uma restauração para o estado capturado em initial-customer-backup:

kubectl apply -n omni-demo -f - <<EOF
apiVersion: alloydbomni.dbadmin.goog/v1
kind: Restore
metadata:
  name: restore-to-initial
spec:
  sourceDBCluster: adbo
  backup: initial-customer-backup
EOF

Monitore a operação de restauração:

kubectl get restore restore-to-initial -n omni-demo -w

Aguarde até que PHASE alcance ProvisionSucceeded e verifique se DBCluster retorna para DBClusterReady:

kubectl get dbcluster adbo -n omni-demo -w

5. Verificar o estado dos dados restaurados

Consulte a tabela customers para verificar se apenas os registros anteriores ao backup existem:

kubectl run pg-client --rm -i --tty --image=postgres:16 --restart=Never -n omni-demo \
  --env="PGPASSWORD=ChangeMe123" -- \
  psql -h al-adbo-rw-ilb -U postgres -d postgres -c "
    SELECT * FROM customers;
  "

A saída confirma que apenas 2 linhas (Alpha Co e Beta LLC) estão presentes, verificando se o banco de dados foi restaurado para o estado exato do backup.

9. Recuperação pontual (PITR) para um banco de dados clonado

A recuperação pontual (PITR) permite restaurar um banco de dados para qualquer segundo dentro da janela de recuperação usando backups de base e registros de stream do WAL, provisionando os dados restaurados em um novo cluster de banco de dados clonado.

Como o operador arquiva continuamente o registro prévio de escrita (WAL), a PITR permite que você se recupere de erros humanos ou de aplicativos acidentais, como um DELETE ou DROP TABLE não intencional às 14h15, clonando o banco de dados para o segundo exato antes do erro (14h14min59s), sem tocar no cluster original.

1. Registrar o carimbo de data/hora atual e modificar dados

Recupere o carimbo de data/hora UTC atual:

export PITR_TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
echo "PITR Target Timestamp: ${PITR_TIMESTAMP}"

Insira um registro de teste que represente uma modificação indesejada após este carimbo de data/hora:

kubectl run pg-client --rm -i --tty --image=postgres:16 --restart=Never -n omni-demo \
  --env="PGPASSWORD=ChangeMe123" -- \
  psql -h al-adbo-rw-ilb -U postgres -d postgres -c "
    INSERT INTO customers (name) VALUES ('Unwanted Record Post-Timestamp');
    SELECT * FROM customers;
  "

2. Realizar a restauração pontual

Aplique o recurso personalizado Restore configurando pointInTime e clonedDBClusterConfig:

kubectl apply -n omni-demo -f - <<EOF
apiVersion: alloydbomni.dbadmin.goog/v1
kind: Restore
metadata:
  name: restore-pitr-clone
spec:
  sourceDBCluster: adbo
  pointInTime: "${PITR_TIMESTAMP}"
  clonedDBClusterConfig:
    dbclusterName: adbo-cloned
EOF

Monitore a operação de restauração até que PHASE chegue a ProvisionSucceeded:

kubectl get restore restore-pitr-clone -n omni-demo -w

3. Verificar o banco de dados clonado

Depois que a restauração for concluída, aguarde até que o novo DBCluster clonado alcance DBClusterReady (pressione Ctrl+C para sair do modo de observação):

kubectl get dbcluster adbo-cloned -n omni-demo -w

Consulte o banco de dados clonado adbo-cloned pelo Serviço de leitura e gravação al-adbo-cloned-rw-ilb:

kubectl run pg-client --rm -i --tty --image=postgres:16 --restart=Never -n omni-demo \
  --env="PGPASSWORD=ChangeMe123" -- \
  psql -h al-adbo-cloned-rw-ilb -U postgres -d postgres -c "
    SELECT * FROM customers;
  "

Observe que Unwanted Record Post-Timestamp está ausente no cluster clonado, o que demonstra uma recuperação precisa para o momento exato de destino.

10. Implantar o pooler de conexões do PgBouncer

O pool de conexões reduz a sobrecarga de memória do banco de dados e a latência de conexão. O operador gerencia instâncias do PgBouncer de forma nativa usando o recurso personalizado PgBouncer.

O PostgreSQL cria um processo de sistema operacional separado para cada conexão de cliente. Por isso, centenas de conexões simultâneas de serviços da Web, microsserviços ou agentes de IA podem esgotar a memória do banco de dados. O PgBouncer fica na frente do banco de dados e multiplexa muitas conexões de cliente de curta duração (até max_client_conn) em um pequeno pool de conexões de servidor PostgreSQL de longa duração (default_pool_size por par de usuário/banco de dados, limitado por max_db_connections).

1. Implantar o PgBouncer

Implante um pooler do PgBouncer de duas réplicas vinculado ao cluster adbo:

kubectl apply -n omni-demo -f - <<EOF
apiVersion: alloydbomni.dbadmin.goog/v1
kind: PgBouncer
metadata:
  name: omni-pgbouncer
spec:
  dbclusterRef: adbo
  allowSuperUserAccess: true
  replicaCount: 2
  parameters:
    pool_mode: transaction
    default_pool_size: "20"
    max_client_conn: "500"
    max_db_connections: "100"
  podSpec:
    resources:
      cpu: 1
      memory: 1Gi
    image: "gcr.io/alloydb-omni/operator/g-pgbouncer:1.4.0"
  serviceOptions:
    type: ClusterIP
EOF

2. Verificar o status do PgBouncer

Observe o status do PgBouncer até que PHASE seja Ready:

kubectl get pgbouncer omni-pgbouncer -n omni-demo -w

Verifique os pods e o serviço do PgBouncer em execução:

kubectl get pods -n omni-demo
kubectl get svc al-omni-pgbouncer-pgb-svc -n omni-demo

3. Conectar via PgBouncer

Conecte um cliente pelo serviço PgBouncer na porta 6432:

kubectl run pg-client --rm -i --tty --image=postgres:16 --restart=Never -n omni-demo \
  --env="PGPASSWORD=ChangeMe123" -- \
  psql -h al-omni-pgbouncer-pgb-svc -p 6432 -U postgres -d postgres -c "
    SELECT pg_catalog.version();
    SELECT * FROM customers;
  "

O PgBouncer faz o proxy da consulta para o banco de dados primário do AlloyDB Omni.

11. Implantar o pgAdmin4 para acessar o banco de dados

É possível executar o pgAdmin4 diretamente no cluster do Kubernetes para fornecer um console de administração baseado na Web para consultar, gerenciar e inspecionar o AlloyDB Omni.

1. Instalar o pgAdmin4 pelo Helm

Instale pgadmin4 no namespace omni-demo:

helm install my-pgadmin oci://docker.io/dpage/pgadmin4-helm \
  --namespace omni-demo \
  --set ingress.enabled=false \
  --set image.tag=latest \
  --set auth.email="admin@example.com" \
  --set auth.password="AdminPassword123"

Esse gráfico nomeia os recursos do Kubernetes como pgadmin4 (Deployment, Service, PersistentVolumeClaim) e rotula os pods com app=pgadmin4, independentemente do nome da versão do Helm (my-pgadmin).

Verifique se o pod pgAdmin4 está em execução:

kubectl wait --namespace omni-demo \
  --for=condition=ready pod \
  --selector=app=pgadmin4 \
  --timeout=300s

2. Encaminhar porta e acessar a interface da Web

Encaminhe o pgAdmin4 para seu ambiente local ou para o Cloud Shell:

kubectl port-forward service/pgadmin4 5050:80 -n omni-demo

O kubectl port-forward continua em execução em primeiro plano enquanto você usa a interface da Web do pgAdmin4. Abra um segundo terminal (ou uma nova guia do Cloud Shell) para outros comandos e pressione Ctrl+C nesse terminal quando estiver tudo pronto para seguir para a próxima etapa.

Abra a interface da Web do pgAdmin4:

  • Caminho 1 (Google Cloud Shell): clique no botão Visualização na Web no menu superior direito, selecione Alterar porta, insira 5050 e clique em Alterar e visualizar.
  • Caminho 2 (estação de trabalho local): abra http://localhost:5050 no navegador enquanto o comando kubectl port-forward estiver em execução.

Faça login usando:

  • E-mail: admin@example.com
  • Senha: AdminPassword123

3. Registrar o AlloyDB Omni no pgAdmin4

  1. No pgAdmin4, clique com o botão direito do mouse em Servidores > Registrar > Servidor....
  2. Na guia Geral:
    • Nome: AlloyDB Omni Primary
  3. Na guia Conexão:
    • Nome do host/endereço: al-adbo-rw-ilb.omni-demo.svc.cluster.local (ou al-omni-pgbouncer-pgb-svc.omni-demo.svc.cluster.local para PgBouncer)
    • Porta: 5432 (ou 6432 para PgBouncer)
    • Banco de dados de manutenção: postgres
    • Nome de usuário: postgres
    • Senha: ChangeMe123
  4. Clique em Salvar e verifique a sessão e as tabelas do banco de dados ativo.

12. Escalonar CPU e memória com manutenção de baixo tempo de inatividade (LDTM)

Ao escalonar verticalmente a computação e a memória em um banco de dados de produção, as atualizações tradicionais causam interrupções na reinicialização do banco de dados. O AlloyDB Omni oferece a manutenção com baixo tempo de inatividade (LDTM, na sigla em inglês) para implementar atualizações graduais em réplicas com o mínimo de interrupção do aplicativo.

1. Ativar a anotação LDTM

Anote o DBCluster para ativar o LDTM para atualizações:

kubectl annotate dbclusters.alloydbomni.dbadmin.goog adbo -n omni-demo dbcluster.dbadmin.goog/enableLDTM=true --overwrite

2. Escalonar recursos de CPU e memória

Atualize os recursos principais de cpu: 1, memory: 4Gi para cpu: 2, memory: 8Gi:

kubectl patch dbcluster adbo -n omni-demo --type=merge -p '{
  "spec": {
    "primarySpec": {
      "resources": {
        "cpu": 2,
        "memory": "8Gi"
      }
    }
  }
}'

3. Monitorar o progresso do escalonamento do LDTM

Monitore a atualização gradual e as condições de alternância de espera para primário:

kubectl get dbcluster adbo -n omni-demo -o yaml | grep -A 5 -B 2 "LDTMScalingInProgress"

Observe os pods sendo atualizados de forma gradual:

kubectl get pods -n omni-demo -w

O LDTM prepara primeiro o modo de espera atualizado, verifica a replicação de streaming, executa uma troca rápida e atualiza a instância restante sem interrupções de serviço.

Verifique a alocação de recursos atualizada:

kubectl get dbcluster adbo -n omni-demo -o jsonpath='{.spec.primarySpec.resources}'

13. Limpar recursos

Para liberar capacidade do cluster e evitar cobranças desnecessárias na sua conta do Google Cloud, limpe os recursos provisionados durante este codelab.

Se você estiver executando a limpeza em uma nova sessão de terminal (Caminho 1), as variáveis de ambiente das etapas anteriores não estarão mais definidas. Exporte-as novamente com os mesmos valores usados antes:

export PROJECT_ID="<YOUR_PROJECT_ID>"
export REGION="us-central1"
export CLUSTER_NAME="omni-autopilot-cluster"
export BUCKET_NAME="${PROJECT_ID}-omni-backups"
export SA_NAME="omni-backup-sa"
gcloud config set project ${PROJECT_ID}

1. Excluir cargas de trabalho do banco de dados (Caminho 1 e Caminho 2)

Marque os dois clusters como excluídos para passar nas verificações do webhook de admissão, aguarde o operador remover os recursos DBCluster e exclua o namespace:

kubectl patch dbcluster adbo -n omni-demo --type=merge -p '{"spec":{"isDeleted":true}}'
kubectl patch dbcluster adbo-cloned -n omni-demo --type=merge -p '{"spec":{"isDeleted":true}}'
kubectl wait --for=delete dbcluster/adbo dbcluster/adbo-cloned -n omni-demo --timeout=300s
kubectl delete namespace omni-demo

Se você usou seu próprio cluster do Kubernetes (Caminho 2) e também quer remover o operador do AlloyDB Omni e o cert-manager:

helm uninstall alloydbomni-operator -n alloydb-omni-system
kubectl delete namespace alloydb-omni-system
helm uninstall cert-manager -n cert-manager
kubectl delete namespace cert-manager

2. Excluir o bucket do GCS e a conta de serviço do IAM (somente caminho 1)

Se você criou o bucket do Google Cloud Storage e a conta de serviço no Caminho 1:

gcloud storage rm --recursive gs://${BUCKET_NAME}
gcloud projects remove-iam-policy-binding ${PROJECT_ID} \
  --member="serviceAccount:${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/storage.objectAdmin"
gcloud iam service-accounts delete ${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com --quiet

3. Excluir o cluster do GKE (somente caminho 1)

Se você provisionou um cluster do Autopilot do GKE no Caminho 1:

gcloud container clusters delete ${CLUSTER_NAME} --region=${REGION} --quiet

14. Parabéns

Parabéns! Você concluiu o codelab do AlloyDB Omni no Kubernetes.

O que vimos

  • Provisionou um cluster do GKE Autopilot (Caminho 1) ou preparou um cluster do Kubernetes (Caminho 2).
  • Implantou o cert-manager e o operador do AlloyDB Omni no Kubernetes usando o Helm.
  • Implantou uma instância única do AlloyDB Omni DBCluster.
  • Fez upgrade do cluster para alta disponibilidade (HA) com standbys síncronos e ativou o roteamento de standby somente leitura.
  • Criou recursos automatizados do BackupPlan para armazenamento permanente local e Google Cloud Storage (GCS).
  • Fazer backups on demand e validar restaurações de banco de dados.
  • Executou a recuperação pontual (PITR) em um novo cluster de banco de dados clonado.
  • Implantamos um pool de conexões do PgBouncer para conexões de cliente escalonáveis.
  • Implantou e conectou o pgAdmin4 para gerenciamento de bancos de dados.
  • Executou a manutenção de baixa inatividade (LDTM, na sigla em inglês) para escalonar dinamicamente os recursos de computação e memória.

Próximas etapas

15. Pesquisa

Como você usará este tutorial?

Apenas leitura Leitura e exercícios