Implantar um cluster de alta disponibilidade do AlloyDB Omni em VMs do GCE usando o RPM Orchestrator

1. Introdução

Este codelab demonstra a implantação de clusters de alta disponibilidade (HA) do AlloyDB Omni em máquinas virtuais (VMs) do Google Compute Engine (GCE). Ao final deste codelab, você vai provisionar uma arquitetura de referência de HA que consiste em três nós de banco de dados e dois nós HAProxy, além de um nó de controle para operações de gerenciamento.

Pré-requisitos

  • Acesso a um projeto do Google Cloud e ao Cloud Shell no console do Cloud.
  • SDK Google Cloud (gcloud) instalado e configurado. Para mais detalhes sobre a instalação do gcloud, consulte gcloud-install.
  • Terraform v1.9.8 instalado.

O que você vai aprender

  • Como criar e preparar VMs do GCE para o AlloyDB Omni.
  • Como instalar e executar o orquestrador de RPM do AlloyDB Omni.
  • Como instalar e configurar RPMs do AlloyDB Omni para arquitetura de referência de HA.

O que é necessário

  • Receber o link do URL para RPMs do AlloyDB Omni e o orquestrador de RPM. Para isso, preencha o formulário de inscrição do AlloyDB Omni. Os links são enviados para o e-mail do servidor de URL do repositório. Inicialize as seguintes variáveis de ambiente para manter os URLs à mão, que serão usados durante o codelab.
    export ORCHESTRATOR_ANSIBLE_COLLECTION_PATH="..."
export ALLOYDB_OMNI_REPOSITORY_URL="..."
export ALLOYDB_OMNI_ORCHESTRATOR_REPOSITORY_URL="..."
export ALLOYDB_OMNI_COMMON_REPOSITORY_URL=....
export ETCD_REPOSITORY_URL="..."
  • Um terminal funcional com acesso à pilha de implantação do AlloyDB Omni. Você pode usar o Cloud Shell para essa finalidade.

2. Configuração e requisitos

Configuração do projeto

Criar um projeto do Google Cloud

  1. No console do Google Cloud, na página de seletor de projetos, selecione ou crie um projeto na nuvem.
  2. Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como verificar se o faturamento está ativado em um projeto.

Iniciar Cloud Shell

Embora o Google Cloud possa ser operado remotamente em seu laptop, neste codelab vamos usar o Google Cloud Shell, um ambiente de linha de comando executado no Google Cloud.

No console do Google Cloud, clique no ícone do Cloud Shell na barra de ferramentas superior à direita:

Ícone para ativar o Cloud Shell

Como alternativa, pressione G e S. Essa sequência vai ativar o Cloud Shell se você estiver no console do Google Cloud ou usar este link.

O provisionamento e a conexão com o ambiente levarão apenas alguns instantes para serem concluídos: Quando o processamento for concluído, você verá algo como:

Terminal do Google Cloud Shell mostrando que o ambiente foi conectado

Essa máquina virtual contém todas as ferramentas de desenvolvimento necessárias. Ela oferece um diretório principal persistente de 5 GB, além de ser executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede. Neste codelab, todo o trabalho pode ser feito com um navegador. Não é necessário instalar nada.

3. Criar máquinas virtuais do Google Cloud Compute Engine

Preparar scripts do Terraform

  1. Defina variáveis de ambiente para o ID do projeto e o nome do cluster desejado. Você vai usar esses recursos ao longo do codelab.
    export PROJECT="your-project-id"
export CLUSTER="your-cluster-name"
    Observação: o ID do projeto do Google Cloud precisa ter entre 6 e 30 caracteres. Para mais informações, consulte https://docs.cloud.google.com/resource-manager/docs/creating-managing-projects#before_you_begin.
  2. Verifique se você fez login com o usuário da conta do Google Cloud.
    gcloud auth login
  3. Crie um diretório de trabalho para sua implantação e copie os arquivos de configuração do Terraform necessários da origem do repositório.
    mkdir -p ~/alloydb-omni/$PROJECT/$CLUSTER
