Resolver problemas do operador AlloyDB Omni no Kubernetes

Selecione uma versão da documentação:

Nesta página, mostramos como resolver problemas com o operador do AlloyDB Omni no Kubernetes, incluindo soluções alternativas para problemas conhecidos.

Coletar informações de depuração

Estas seções descrevem como coletar registros e configurações para depuração.

Buscar registros de pods do operador

Para buscar registros dos pods do operador, execute os seguintes comandos:

kubectl logs deployments/fleet-controller-manager -c fleet-manager -n alloydb-omni-system > alloydb-omni-system-fleet-controller-manager.out
kubectl logs deployments/local-controller-manager -c local-manager -n alloydb-omni-system > alloydb-omni-system-local-controller-manager.out

Buscar registros de pods do banco de dados

Para buscar registros de pods do banco de dados, execute os seguintes comandos:

DB_POD=$(kubectl get pod -l alloydbomni.internal.dbadmin.goog/dbcluster=DB_CLUSTER_NAME,alloydbomni.internal.dbadmin.goog/task-type=database -n DB_CLUSTER_NAMESPACE -o jsonpath='{.items[0].metadata.name}')
kubectl logs -c database ${DB_POD} -n DB_CLUSTER_NAMESPACE > ${DB_POD}.log
kubectl logs -l alloydbomni.internal.dbadmin.goog/dbcluster=DB_CLUSTER_NAME -c database -n DB_CLUSTER_NAMESPACE > dbcluster_DB_CLUSTER_NAME.out

Os registros a seguir são exemplos de verificações de integridade do banco de dados bem-sucedidas:

I0813 11:01:49.210051      27 gateway.go:184] "DatabaseHealthCheck: request handled successfully" log_name="agent" project_ns="default" dbcluster="adb"
I0813 11:01:59.196796      27 gateway.go:166] "DatabaseHealthCheck: handling request" log_name="agent" project_ns="default" dbcluster="adb"
I0813 11:01:59.196853      27 database.go:702] "dbdaemon/isRestoreInProgress: starting" log_name="agent" project_ns="default" dbcluster="adb"
I0813 11:01:59.209824      27 gateway.go:184] "DatabaseHealthCheck: request handled successfully" log_name="agent" project_ns="default" dbcluster="adb"
I0813 11:02:09.197013      27 gateway.go:166] "DatabaseHealthCheck: handling request" log_name="agent" project_ns="default" dbcluster="adb"
I0813 11:02:09.197093      27 database.go:702] "dbdaemon/isRestoreInProgress: starting" log_name="agent" project_ns="default" dbcluster="adb"
I0813 11:02:09.210010      27 gateway.go:184] "DatabaseHealthCheck: request handled successfully" log_name="agent" project_ns="default" dbcluster="adb"
I0813 11:02:19.197368      27 gateway.go:166] "DatabaseHealthCheck: handling request" log_name="agent" project_ns="default" dbcluster="adb"
I0813 11:02:19.197425      27 database.go:702] "dbdaemon/isRestoreInProgress: starting" log_name="agent" project_ns="default" dbcluster="adb"
I0813 11:02:19.210416      27 gateway.go:184] "DatabaseHealthCheck: request handled successfully" log_name="agent" project_ns="default" dbcluster="adb"

Busque o postgresql.log

Para buscar o postgresql.log, execute o seguinte comando:

DB_POD=$(kubectl get pod -l alloydbomni.internal.dbadmin.goog/dbcluster=DB_CLUSTER_NAME,alloydbomni.internal.dbadmin.goog/task-type=database -n DB_CLUSTER_NAMESPACE -o jsonpath='{.items[0].metadata.name}')
kubectl exec -c database -n DB_CLUSTER_NAMESPACE -it ${DB_POD} -- cat /obs/diagnostic/postgresql.log > dbcluster_DB_CLUSTER_NAME_postgresql.log

Buscar o arquivo YAML da DBInstance

Para buscar o arquivo YAML DBInstance, execute o seguinte comando:

kubectl get dbclusters.alloydbomni.dbadmin.goog DB_CLUSTER_NAME -n DB_CLUSTER_NAMESPACE -o yaml > dbcluster_DB_CLUSTER_NAME.yaml

Buscar configurações e registros para cenários de alta disponibilidade

Para buscar configurações e registros específicos de cenários de alta disponibilidade (HA), execute os seguintes comandos:

kubectl get replicationconfig.alloydbomni.internal.dbadmin.goog -l alloydbomni.internal.dbadmin.goog/dbcluster=DB_CLUSTER_NAME -n DB_CLUSTER_NAMESPACE -o yaml > replicationconfig_DB_CLUSTER_NAME.yaml
kubectl get deletestandbyjobs.alloydbomni.internal.dbadmin.goog -l alloydbomni.internal.dbadmin.goog/dbcluster=DB_CLUSTER_NAME -n DB_CLUSTER_NAMESPACE -o yaml > deletestandbyjobs_DB_CLUSTER_NAME.yaml
kubectl get createstandbyjobs.alloydbomni.internal.dbadmin.goog -l alloydbomni.internal.dbadmin.goog/dbcluster=DB_CLUSTER_NAME -n DB_CLUSTER_NAMESPACE -o yaml > createstandbyjobs_DB_CLUSTER_NAME.yaml
kubectl get failovers.alloydbomni.dbadmin.goog -l alloydbomni.internal.dbadmin.goog/dbcluster=DB_CLUSTER_NAME -n DB_CLUSTER_NAMESPACE -o yaml > failovers_DB_CLUSTER_NAME.yaml

Buscar status de pod e STS

Para buscar os status do pod e do StatefulSet (STS), execute os seguintes comandos:

DB_POD=$(kubectl get pod -n DB_CLUSTER_NAMESPACE -l alloydbomni.internal.dbadmin.goog/dbcluster=DB_CLUSTER_NAME,alloydbomni.internal.dbadmin.goog/task-type=database -o jsonpath='{.items[0].metadata.name}')
kubectl describe pod ${DB_POD} -n DB_CLUSTER_NAMESPACE > pod_${DB_POD}.out
kubectl describe statefulset -l alloydbomni.internal.dbadmin.goog/dbcluster=DB_CLUSTER_NAME -n DB_CLUSTER_NAMESPACE > statefulset_DB_CLUSTER_NAME.out

Identificar erros

Estas seções descrevem como identificar erros.

Procurar status e códigos de erro

Para identificar o código do erro, verifique o arquivo YAML do DBCluster em "status". Consulte a documentação de códigos de erro para mais informações.

Para buscar o arquivo YAML do DBCluster, execute o seguinte comando:

kubectl get dbclusters.alloydbomni.dbadmin.goog DB_CLUSTER_NAME -n DB_CLUSTER_NAMESPACE -o yaml > dbcluster_DB_CLUSTER_NAME.yaml

Procure por criticalIncidents. Esta seção contém o código do erro e um stack trace.

Confira alguns exemplos de criticalIncidents:

status:
    certificateReference:
      certificateKey: ca.crt
      secretRef:
        name: dbs-al-cert-dr-mce
        namespace: dr
    conditions:
    -   lastTransitionTime: "2024-10-07T22:46:03Z"
    ...
    criticalIncidents:
    -   code: DBSE0304
      createTime: "2024-10-03T11:50:54Z"
      message: 'Healthcheck: Health check invalid result.'
      resource:
        component: healthcheck
        location:
          group: alloydbomni.internal.dbadmin.goog
          kind: Instance
          name: bc0f-dr-mce
          namespace: dr
          version: v1
      stackTrace:
      -   component: healthcheck
        message: 'DBSE0304: Healthcheck: Health check invalid result. rpc error: code
          = Code(10304) desc = DBSE0304: Healthcheck: Health check invalid result.
          dbdaemon/healthCheck: invalid timestamp read back from the healthcheck table.
          Lag is 384837.296269 seconds, wanted 35 seconds'

Também é possível recuperar o status extraindo campos específicos no formato JSON:

kubectl get dbclusters.alloydbomni.dbadmin.goog DB_CLUSTER_NAME -n DB_CLUSTER_NAMESPACE -o jsonpath='{.status.criticalIncidents}' | jq

O resultado será o seguinte:

[
  {
    "code": "DBSE0085",
    "createTime": "2024-03-14T05:41:37Z",
    "message": "Platform: Pod is unschedulable.",
    "resource": {
      "component": "provisioning",
      "location": {
        "group": "alloydb.internal.dbadmin.goog",
        "kind": "Instance",
        "name": "b55f-testdbcluster",
        "namespace": "dbs-system",
        "version": "v1"
      }
    },
    "stackTrace": [
      {
        "component": "provisioning",
        "message": "DBSE0085: Platform: Pod is unschedulable. 0/16 nodes are available: pod has unbound immediate PersistentVolumeClaims. preemption: 0/16 nodes are available: 16 No preemption victims found for incoming pod..: Pod is unschedulable"
      }
    ]
  }
]

Se a mensagem de erro se referir ao pod do banco de dados, verifique as instâncias e os recursos do pod no mesmo namespace:

kubectl get instances.alloydbomni.internal.dbadmin.goog -l alloydbomni.internal.dbadmin.goog/dbcluster=DB_CLUSTER_NAME -n DB_CLUSTER_NAMESPACE -o yaml > instance_DB_CLUSTER_NAME.yaml
kubectl get pods -l alloydbomni.internal.dbadmin.goog/dbcluster=DB_CLUSTER_NAME,alloydbomni.internal.dbadmin.goog/task-type=database -n DB_CLUSTER_NAMESPACE

Problemas conhecidos

Nesta seção, descrevemos problemas conhecidos e soluções alternativas para o operador do AlloyDB Omni. Para uma lista completa de comunicados de lançamento, correções de bugs e atualizações de segurança, consulte as Notas da versão.

Falha na emissão de certificados no cert-manager

O operador do AlloyDB Omni usa cert-manager para provisionar certificados Transport Layer Security (TLS) para o operador e os clusters de banco de dados. Na versão 1.21.2 e anteriores do cert-manager, uma disputa conhecida (problema nº 6331 do cert-manager) pode fazer com que a emissão do certificado falhe e entre em uma espera de nova tentativa de uma hora.

Versões afetadas

Operador do AlloyDB Omni 1.0.0 e versões mais recentes com cert-manager 1.21.2 e anteriores.

Sintomas

Quando esse problema ocorre, é possível observar os seguintes sintomas:

  • Um recurso DBCluster permanece na fase DBClusterWaitingForCertificate, e a criação ou o upgrade do cluster de banco de dados expira.
  • Uma instalação do Helm do operador do AlloyDB Omni falha porque um recurso Certificate, como local-serving-cert no namespace alloydb-omni-system, não está pronto.
  • As condições de status de um recurso Certificate incluem a mensagem CSR not signed by referenced private key com o motivo Failed ou ErrorKeyMatch.

Para encontrar os recursos Certificate afetados por esse problema, execute o seguinte comando:

kubectl get certificates.cert-manager.io --all-namespaces \
    -o jsonpath='{range .items[*]}{.metadata.namespace}{"\t"}{.metadata.name}{"\t"}{.status.conditions[*].message}{"\n"}{end}' \
    | grep "CSR not signed by referenced private key"

A saída lista o namespace, o nome e as mensagens de condição de status de cada recurso Certificate afetado. Se você visualizar um recurso Certificate afetado no formato YAML, o campo status será semelhante ao seguinte:

status:
  conditions:
  - message: 'The certificate request has failed to complete and will be retried: Error generating certificate template: CSR not signed by referenced private key'
    reason: Failed
    status: "False"
    type: Issuing
  failedIssuanceAttempts: 1

Alternativa

Para evitar conflitos de atualização do controlador e reduzir o atraso de repetição de solicitações de certificado com falha de uma hora para 15 segundos, faça upgrade de cert-manager com o feature gate ServerSideApply e durações de espera reduzidas:

helm upgrade cert-manager oci://quay.io/jetstack/charts/cert-manager \
    --version CERT_MANAGER_VERSION \
    --namespace cert-manager \
    --reuse-values \
    --set featureGates="ServerSideApply=true" \
    --set "extraArgs={--certificate-request-minimum-backoff-duration=15s,--certificate-request-maximum-backoff-duration=5m}"

Substitua:

  • CERT_MANAGER_VERSION: a versão do cert-manager instalada no cluster do Kubernetes, como v1.21.2. Para encontrar a versão instalada, execute o comando helm list --namespace cert-manager.

Depois que o controlador cert-manager for reiniciado, verifique se todos os certificados mostram True na coluna READY:

kubectl get certificates.cert-manager.io --all-namespaces

Se uma instalação do operador do AlloyDB Omni falhar devido a esse problema, execute a instalação novamente.

O upgrade da versão secundária de manutenção com pouco tempo de inatividade para de progredir em um cluster de banco de dados secundário

Versões afetadas

Operador do AlloyDB Omni 1.8.0 e versões mais recentes.

Sintomas

Durante um upgrade ou downgrade de versão secundária de um cluster de banco de dados secundário de replicação entre data centers que tenha standbys de alta disponibilidade (HA), a operação para de progredir após o primeiro upgrade de standby. O recurso DBCluster permanece no estado DBCUpgradeInProgress=True com o motivo DBCUpgradeFlowBegins.

Alternativa

  1. Desative a manutenção com pouco tempo de inatividade (LDTM) no cluster de banco de dados secundário para que o operador do AlloyDB Omni conclua o upgrade usando o fluxo de trabalho de upgrade contínuo padrão:

    kubectl annotate dbclusters.alloydbomni.dbadmin.goog DB_CLUSTER_NAME \
        dbcluster.dbadmin.goog/enableLDTM=false \
        --namespace DB_CLUSTER_NAMESPACE \
        --overwrite
    

    Substitua:

    • DB_CLUSTER_NAME: o nome do recurso secundário DBCluster.
    • DB_CLUSTER_NAMESPACE: o namespace do recurso secundário DBCluster.
  2. Verifique se o upgrade foi concluído e se o recurso DBCluster atingiu a fase DBClusterReady:

    kubectl get dbclusters.alloydbomni.dbadmin.goog DB_CLUSTER_NAME \
        --namespace DB_CLUSTER_NAMESPACE
    
  3. Reative a manutenção com pouco tempo de inatividade no cluster de banco de dados secundário para que o recurso DBCluster mantenha a capacidade de manutenção com pouco tempo de inatividade se for promovido a um cluster de banco de dados principal:

    kubectl annotate dbclusters.alloydbomni.dbadmin.goog DB_CLUSTER_NAME \
        dbcluster.dbadmin.goog/enableLDTM=true \
        --namespace DB_CLUSTER_NAMESPACE \
        --overwrite
    

O agente do Monitoring encontra erros de permissão de cgroups após ativar a replicação entre data centers

Versões afetadas

Operador do AlloyDB Omni 1.9.0.

Sintomas

Depois de ativar a replicação entre data centers, o agente de monitoramento encontra erros de permissão nos registros do contêiner ao tentar coletar informações de cgroups.

Alternativa

  1. Liste os pods de banco de dados no cluster de banco de dados secundário para encontrar o nome do pod de banco de dados downstream:

    kubectl get pods \
        --selector alloydbomni.internal.dbadmin.goog/dbcluster=DB_CLUSTER_NAME,alloydbomni.internal.dbadmin.goog/task-type=database \
        --namespace DB_CLUSTER_NAMESPACE
    

    Substitua:

    • DB_CLUSTER_NAME: o nome do recurso secundário DBCluster.
    • DB_CLUSTER_NAMESPACE: o namespace do recurso secundário DBCluster.
  2. Exclua o pod do banco de dados downstream para que o operador do AlloyDB Omni recrie e reinicie o pod:

    kubectl delete pod DB_POD_NAME \
        --namespace DB_CLUSTER_NAMESPACE
    

    Substitua DB_POD_NAME pelo nome do pod do banco de dados downstream da etapa anterior.

O cluster de banco de dados aciona continuamente failovers automáticos

Se o recurso DBCluster criar vários failovers automáticos um após o outro, conclua as seguintes verificações:

  1. Liste os recursos Failover do DBCluster e compare os carimbos de data/hora de criação:

    kubectl get failover.alloydbomni.dbadmin.goog \
        --selector failover.dbadmin.goog/dbcluster=DB_CLUSTER_NAME \
        --namespace DB_CLUSTER_NAMESPACE
    

    Substitua:

    • DB_CLUSTER_NAME: o nome do recurso DBCluster.
    • DB_CLUSTER_NAMESPACE: o namespace do recurso DBCluster.
  2. Conecte-se ao pod do banco de dados principal no banco de dados alloydbadmin e verifique a integridade do banco de dados:

    SELECT * FROM healthcheck;
    

    Verifique se o carimbo de data/hora da última verificação de integridade é recente e se as verificações de integridade são executadas nos intervalos esperados. Se a instância principal não estiver íntegra, inspecione o arquivo postgresql.log para determinar por que ela está falhando. Para mais informações sobre como buscar registros, consulte Resolver problemas do operador do AlloyDB Omni no Kubernetes.