cd ~/alloydb-omni/$PROJECT/$CLUSTER
gcloud storage cp gs://alloydb-omni-install/rpm-orchestrator/gce/terraform/*.tf .
  4. Crie um arquivo terraform.tfvars para especificar os parâmetros necessários de acordo com a arquitetura de referência, conforme o conteúdo a seguir:
    cat > terraform.tfvars <<EOF
# Required instance counts for reference architecture
db_instance_count      = 3
haproxy_instance_count = 2
control_instance_count = 1

# Optional: Customize if needed with the below variables
# os_image             = "rocky-linux-cloud/rocky-linux-9"
# zone                 = "us-west4-c"
# region_1             = "us-west4"
# db_instance_type     = "c4-highmem-4"
# db_disk_type         = "hyperdisk-balanced"
# db_data_size         =  "50" # GB
# data_dir             =  "/data"
EOF

Executar scripts do Terraform e validar

  1. Agora você pode provisionar as VMs.
    terraform init
  2. Antes de criar VMs, verifique se você tem o acesso necessário para criar VMs e outros recursos. Em resumo, você vai precisar das seguintes permissões.
    roles/compute.admin
roles/iam.roleAdmin
roles/compute.osAdminLogin
roles/iam.serviceAccountCreator
roles/iam.serviceAccountUser
roles/artifactregistry.repoAdmin
roles/storage.objectUser
roles/resourcemanager.projectIamAdmin
roles/serviceusage.serviceUsageAdmin
  3. Valide a configuração e aplique-a para provisionar os recursos.
    terraform validate
terraform apply --auto-approve
    Observação: verifique se você está usando o Terraform v1.9.8 conforme esperado pela configuração de implantação.
  4. Quando o Terraform for concluído, verifique se as máquinas virtuais foram criadas listando as instâncias criadas usando gcloud.
    gcloud compute instances list --filter="name~$CLUSTER" --project=$PROJECT
    Você verá instâncias correspondentes aos três nós de banco de dados, dois nós HAProxy e a VM de controle e as zonas correspondentes. Grave a ZONA do nó de controle. Vamos precisar dela mais tarde neste codelab.
    export ZONE=$(gcloud compute instances list \
  --filter="name=$CLUSTER-control"          \
  --format="value(zone)" --project=$PROJECT)

4. Preparar as VMs para a implantação

É necessário criar uma sessão SSH no nó de controle e executar etapas para ativar o acesso SSH a todas as VMs (também chamadas de nós).

  1. Verifique se as variáveis de ambiente do projeto e do cluster estão definidas.
    export PROJECT="your-project-id"
export CLUSTER="your-cluster-name"
  2. Crie uma chave SSH e adicione-a para fazer login na VM de controle.
    # Replace values with your specific GCP project, cluster and zone details
ssh-keygen -t ed25519 -f $HOME/.ssh/google_compute_engine
gcloud compute os-login ssh-keys add --key-file=$HOME/.ssh/google_compute_engine.pub --project=$PROJECT
  3. Crie uma regra de firewall para permitir conexões SSH e também permitir o tráfego VRRP.
    gcloud compute config-ssh --project=$PROJECT
gcloud compute firewall-rules create $CLUSTER-allow-ssh --network=$CLUSTER --project=$PROJECT --direction=INGRESS --action=allow --rules=tcp:22 --source-ranges="0.0.0.0/0"
gcloud compute firewall-rules create $CLUSTER-allow-vrrp --network=$CLUSTER --project=$PROJECT --allow=112 --source-ranges="0.0.0.0/0"
  4. Conecte-se à VM de controle por SSH:
    gcloud compute ssh "$CLUSTER-control" --zone=$ZONE --project=$PROJECT
  5. Crie um grupo do Linux no nó de controle com o mesmo nome do nome de usuário:
    sudo groupadd $(id -un)