Se você usar um grande número de clusters de banco de dados em um único cluster do Kubernetes ou se tiver clusters de banco de dados subprovisionados, as verificações de integridade de failover automático poderão expirar ou não se conectar. Se você receber um erro que começa com HealthCheckProber: health check for instance failed, consulte as correções recomendadas em Resolver problemas de recuperação de instâncias. Para reduzir ou evitar failovers automáticos, você também pode realizar as seguintes ações:

O cluster de banco de dados permanece travado em um estado de failover ou switchover

Durante um failover ou uma troca de alta disponibilidade (HA), o operador do AlloyDB Omni isola a antiga instância primária durante a fase StopPrimary renomeando os arquivos PG_VERSION como PG_VERSION.disabled no diretório de dados raiz em /pgdata/db/PG_VERSION.disabled e em cada subdiretório de banco de dados em /pgdata/db/base/OID/PG_VERSION.disabled. Se o failover ou a alternância falhar antes que a instância em espera seja promovida e a reversão automática não ocorrer ou falhar, a antiga instância primária permanecerá isolada e o recurso DBCluster permanecerá travado em uma fase de reversão em andamento ou com falha.

Versões afetadas

Operador do AlloyDB Omni 1.0.0 e versões mais recentes.

Sintomas

Quando esse problema ocorre, é possível observar os seguintes sintomas:

  • O campo status.phase do recurso DBCluster permanece em DBClusterFailoverInProgress, DBClusterSwitchoverInProgress, DBClusterFailoverRollbackFailed ou DBClusterSwitchoverRollbackFailed.
  • A condição HAReady no recurso DBCluster tem status: "False" com o motivo FailoverInProgress ou SwitchoverInProgress.
  • O recurso Failover (failovers.alloydbomni.dbadmin.goog) ou Switchover (switchovers.alloydbomni.dbadmin.goog) está no estado Failed ou Failed_RollbackFailed.
  • O campo status.internal.phase do recurso Failover ou Switchover permanece em uma fase anterior a PromoteStandby, como StopPrimary, ou permanece na fase PromoteStandby por uma hora ou mais sem promover a instância em espera.
  • O pod do banco de dados principal não inicia o PostgreSQL e registra um erro indicando que o arquivo PG_VERSION está ausente porque PG_VERSION foi renomeado como PG_VERSION.disabled em /pgdata/db/PG_VERSION.disabled e /pgdata/db/base/OID/PG_VERSION.disabled.
  • Se uma recuperação manual anterior tiver restaurado apenas o arquivo /pgdata/db/PG_VERSION de nível superior, deixando os arquivos PG_VERSION.disabled nos subdiretórios /pgdata/db/base/OID/, as operações pg_basebackup subsequentes em instâncias em espera vão falhar com o seguinte erro nos registros do PostgreSQL na instância principal:

    XX000:ERROR: [basebackup.c:1549] invalid segment number 0 in file "PG_VERSION.disabled"
    

Alternativa

Para remover manualmente o isolamento da antiga instância principal e recuperar o recurso DBCluster, siga estas etapas:

  1. Inspecione os recursos externos e internos Failover ou Switchover no namespace do cluster de banco de dados para verificar a fase deles e identificar as instâncias principal anterior (oldPrimary) e de espera de destino (newPrimary):

    kubectl get failovers.alloydbomni.dbadmin.goog,switchovers.alloydbomni.dbadmin.goog,failovers.alloydbomni.internal.dbadmin.goog,instanceswitchovers.alloydbomni.internal.dbadmin.goog \
        --namespace DB_CLUSTER_NAMESPACE \
        -o yaml
    

    Substitua DB_CLUSTER_NAMESPACE pelo namespace do recurso DBCluster.

    Confirme se status.internal.phase não ultrapassou PromoteStandby. Se o pod do banco de dados em espera estiver em execução, verifique se o PostgreSQL na instância em espera ainda está no modo de recuperação somente leitura:

    kubectl exec -c database STANDBY_POD_NAME \
        --namespace DB_CLUSTER_NAMESPACE -- \
        psql -U alloydbadmin -d alloydbadmin -c "SELECT pg_is_in_recovery();"
    

    Substitua STANDBY_POD_NAME pelo nome do pod do banco de dados em espera, formatado como al-STANDBY_INSTANCE_NAME-0, em que STANDBY_INSTANCE_NAME é o valor de status.internal.newPrimary.

    Confirme se a consulta retorna t (verdadeiro) ou se o pod do banco de dados em espera está interrompido. Depois de confirmar que a instância em espera não foi promovida, exclua o recurso Instance em espera para evitar que ele seja promovido durante a recuperação:

    kubectl delete instances.alloydbomni.internal.dbadmin.goog STANDBY_INSTANCE_NAME \
        --namespace DB_CLUSTER_NAMESPACE
    

    Substitua STANDBY_INSTANCE_NAME pelo nome do recurso Instance em espera do campo status.internal.newPrimary.

  2. Verifique o diretório de dados /pgdata/db no pod do banco de dados principal para arquivos PG_VERSION e PG_VERSION.disabled:

    kubectl exec -c database PRIMARY_POD_NAME \
        --namespace DB_CLUSTER_NAMESPACE -- \
        find /pgdata/db -type f -name "PG_VERSION*"
    

    Substitua PRIMARY_POD_NAME pelo nome do pod do banco de dados principal, formatado como al-PRIMARY_INSTANCE_NAME-0, em que PRIMARY_INSTANCE_NAME é o valor de status.internal.oldPrimary.

    Se nem PG_VERSION nem PG_VERSION.disabled existirem em /pgdata/db, o diretório de dados do banco de dados não será recuperável e precisará ser restaurado de um backup.

    Se houver arquivos PG_VERSION.disabled, restaure PG_VERSION no diretório de dados raiz em /pgdata/db/PG_VERSION.disabled e em cada subdiretório do banco de dados em /pgdata/db/base/OID/PG_VERSION.disabled. O comando a seguir renomeia cada arquivo PG_VERSION.disabled de volta para PG_VERSION ou remove o arquivo PG_VERSION.disabled se o arquivo PG_VERSION correspondente já tiver sido restaurado:

    kubectl exec -c database PRIMARY_POD_NAME \
        --namespace DB_CLUSTER_NAMESPACE -- \
        sh -c 'find /pgdata/db -type f -name "PG_VERSION.disabled" | while read -r f; do
          target="${f%.disabled}"
          if [ -f "$target" ]; then rm -f "$f"; else mv "$f" "$target"; fi
        done'
    
  3. Reinicie o serviço PostgreSQL no pod do banco de dados principal:

    kubectl exec -c database PRIMARY_POD_NAME \
        --namespace DB_CLUSTER_NAMESPACE -- \
        /scripts/supervisor/bin/supervisorctl.par \
        -c /scripts/supervisor/etc/supervisord.conf restart postgres
    
  4. Limpe o estado de failover ou de alternância com falha usando uma das seguintes opções:

    • Opção 1: excluir os recursos Failover ou Switchover e reiniciar os controladores do operador. Exclua os recursos Failover externos e internos e reinicie as implantações fleet-controller-manager e local-controller-manager no namespace alloydb-omni-system para liberar bloqueios na memória:

      kubectl delete failovers.alloydbomni.dbadmin.goog FAILOVER_NAME \
          --namespace DB_CLUSTER_NAMESPACE
      kubectl delete failovers.alloydbomni.internal.dbadmin.goog INTERNAL_FAILOVER_NAME \
          --namespace DB_CLUSTER_NAMESPACE
      kubectl rollout restart deployment/fleet-controller-manager deployment/local-controller-manager \
          --namespace alloydb-omni-system
      

      Substitua:

      • FAILOVER_NAME: o nome do recurso failovers.alloydbomni.dbadmin.goog.
      • INTERNAL_FAILOVER_NAME: o nome do recurso failovers.alloydbomni.internal.dbadmin.goog.

      Se uma alternância estiver travada em vez de um failover, exclua os recursos switchovers.alloydbomni.dbadmin.goog e instanceswitchovers.alloydbomni.internal.dbadmin.goog.

    • Opção 2: marcar os recursos Failover como revertidos. Essa opção se aplica apenas a recursos Failover travados. Se um recurso Switchover estiver travado, use a Opção 1. Edite o sub-recurso status nos recursos failovers.alloydbomni.dbadmin.goog e failovers.alloydbomni.internal.dbadmin.goog:

      kubectl edit failovers.alloydbomni.dbadmin.goog FAILOVER_NAME \
          --namespace DB_CLUSTER_NAMESPACE \
          --subresource=status
      kubectl edit failovers.alloydbomni.internal.dbadmin.goog INTERNAL_FAILOVER_NAME \
          --namespace DB_CLUSTER_NAMESPACE \
          --subresource=status
      

      Na seção status de cada recurso Failover, defina endTime como um carimbo de data/hora após createTime, defina internal.phase como RollbackSucceeded e defina state como Failed, conforme mostrado no exemplo a seguir:

      apiVersion: alloydbomni.dbadmin.goog/v1
      kind: Failover
      status:
        createTime: "2026-09-01T22:07:42Z"
        endTime: "2026-09-01T22:07:50Z"
        internal:
          attempt: 0
          lastPhaseChangeTime: "2026-09-01T22:07:39Z"
          newPrimary: 4274-dbcluster-sample
          newPrimaryZone: ""
          oldPrimary: dafd-dbcluster-sample
          phase: RollbackSucceeded
        observedGeneration: 2
        reconciled: true
        startTime: "2026-09-01T22:07:39Z"
        state: Failed
      
  5. Atualize o sub-recurso status do recurso DBCluster para limpar latestFailoverStatus e definir phase como DBClusterReconciling:

    kubectl patch dbclusters.alloydbomni.dbadmin.goog DB_CLUSTER_NAME \
        --namespace DB_CLUSTER_NAMESPACE \
        --subresource=status \
        --type=merge \
        --patch '{"status":{"latestFailoverStatus":null,"phase":"DBClusterReconciling"}}'
    

    Substitua DB_CLUSTER_NAME pelo nome do recurso DBCluster.

    Se a condição HAReady em status.conditions ainda impedir a reconciliação porque o campo reason está definido como FailoverInProgress ou SwitchoverInProgress, edite o subrecurso status do recurso DBCluster e remova a entrada de condição HAReady de status.conditions para que o operador do AlloyDB Omni a recrie durante a reconciliação ou defina o campo reason como um valor CamelCase válido não vazio, como ClusterReady:

    kubectl edit dbclusters.alloydbomni.dbadmin.goog DB_CLUSTER_NAME \
        --namespace DB_CLUSTER_NAMESPACE \
        --subresource=status
    
  6. Verifique se o operador do AlloyDB Omni reconcilia a instância em espera e retorna o recurso DBCluster para a fase DBClusterReady:

    kubectl get dbclusters.alloydbomni.dbadmin.goog DB_CLUSTER_NAME \
        --namespace DB_CLUSTER_NAMESPACE
    

Depurar problemas de memória

Estas seções descrevem como depurar problemas de memória.

Executar e gerar um heapdump

Ative esse recurso apenas para resolver problemas. Lembre-se de desativá-lo depois.