sudo usermod -aG $(id -un) $(id -un)
  6. A configuração do Terraform cria alguns scripts de configuração e os prepara no diretório /tmp/ da VM de controle, que inclui itens como nome do cluster, conta de serviço, nome do projeto etc.Crie acesso SSH sem senha dos nós de controle a todos os nós do cluster usando scripts de configuração no nó de controle.
    /tmp/setup-ssh-for-cluster.sh
    Importante: anote o usuário service_account. Vamos usá-lo como SSH_USER mais tarde neste codelab.
  7. Para este codelab, podemos desativar o SELinux em todos os nós. O script do Terraform adiciona "/tmp/run-all.sh", que pode ser usado para essa finalidade.
    /tmp/run-all.sh sudo setenforce 0
  8. Se você se inscreveu no AlloyDB Omni e recebeu os links, é hora de adicionar esses URLs às variáveis de ambiente também.
    cat >> ~/.codelab.env <<EOF
export ORCHESTRATOR_ANSIBLE_COLLECTION_PATH="..."
export ALLOYDB_OMNI_REPOSITORY_URL="..."
export ALLOYDB_OMNI_ORCHESTRATOR_REPOSITORY_URL="..."
export ALLOYDB_OMNI_COMMON_REPOSITORY_URL=....
export ETCD_REPOSITORY_URL="..."
EOF
    Escolha um IP virtual para seu ambiente na variável de entrada cidr_range no arquivo terraform/variables.tf, de modo que ele não entre em conflito com os outros nós, conforme mostrado no exemplo a seguir:
    cat >> ~/.codelab.env <<EOF
export VIRTUAL_IP="10.1.0.50"
EOF

5. Instalar componentes de software necessários em todas as VMs

A próxima etapa é instalar os componentes de software necessários nas VMs. Isso pode ser coordenado no nó de controle. Todos os comandos a seguir precisam ser executados no nó de controle.

  1. Conecte-se à VM de controle por SSH, se ainda não estiver no nó de controle.
    gcloud compute ssh "$CLUSTER-control" --zone=$ZONE --project=$PROJECT
    Depois de acessar o prompt SSH da VM de controle, arquivo de ambiente de origem.
    source ~/.codelab.env
  2. No nó de controle, instale o Ansible e as bibliotecas necessárias do Python.
    sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm -y
sudo dnf install -y ansible
sudo dnf install -y python3-grpcio python3-protobuf python3-googleapis-common-protos python3-grpcio-status
  3. Em seguida, faça o download do arquivo tar da coleção do Ansible do orquestrador de RPM e instale-o.
    gcloud storage cp "gs://${ORCHESTRATOR_ANSIBLE_COLLECTION_PATH#https://storage.googleapis.com/}google-alloydbomni_orchestrator-*.tar.gz" .
ansible-galaxy collection install google-alloydbomni_orchestrator-0.1.0-6.tar.gz
ansible-galaxy collection list | grep alloydbomni_orchestrator
    Observação: verifique se a variável ORCHESTRATOR_ANSIBLE_COLLECTION_PATH tem "/" no final.
  4. O orquestrador usa um arquivo de especificação de implantação no formato de inventário do Ansible para entender a topologia do cluster. Crie um arquivo chamado deployment_spec.yaml com os detalhes do nó no nó de controle.
    cat > deployment_spec.yaml <<EOF
alloydbomni:
  vars:
    cluster_manager:
      name: "$CLUSTER"
    etcd:
      setup: true
      config_forcewrite: true
    alloydbomni:
      major_version: "18"
      repo_url: $ALLOYDB_OMNI_REPOSITORY_URL
    alloydbomni_monitor:
      repo_url: $ALLOYDB_OMNI_COMMON_REPOSITORY_URL
    alloydbomni_cluster_manager:
      repo_url: $ALLOYDB_OMNI_ORCHESTRATOR_REPOSITORY_URL
    alloydbomni_node_manager:
      repo_url: $ALLOYDB_OMNI_ORCHESTRATOR_REPOSITORY_URL
    pgbouncer:
      repo_url: $ALLOYDB_OMNI_COMMON_REPOSITORY_URL
    pgbackrest:
      repo_url: $ALLOYDB_OMNI_COMMON_REPOSITORY_URL

  children:
    primary_instance_nodes:
      hosts:
        $CLUSTER-db1:
        $CLUSTER-db2:
        $CLUSTER-db3:
    load_balancer_nodes:
      hosts:
        $CLUSTER-haproxy1:
        $CLUSTER-haproxy2:
EOF
    Observação: revise o arquivo gerado para garantir que ele se refira a valores válidos.
  5. Crie um playbook chamado install.yaml que faça referência ao papel de instalação da coleção do orquestrador.
    cat > install.yaml <<EOF
- name: Install AlloyDB Omni cluster components
  hosts: all
  vars:
    ansible_become: true
    ansible_user: $SSH_USER
    ansible_ssh_private_key_file: $HOME/ssh-key-cluster-sa
  roles:
    - role: google.alloydbomni_orchestrator.install
EOF
    Observação: revise o arquivo gerado para garantir que ele se refira a valores válidos.
  6. Execute o playbook usando o arquivo de inventário para fazer o download e instalar os RPMs em todos os nós especificados.
    ansible-playbook -i deployment_spec.yaml install.yaml

6. Inicializar o cluster do AlloyDB Omni

Nesta fase, instalamos todos os componentes necessários em todos os nós. Estamos prontos para inicializar o cluster do AlloyDB Omni.

  1. Conecte-se à VM de controle por SSH, se ainda não estiver no nó de controle.
    gcloud compute ssh "$CLUSTER-control" --zone=$ZONE --project=$PROJECT
    Depois de acessar o prompt SSH da VM de controle, arquivo de ambiente de origem.
    source ~/.codelab.env
  2. Gere um hash para sua senha e anote-o.
    encoded_password=$(echo -n "your unique password" | base64)
  3. Para criar o cluster, o AlloyDB Omni precisa saber como configurá-lo. Crie um nome de arquivo dbcluster.yaml para as especificações do cluster de banco de dados.
    cat > dbcluster.yaml <<EOF
Secret:
  metadata:
    name: db-pw-$CLUSTER
  spec:
    type: Opaque
    data:
      $CLUSTER: $encoded_password
---
DBCluster:
  metadata:
    name: $CLUSTER
  spec:
    databaseVersion: 18.1.0
    mode: ""
    availability:
      numberOfStandbys: 2
      enableAutoFailover: true
      enableAutoHeal: true
      autoFailoverTriggerThreshold: 2
      autoHealTriggerThreshold: 2
      healthcheckPeriodSeconds: 5
      replayReplicationSlotsOnStandbys: false
    primarySpec:
      adminUser:
        passwordRef:
          name: db-pw-$CLUSTER
      resources:
        cpu: 4
        memory: 32Gi
        disks:
        - name: DataDisk
          path: $PGDATA
      dbLoadBalancerOptions:
        gcp:
          loadBalancerIP: "$VIRTUAL_IP"
          loadBalancerType: "internal"
          loadBalancerInterface: "eth0"
EOF
  4. Crie um playbook chamado bootstrap.yaml, que vai se referir ao papel do Ansible de inicialização para criar o cluster do AlloyDB Omni.
    cat > bootstrap.yaml <<EOF
- name: Create DBCluster
  hosts: localhost
  vars:
    ansible_become: true
    ansible_user: $SSH_USER
    ansible_ssh_private_key_file: $HOME/ssh-key-cluster-sa
  roles:
  - role: google.alloydbomni_orchestrator.bootstrap
EOF
  5. Execute o playbook para criar o cluster.
    ansible-playbook bootstrap.yaml -i deployment_spec.yaml -e resource_spec=dbcluster.yaml

7. (Opcional) Configurar o pool de conexões do PgBouncer

O AlloyDB Omni oferece suporte ao pool de conexões leve usando o PgBouncer. É possível configurar e inicializar o PgBouncer logo após o provisionamento do cluster.

  1. Crie um arquivo de especificação de recursos chamado pgbouncer.yaml que associa o pool de conexões ao cluster de banco de dados:
    cat > pgbouncer.yaml <<EOF
PgBouncer:
  metadata:
    name: pgbouncer-pooler
  spec:
    dbclusterRef: $CLUSTER
    allowSuperUserAccess: true
    accessMode: "rw"
    port: 6432
EOF
  2. Inicialize o pool do PgBouncer usando o mesmo playbook bootstrap.yaml criado anteriormente, transmitindo o novo arquivo de especificação:
    ansible-playbook bootstrap.yaml -i deployment_spec.yaml -e resource_spec=pgbouncer.yaml

8. Verificar o cluster do AlloyDB Omni

Para verificar se o cluster está funcionando corretamente e acessível usando o balanceador de carga, conecte-se a ele usando o cliente PostgreSQL padrão do nó de controle.

  1. Instale o repositório e o pacote do cliente PostgreSQL 18 no nó de controle:
    sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm
sudo dnf install -y postgresql18
  2. Conecte-se ao cluster usando o IP virtual reservado anteriormente. Você vai receber uma solicitação para a senha codificada em dbcluster.yaml:
    /usr/pgsql-18/bin/psql -h $VIRTUAL_IP -U postgres -W
  3. Depois de conectado, você pode executar consultas SQL básicas para verificar o estado do cluster, por exemplo, verificando a versão do banco de dados:
    postgres=# SELECT version();
    Você verá uma saída indicando que o PostgreSQL 18 está em execução com o AlloyDB Omni. Digite \q para sair do prompt.

9. (Opcional) Fazer backup de dados usando pgBackRest

O AlloyDB Omni é integrado ao pgBackRest para gerenciar backups diretamente no Cloud Storage. É possível configurar um plano de backup e acionar um backup on demand no bucket do GCS criado pela configuração do Terraform.

  1. Crie um arquivo de especificação de plano de backup chamado backup_plan.yaml que aponte para o bucket do GCS provisionado:
    cat > backup_plan.yaml <<EOF
BackupPlan:
  metadata:
    name: pgb-plan
  spec:
    dbclusterRef: $CLUSTER
    backupLocation:
      type: GCS
      gcsOptions:
        bucket: $CLUSTER-gcs-backups
        key: /backups
EOF
  2. Crie um playbook do Ansible chamado backup.yaml que faça referência ao papel de gerenciamento de backup:
    cat > backup.yaml <<EOF
- name: Manage AlloyDB Omni Backups
  hosts: localhost
  vars:
    ansible_become: true
    ansible_user: $SSH_USER
    ansible_ssh_private_key_file: $HOME/ssh-key-cluster-sa
  roles:
    - role: google.alloydbomni_orchestrator.backup
EOF
  3. Aplique o plano de backup usando o playbook backup.yaml:
    ansible-playbook backup.yaml -i deployment_spec.yaml -e resource_spec=backup_plan.yaml
  4. Depois que o plano for estabelecido, crie um arquivo de recurso de backup on demand chamado create_backup.yaml.
    cat > create_backup.yaml <<EOF
Backup:
  metadata:
    name: on-demand-backup
  spec:
    backupPlanRef: pgb-plan
    dbclusterRef: $CLUSTER
EOF
  5. Execute o playbook para iniciar o backup:
    ansible-playbook backup.yaml -i deployment_spec.yaml -e resource_spec=create_backup.yaml
  6. Para verificar o status do backup, crie um playbook status.yaml:
- name: Fetch AlloyDB Omni Resource Status
hosts: localhost
vars:
  ansible_become: true
  ansible_user: $SSH_USER
  ansible_ssh_private_key_file: $HOME/ssh-key-cluster-sa
roles:
  - role: google.alloydbomni_orchestrator.status
EOF
  1. Execute o playbook para listar todos os backups:
ansible-playbook status.yaml -i deployment_spec.yaml -e resource_type=Backup
  1. Como alternativa, para receber informações detalhadas sobre um backup específico criado anteriormente, transmita -e resource_name=on-demand-backup:
ansible-playbook status.yaml -i deployment_spec.yaml \
  -e resource_type=Backup \
  -e resource_name=on-demand-backup

10. Limpar recursos

Quando terminar a implantação, destrua os recursos provisionados para evitar cobranças.

  1. Crie um playbook chamado teardown.yaml:
    cat > teardown.yaml <<EOF
- name: Tear down AlloyDB Omni cluster
  hosts: localhost
  vars:
    ansible_become: true
    ansible_user: $SSH_USER
    ansible_ssh_private_key_file: $HOME/ssh-key-cluster-sa
  roles:
  - role: google.alloydbomni_orchestrator.delete