Para fazer um heapdump, siga estas etapas:

  1. Modifique a implantação do operador no namespace alloydb-omni-system com o nome fleet-controller-manager e local-controller-manager.
  2. Adicione o seguinte argumento ao pod --pprof-address=:8642 ou a qualquer outra porta disponível.
  3. Aguarde o pod do controlador reiniciar.
  4. Encaminhe a porta anterior. Exemplo:

    kubectl port-forward FLEET_CONTROLLER_MANAGER_POD_NAME -n alloydb-omni-system 8642:8642
    
  5. Em outro terminal, execute go tool pprof http://localhost:8642/debug/pprof/heap. Mude a porta para corresponder à anterior se você não usar 8642.

  6. Conecte-se ao endereço e execute comandos de solução de problemas. Por exemplo, top.

  7. Depois de concluir a solução de problemas, desfaça a etapa 1 removendo o argumento e aguardando a reinicialização do pod.

Determinar o número de recursos que o operador está monitorando

Para entender os recursos em uso, execute os seguintes comandos:

kubectl get backuprepositories -A  | wc -l
kubectl get failovers -A  | wc -l
kubectl get instancebackupplans -A  | wc -l
kubectl get instancebackups -A  | wc -l
kubectl get instancerestores -A  | wc -l
kubectl get instances -A  | wc -l
kubectl get instanceswitchovers -A  | wc -l
kubectl get lrojobs -A  | wc -l
kubectl get replicationconfigs -A  | wc -l
kubectl get sidecars -A  | wc -l
kubectl get deployments -A  | wc -l
kubectl get statefulsets -A  | wc -l
kubectl get certificates.cert-manager.io -A  | wc -l
kubectl get issuers.cert-manager.io -A  | wc -l
kubectl get configmaps -A  | wc -l
kubectl get persistentvolumeclaims -A  | wc -l
kubectl get persistentvolumes -A  | wc -l
kubectl get pods -A  | wc -l
kubectl get secrets -A  | wc -l
kubectl get services -A  | wc -l
kubectl get storageclasses.storage.k8s.io -A  | wc -l

Por exemplo, se o número de secrets for alto, isso pode levar a um erro de memória insuficiente (OOM).

kubectl get secrets -A | wc -l

Depuração avançada de alta disponibilidade

Esta seção faz referência a recursos que são implementações internas. Eles estão sujeitos a mudanças a qualquer momento e não têm compromissos de compatibilidade com versões anteriores. Aplique correções manuais apenas a problemas em bancos de dados que não são de produção. Essas etapas podem tornar o banco de dados irrecuperável.

A configuração de alta disponibilidade do AlloyDB Omni tem três fases:

  1. Configure a instância principal para receber uma conexão da instância de espera.
  2. Inicialize o modo de espera e conecte-o ao principal.
  3. Defina as configurações principais para tornar a conexão síncrona.

A etapa 2 geralmente é a mais lenta. Dependendo do tamanho do banco de dados, isso pode levar várias horas.

Cada instância de replicação precisa ter um replicationconfig anexado a ela. Exemplo:

kubectl get replicationconfigs.alloydbomni.internal.dbadmin.goog -n DB_CLUSTER_NAMESPACE

Exemplo de saída:

NAME                 PARENT     TYPE       ROLE         READY   HEALTHY   SYNC_U   SYNC_D   SLOT_LOG   SLOT_REPLAY
cd58-adb--58ea-adb   cd58-adb   Physical   Upstream     True    True      true
ds-58ea-adb          58ea-adb   Physical   Downstream   True    True               true

A especificação da configuração de replicação indica as configurações pretendidas, enquanto o status reflete o estado real lido no banco de dados. Se houver uma incompatibilidade entre a especificação e o status, o controlador ainda estará tentando aplicar a alteração ou haverá algum erro que impede a aplicação da alteração. Isso seria indicado nos campos de status.

Jobs em espera

Deve haver dois conjuntos de jobs internos que rastreiam o fluxo de trabalho de um modo de espera:

  • createstandbyjobs.alloydbomni.internal.dbadmin.goog
  • deletestandbyjobs.alloydbomni.internal.dbadmin.goog

Se a configuração parecer travada, confira os jobs relacionados ao cluster de banco de dados (DBC). O job pode ter mensagens de erro que explicam o estado da configuração. Os jobs são limpos automaticamente algum tempo depois de serem concluídos. Por isso, talvez você não veja nenhum job se nenhum estiver em andamento.

kubectl get createstandbyjobs.alloydbomni.internal.dbadmin.goog -n DB_CLUSTER_NAMESPACE

O resultado será o seguinte:

apiVersion: alloydbomni.dbadmin.gdc.goog/v1
  kind: CreateStandbyJob
  metadata:
    creationTimestamp: "2024-11-05T03:34:26Z"
    finalizers:
    -   createstandbyjob.dbadmin.goog/finalizer
    generation: 1804
    labels:
      dbs.internal.dbadmin.goog/dbc: foo-ha-alloydb1-clone1
    name: foo-ha-alloydb1-clone1--ac00-foo-ha-alloydb1-clone1--6036-foo-ha-alloydb1-clone1-1730777666
    namespace: db
    resourceVersion: "11819071"
    uid: 1f24cedf-b326-422f-9405-c96c8720cd90
  spec:
    attempt: 3
    cleanup: false
    currentStep: SetupSynchronous
    currentStepTime: "2024-11-05T03:45:31Z"
    metadata:
      dbc: foo-ha-alloydb1-clone1
      primaryInstance: ac00-foo-ha-alloydb1-clone1
      retryError: 'etcdserver: leader changed'
      standbyInstance: 6036-foo-ha-alloydb1-clone1
    requeueTime: "2024-11-05T18:33:03Z"
    startTime: "2024-11-05T03:36:56Z"

Verificação principal

A primeira coisa a verificar é se a instância principal está configurada corretamente. Deve haver um perfil de replicação para cada espera. Se isSynchronous for verdadeiro na especificação e no status, a configuração estará concluída. Se isSynchronous for falso na especificação e no status, ele ainda não terá atingido a etapa 3. Confira os jobs em espera para ver se há algum em execução e se eles têm mensagens de erro.

  replication:
    profiles:
    -   isActive: true
      isSynchronous: true
      name: ha:4c82-dbcluster-sample::d85d-dbcluster-sample
      password:
        name: ha-rep-pw-dbcluster-sample
        namespace: default
      passwordResourceVersion: "896080"
      role: Upstream
      type: Physical
      username: alloydbreplica

Verifique se a anotação disableHealthcheck é falsa. Ele deve ser desativado apenas durante um failover ou switchover.

apiVersion: alloydbomni.internal.dbadmin.goog/v1
kind: Instance
metadata:
  annotations:
    dbs.internal.dbadmin.goog/consecutiveHealthcheckFailures: "0"
    dbs.internal.dbadmin.goog/disableHealthcheck: "false"
    dr-secondary: "false"
    forceReconcile: "1730414498"

Consultas

Para verificar se os recursos no pod do banco de dados estão configurados corretamente, faça login no banco de dados como o usuário administrador alloydbadmin. Em seguida, execute as seguintes consultas:

Slot de replicação

\x on
select * from pg_replication_slots;
-[ RECORD 1 ]-------+---------------------------------------------
slot_name           | d85d_dbcluster_sample
plugin              |
slot_type           | physical
datoid              |
database            |
temporary           | f
active              | t
active_pid          | 250
xmin                | 16318
catalog_xmin        |
restart_lsn         | 0/CA657F0
confirmed_flush_lsn |
wal_status          | reserved
safe_wal_size       |
two_phase           | f

Um bom estado é a presença de um slot de replicação com o mesmo nome da instância em espera. A ausência de um slot de replicação indica que a primeira etapa de configuração não foi concluída com sucesso.

Se active não for t (verdadeiro), isso significa que o modo de espera não está se conectando por algum motivo (rede, modo de espera não finalizando a configuração etc.) e a depuração provavelmente precisará continuar no modo de espera.

Estatísticas de replicação

\x on
select * from pg_stat_replication;
-[ RECORD 1 ]----+----------------------------------------------------------------
pid              | 250
usesysid         | 16385
usename          | alloydbreplica
application_name | d85d_dbcluster_sample
client_addr      | 10.54.79.196
client_hostname  | gke-samwise-default-pool-afaf152d-8197.us-central1-a.c.foo
client_port      | 24914
backend_start    | 2024-10-30 21:44:26.408261+00
backend_xmin     |
state            | streaming
sent_lsn         | 0/CA64DA8
write_lsn        | 0/CA64DA8
flush_lsn        | 0/CA64DA8
replay_lsn       | 0/CA64DA8
write_lag        |
flush_lag        |
replay_lag       |
sync_priority    | 2
sync_state       | sync
reply_time       | 2024-11-04 22:08:04.370838+00

Se não houver, significa que não há uma conexão ativa. sync_state precisa ser sync. Se não for sync, isso significa que a etapa final da configuração não foi concluída. Confira os registros / jobs para mais detalhes.

Verificação de espera

O modo de espera precisa ter um perfil de replicação que corresponda ao mesmo perfil do principal:

  replication:
    profiles:
    -   host: 10.54.79.210
      isActive: true
      isSynchronous: true
      name: ha:4c82-dbcluster-sample::d85d-dbcluster-sample
      passwordResourceVersion: "896080"
      port: 5432
      role: Downstream
      type: Physical
      username: alloydbreplica

Se não houver conexão entre a instância de espera e a principal, há duas possibilidades comuns:

  1. A configuração do modo de espera ainda está em andamento.
  2. O modo de espera está recebendo um erro ao configurar ou tentar se conectar.

Para verificar se a opção 1 está acontecendo, acesse os registros do pod do banco de dados e procure log statements chamados dbdaemon/setupPhysicalReplicationDownstream. Veja a seguir exemplos de registros de configuração bem-sucedidos:

I1104 22:42:42.604871     103 replication.go:107] "dbdaemon/setupPhysicalReplicationDownstream: begin setup" log_name="agent" project_ns="default" dbcluster="dbcluster-sample"
2024-11-04 22:42:42,605 INFO waiting for postgres to stop
2024-11-04 22:42:43,566 INFO stopped: postgres (exit status 0)
I1104 22:42:43.567590     103 replication.go:131] "dbdaemon/setupPhysicalReplicationDownstream: about to call pg_basebackup" log_name="agent" project_ns="default" dbcluster="dbcluster-sample" cmd=["-h","10.54.79.210","-D","/mnt/disks/pgsql/pg_basebackup_data","-U","alloydbreplica","-v","-P","-p","5432","-w","-c","fast"]
I1104 22:42:44.206403     103 replication.go:139] "dbdaemon/setupPhysicalReplicationDownstream: pg_basebackup finished" log_name="agent" project_ns="default" dbcluster="dbcluster-sample"
I1104 22:42:44.206440     103 replication.go:141] "dbdaemon/setupPhysicalReplicationDownstream: replacing data directory with pg_basebackup data directory" log_name="agent" project_ns="default" dbcluster="dbcluster-sample"
I1104 22:42:44.244749     103 replication.go:148] "dbdaemon/setupPhysicalReplicationDownstream: replaced data directory with pg_basebackup data directory" log_name="agent" project_ns="default" dbcluster="dbcluster-sample"
I1104 22:42:44.244783     103 replication.go:150] "dbdaemon/setupPhysicalReplicationDownstream: Creating config files" log_name="agent" project_ns="default" dbcluster="dbcluster-sample"
I1104 22:42:44.251565     103 replication.go:155] "dbdaemon/setupPhysicalReplicationDownstream: removing postgresql config file for log archiving" log_name="agent" project_ns="default" dbcluster="dbcluster-sample"
I1104 22:42:44.251621     103 replication.go:160] "dbdaemon/setupPhysicalReplicationDownstream: removing postgresql auto config file" log_name="agent" project_ns="default" dbcluster="dbcluster-sample"
I1104 22:42:44.251689     103 replication.go:165] "dbdaemon/setupPhysicalReplicationDownstream: Successfully wrote to config file" log_name="agent" project_ns="default" dbcluster="dbcluster-sample"
2024-11-04 22:42:44,256 INFO spawned: 'postgres' with pid 271
2024-11-04 22:42:45,469 INFO success: postgres entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)
I1104 22:42:45.469838     103 replication.go:174] "dbdaemon/setupPhysicalReplicationDownstream: backup replication configuration after changing replication config" log_name="agent" project_ns="default" dbcluster="dbcluster-sample"
I1104 22:42:45.476732     103 replication.go:179] "dbdaemon/setupPhysicalReplicationDownstream: finished standby setup" log_name="agent" project_ns="default" dbcluster="dbcluster-sample"