EOF
  2. Execute o playbook usando o ansible-playbook. Se você configurou backups, exclua os recursos de backup e BackupPlan primeiro:
    ansible-playbook teardown.yaml -i deployment_spec.yaml  -e "resource_type=Backup" -e "resource_name=on-demand-backup"
ansible-playbook teardown.yaml -i deployment_spec.yaml  -e "resource_type=BackupPlan" -e "resource_name=pgb-plan"
    Se você configurou o PgBouncer, exclua o recurso do pool de conexões:
    ansible-playbook teardown.yaml -i deployment_spec.yaml  -e "resource_type=PgBouncer" -e "resource_name=pgbouncer-pooler"
    Em seguida, especifique DBCluster como resource_type e exclua o cluster de banco de dados:
    ansible-playbook teardown.yaml -i deployment_spec.yaml  -e "resource_type=DBCluster" -e "resource_name=$CLUSTER"
  3. Depois que o cluster for excluído, faça logout do nó de controle, volte para o terminal e navegue até o diretório de trabalho do Terraform.
    Observação: se você acabou de fazer login no Cloud Shell, lembre-se de definir estes:
    export PROJECT="your-project-id"
export CLUSTER="your-cluster-name"
  4. Exclua a regra de firewall VRRP e destrua os recursos gerenciados pelo Terraform:
    gcloud compute firewall-rules delete -q "$CLUSTER-allow-vrrp" --project="$PROJECT"
gcloud compute firewall-rules delete -q "$CLUSTER-allow-ssh" --project="$PROJECT"
terraform destroy
  5. Confirme a destruição quando solicitado. Como recursos ou rotas de rede persistentes podem ocasionalmente impedir a desmontagem completa, execute os seguintes comandos de limpeza segura para garantir que todas as regras de firewall, gateways NAT, roteadores, rotas, sub-redes e redes associadas sejam totalmente removidas. Substitua REGION pela região de implantação específica, como "us-central1":
    # Delete any remaining firewall rules associated with the cluster
gcloud compute firewall-rules list --project=$PROJECT 2> /dev/null | grep ^$CLUSTER- | cut -f1 -d' ' | \
  while read rule; do gcloud compute firewall-rules delete --project=$PROJECT --quiet $rule; done

# Delete the Cloud NAT gateway and router if they still exist
gcloud compute routers nats describe $CLUSTER-nat-gw --router=$CLUSTER-router --region=REGION --project=$PROJECT 2>/dev/null \
  && gcloud compute routers nats delete $CLUSTER-nat-gw --router=$CLUSTER-router --region=REGION --project=$PROJECT --quiet

gcloud compute routers describe $CLUSTER-router --region=REGION --project=$PROJECT 2>/dev/null \
  && gcloud compute routers delete $CLUSTER-router --region=REGION --project=$PROJECT --quiet

# Delete any remaining custom routes
gcloud compute routes list --project=$PROJECT --filter="network:$CLUSTER" --format="value(name)" 2>/dev/null | \
  while read route; do gcloud compute routes delete --project=$PROJECT --quiet $route 2>/dev/null || true; done

# Delete the subnet and network if they still exist
gcloud compute networks subnets describe $CLUSTER --region=REGION --project=$PROJECT 2>/dev/null \
  && gcloud compute networks subnets delete $CLUSTER --region=REGION --project=$PROJECT --quiet

gcloud compute networks describe $CLUSTER --project $PROJECT 2> /dev/null \
  && gcloud compute networks delete $CLUSTER --project $PROJECT --quiet

11. Parabéns

Parabéns por concluir o codelab.

O que vimos

  • Como criar e preparar VMs do GCE para o AlloyDB Omni.
  • Como instalar e executar o orquestrador de RPM do AlloyDB Omni.
  • Como instalar e configurar RPMs do AlloyDB Omni para arquitetura de referência de HA.

Saiba mais sobre o AlloyDB Omni na documentação.

12. Pesquisa

Como você usará este tutorial?

Apenas leitura Leitura e exercícios