Se houver um erro de conexão, verifique os registros do pod do banco de dados e o arquivo de registro no banco de dados em /obs/diagnostic/postgresql.log para ver qual é o erro ao tentar se conectar. Um erro comum é a falta de conectividade de rede entre o standby e o primário.

Correções manuais

A maneira mais fácil de corrigir problemas de alta disponibilidade é desativar e reativar a alta disponibilidade definindo numberOfStandbys como 0 e, em seguida, redefinindo-o para o número desejado. Se as instâncias em espera estiverem presas sendo desativadas, siga estas etapas para redefinir manualmente a configuração de alta disponibilidade para que fique vazia:

  1. Exclua manualmente as instâncias em espera.
  2. Conecte-se ao banco de dados principal. Consulte os slots de replicação atuais e exclua os slots de replicação de espera que você quer excluir:

    select pg_drop_replication_slot('REPLICATION_SLOT_NAME');
    
  3. Exclua todos os perfis de replicação da instância principal que você quer excluir.

Se uma instância não tiver sido reconciliada recentemente, será possível editar o valor da anotação forceReconcile. Defina como qualquer valor numérico, que é o carimbo de data/hora da última vez que a anotação foi atualizada. O único propósito dessa anotação é fornecer um campo que possa ser atualizado para forçar uma nova reconciliação.

apiVersion: alloydbomni.internal.dbadmin.goog/v1
kind: Instance
metadata:
  annotations:
    dbs.internal.dbadmin.goog/consecutiveHealthcheckFailures: "0"
    dbs.internal.dbadmin.goog/disableHealthcheck: "false"
    dr-secondary: "false"
    forceReconcile: "1730414498"

Se um recurso DBCluster permanecer travado em DBClusterFailoverInProgress, DBClusterSwitchoverInProgress, DBClusterFailoverRollbackFailed ou DBClusterSwitchoverRollbackFailed porque a instância principal está isolada com arquivos PG_VERSION.disabled, consulte O cluster de banco de dados permanece travado em um estado de failover ou alternância.

Coletar registros de auditoria e do mecanismo de banco de dados

Os registros do mecanismo de banco de dados e registros de auditoria estão disponíveis como arquivos no pod do banco de dados (exige acesso raiz):

  • obs/diagnostic/postgresql.log
  • obs/diagnostic/postgresql.audit
DB_POD=$(kubectl get pod -l alloydbomni.internal.dbadmin.goog/dbcluster=DB_CLUSTER_NAME,alloydbomni.internal.dbadmin.goog/task-type=database -n DB_CLUSTER_NAMESPACE -o jsonpath='{.items[0].metadata.name}')
kubectl exec -c database -n DB_CLUSTER_NAMESPACE ${DB_POD} -it -- /bin/bash

Quando estiver conectado ao contêiner do banco de dados:

ls -l /obs/diagnostic/

Exemplo de saída:

drwx--S--- 2 postgres postgres    4096 Aug 13 10:22 archive
-rw------- 1 postgres postgres  256050 Aug 13 13:25 postgresql.internal
-rw------- 1 postgres postgres 1594799 Aug 13 13:25 postgresql.log

Coletar métricas de banco de dados e de pods de banco de dados

O operador do AlloyDB Omni fornece um conjunto de métricas básicas para o mecanismo do AlloyDB Omni e o pod que o hospeda. As métricas estão disponíveis como endpoints do Prometheus na porta 9187. Para acessar os endpoints, é necessário identificar o nome do pod do banco de dados usando o rótulo DBCluster e iniciar o encaminhamento de portas da seguinte maneira:

DB_POD=$(kubectl get pod -l alloydbomni.internal.dbadmin.goog/dbcluster=DB_CLUSTER_NAME -n DB_CLUSTER_NAMESPACE -o jsonpath='{.items[0].metadata.name}')
kubectl port-forward -n DB_CLUSTER_NAMESPACE ${DB_POD} 9187:9187

Acessar métricas de pods do banco de dados

Em outro terminal:

curl http://localhost:9187/metrics | grep HELP

Para mais informações sobre monitoramento, consulte Monitorar o AlloyDB Omni.

Também é possível configurar o Prometheus para coletar as métricas no cluster do Kubernetes. Consulte a configuração de descoberta de serviços do Kubernetes do Prometheus para mais detalhes.