Esegui il deployment e gestisci AlloyDB Omni su Kubernetes (GKE o cluster Bring Your Own)

1. Introduzione

In questo codelab imparerai a installare l'operatore AlloyDB Omni Kubernetes (l'orchestratore di container) su un cluster Google Kubernetes Engine (GKE) Autopilot o sul tuo cluster Kubernetes e a gestire i workflow completi del ciclo di vita del database end-to-end e i Critical User Journey (CUJ).

AlloyDB Omni è una versione scaricabile di AlloyDB progettata per essere eseguita ovunque, dagli ambienti on-premise a Google Cloud o all'edge computing. Con l'orchestratore di container, AlloyDB Omni automatizza l'alta affidabilità, i failover automatici, la riparazione automatica, la manutenzione in sequenza con tempi di inattività minimi, il pooling delle connessioni, i backup automatici e il recupero point-in-time.

Scegli il percorso dell'ambiente

Puoi completare questo codelab utilizzando uno dei seguenti due percorsi:

  1. Percorso 1: hai un account Google Cloud (GKE Autopilot) - Esegui il provisioning di un cluster GKE Autopilot completamente gestito utilizzando Google Cloud Shell o la console Google Cloud.
  2. Percorso 2: non hai un account Google Cloud (Bring Your Own Kubernetes Cluster) - Utilizza un cluster Kubernetes esistente (v1.21 o successiva) con kubectl e helm configurati sulla tua workstation. Non è richiesto un account Google Cloud o l'interfaccia a riga di comando gcloud.

Prerequisiti

  • Conoscenza di base dei concetti di Kubernetes (kubectl, Helm, definizioni di risorse personalizzate).
  • Per il percorso 1 (Google Cloud / GKE Autopilot):
    • Un progetto Google Cloud con la fatturazione abilitata.
    • Accesso a Google Cloud Shell o a una workstation configurata con gcloud, kubectl e helm.
  • Per il percorso 2 (Bring Your Own Kubernetes Cluster):
    • Un cluster Kubernetes che esegue la versione 1.21 o successive con un StorageClass predefinito per il provisioning dinamico di PersistentVolume.
    • Nodi worker che eseguono il kernel Linux 4.18 o versioni successive con cgroup v2 abilitato (x86-64/AMD64) e almeno 8 vCPU e 24 GiB di RAM allocabile nel cluster.
    • Una workstation configurata con kubectl e helm connessa al tuo cluster.

Cosa imparerai a fare

  • Come eseguire il provisioning di un cluster GKE Autopilot (percorso 1) o convalidare un cluster Kubernetes esistente (percorso 2).
  • Come installare cert-manager e l'operatore AlloyDB Omni Kubernetes tramite Helm.
  • Come eseguire il deployment di AlloyDB Omni DBCluster a istanza singola.
  • Come scalare l'alta affidabilità (HA) con standby sincroni e attivare la funzionalità di standby di sola lettura.
  • Come configurare i backup automatici pianificati nello spazio di archiviazione del repository locale (e facoltativamente in Google Cloud Storage nel percorso 1).
  • Come eseguire backup on demand e verificare il ripristino dei dati a uno stato precedente.
  • Come eseguire il recupero point-in-time (PITR) in un nuovo cluster di database clonato.
  • Come eseguire il deployment del pooling delle connessioni PgBouncer per la scalabilità delle connessioni client.
  • Come eseguire il deployment di pgAdmin4 per gestire ed eseguire query sul database visivamente.
  • Come eseguire la manutenzione con tempi di inattività ridotti (LDTM) per la scalabilità delle risorse di CPU e memoria.

Che cosa ti serve

  • Percorso 1: Google Cloud Shell con utilità gcloud, kubectl e helm preinstallate.
  • Percorso 2: un terminale con kubectl e helm connesso al tuo cluster Kubernetes.
  • Per la documentazione di riferimento, consulta la guida ufficiale al deployment di AlloyDB Omni.

2. Configurazione e requisiti

Scegli il Percorso 1 se utilizzi un account Google Cloud per creare un cluster GKE Autopilot o il Percorso 2 se utilizzi il tuo cluster Kubernetes senza un account Google Cloud.

Percorso 1: configurazione del progetto Google Cloud (GKE Autopilot)

  1. Nella console Google Cloud, seleziona o crea un progetto Google Cloud.
  2. Verifica che la fatturazione sia abilitata per il tuo progetto. Scopri come verificare lo stato della fatturazione.
  3. Apri Google Cloud Shell facendo clic sull'icona Attiva Cloud Shell nell'angolo in alto a destra della console Google Cloud o visitando la pagina shell.cloud.google.com. Cloud Shell esegue il provisioning di un ambiente di computing caricato con gcloud, kubectl e helm.
  4. Imposta l'ID progetto come variabile di ambiente e configura 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. Abilita le API Google Cloud richieste per GKE e Cloud Storage:
gcloud services enable container.googleapis.com \
    storage.googleapis.com \
    cloudresourcemanager.googleapis.com

Percorso 2: configurazione del cluster Bring Your Own (senza account Google Cloud)

Se non hai un account Google Cloud e utilizzi il tuo cluster Kubernetes, verifica i seguenti prerequisiti dal terminale prima di continuare:

  1. Verifica che kubectl e helm possano raggiungere il tuo cluster e che i tuoi nodi siano Ready:
kubectl get nodes
helm version
  1. Verifica che il cluster abbia un StorageClass predefinito contrassegnato come (default). I manifest DBCluster e BackupPlan eseguono il provisioning dinamico di PersistentVolumeClaim utilizzando l'oggetto StorageClass predefinito del cluster:
kubectl get storageclass

Se nessun StorageClass è contrassegnato come (default), designane uno come predefinito prima di procedere:

kubectl patch storageclass <YOUR_STORAGE_CLASS_NAME> \
  -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'
  1. Verifica che i nodi worker soddisfino i requisiti hardware e del sistema operativo dell'operatore:
    • Sistema operativo e kernel: kernel Linux 4.18 o versioni successive con cgroup v2 abilitato sui nodi x86-64/AMD64.
    • Capacità del cluster: almeno 8 vCPU e 24 GiB di memoria allocabile nei nodi worker per eseguire contemporaneamente le istanze di database ad alta affidabilità (scalate a 2 vCPU e 8 GiB ciascuna nel passaggio 12), l'istanza clonata PITR, PgBouncer e pgAdmin4.
    • Accesso alla rete: accesso a internet in uscita per eseguire il pull delle immagini container da gcr.io/alloydb-omni, quay.io/jetstack e docker.io.

3. Esegui il provisioning o connettiti al tuo cluster Kubernetes

Se segui il Percorso 1 (account Google Cloud), GKE Autopilot fornisce una modalità Kubernetes completamente gestita e automatizzata in cui Google gestisce l'infrastruttura del cluster, il provisioning dei nodi e la scalabilità automatica. Puoi creare il cluster GKE Autopilot utilizzando Google Cloud CLI o la console Google Cloud.

Opzione A: crea un cluster GKE Autopilot tramite l'interfaccia a riga di comando (percorso 1)

Esegui questo comando gcloud in Cloud Shell:

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

Opzione B: crea un cluster GKE Autopilot tramite la console (percorso 1)

  1. Apri Kubernetes Engine nella console Google Cloud.
  2. Nel riquadro di navigazione a sinistra, fai clic su Cluster.
  3. Fai clic su Crea.
  4. Nella sezione GKE Autopilot, fai clic su Configura.
  5. Specifica il nome del cluster (ad esempio omni-autopilot-cluster) e seleziona la regione che preferisci (us-central1).
  6. Fai clic su Crea.

Verifica la connettività del cluster (percorso 1 e percorso 2)

Se hai creato un cluster GKE Autopilot nel Percorso 1, configura le tue credenziali kubectl:

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

Per Percorso 1 e Percorso 2, verifica la connettività al cluster Kubernetes:

kubectl get nodes

4. Installa i prerequisiti dell'operatore e l'operatore

L'operatore AlloyDB Omni Kubernetes richiede cert-manager per la gestione dei certificati TLS del webhook di ammissione.

1. Installa cert-manager

Installa cert-manager utilizzando il relativo grafico Helm ufficiale:

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

Verifica che i pod cert-manager siano in esecuzione:

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

2. Installa l'operatore AlloyDB Omni

Esegui il deployment dell'operatore AlloyDB Omni Kubernetes nello spazio dei nomi alloydb-omni-system utilizzando 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

Verifica che i pod dell'operatore siano integri e in esecuzione:

kubectl get pods -n alloydb-omni-system

5. Crea un cluster di database a istanza singola

In questo passaggio, creerai uno spazio dei nomi dell'applicazione dedicato ed eseguirai il deployment di AlloyDB Omni DBCluster a istanza singola.

1. Crea lo spazio dei nomi e il secret delle credenziali di amministratore

Crea uno spazio dei nomi omni-demo per i workload del database:

kubectl create namespace omni-demo

Crea un secret di Kubernetes che memorizzi la password per l'utente amministratore del database postgres predefinito:

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. Esegui il deployment di DBCluster a istanza singola

Crea un manifest DBCluster a istanza singola:

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. Verifica l'idoneità del cluster

Monitora lo stato del cluster finché DBCLUSTERPHASE non raggiunge DBClusterReady. Il provisioning iniziale può richiedere diversi minuti: l'operatore deve creare il volume permanente ed eseguire il pull dell'immagine del database. Inoltre, su GKE Autopilot potrebbe essere necessario eseguire prima il provisioning di un nuovo nodo.

kubectl get dbcluster -n omni-demo -w

Premi Ctrl+C per uscire dalla modalità di visualizzazione quando DBCLUSTERPHASE raggiunge DBClusterReady.

Esempio di output:

NAME   PRIMARYENDPOINT   PRIMARYPHASE   DBCLUSTERPHASE   HAREADYSTATUS   HAREADYREASON
adbo   10.128.0.45       Ready          DBClusterReady

Prendi nota dell'indirizzo IP PRIMARYENDPOINT, che è il ClusterIP del servizio Kubernetes di lettura e scrittura al-adbo-rw-ilb. AlloyDB Omni rimane in ascolto sulla porta PostgreSQL predefinita 5432.

Esamina le risorse che l'operatore ha riconciliato dal singolo manifest DBCluster: il pod del database, l'oggetto PersistentVolumeClaim DataDisk e il servizio al-adbo-rw-ilb:

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

6. Esegui l'upgrade all'alta affidabilità (HA) e abilita lo standby di sola lettura

AlloyDB Omni offre alta affidabilità (HA) integrata con replica in streaming, monitoraggio automatico dell'integrità, failover automatico e gestione delle repliche di lettura.

1. Abilita l'alta affidabilità e la funzionalità di replica di lettura

Aggiorna la specifica DBCluster per configurare un'istanza in standby e attivare il routing in standby di sola lettura:

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

2. Verifica la stabilizzazione dell'alta affidabilità

Attendi che l'istanza in standby venga sottoposta a provisioning e raggiunga una replica di streaming integra (HAREADYSTATUS raggiunge True e HAREADYREASON raggiunge Ready), quindi premi Ctrl+C per uscire dalla modalità di visualizzazione:

kubectl get dbcluster adbo -n omni-demo -w

Controlla la condizione di stato HAReady:

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

Verifica che siano pubblicati sia gli endpoint di lettura/scrittura sia quelli di sola lettura:

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

Esempio di output:

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

L'endpoint di lettura/scrittura (servizio al-adbo-rw-ilb) esegue il routing al database primario, mentre l'endpoint di sola lettura (servizio al-adbo-ro-ilb) distribuisce le query di lettura tra le istanze in standby.

7. Configura i piani di backup automatico (locali e GCS)

AlloyDB Omni fornisce backup fisici e archiviazione WAL tramite la risorsa personalizzata BackupPlan. Puoi configurare la conservazione dei backup, le pianificazioni cron automatiche e le destinazioni dei backup (volumi permanenti locali o Google Cloud Storage).

1. Crea piano di backup locale

Crea un BackupPlan che scrive i backup nello spazio di archiviazione Kubernetes locale collegato alle istanze del database:

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

Verifica che il BackupPlan locale sia pronto:

kubectl get backupplan backupplan-local -n omni-demo

Attendi fino a quando PHASE non segnala Ready e NEXTBACKUPTIME non viene pianificato.

2. Crea un piano di backup GCS (percorso 1: solo Google Cloud, facoltativo)

Per archiviare i backup esternamente in un bucket Google Cloud Storage, crea un bucket GCS, configura un secret della chiave del service account e applica un BackupPlan cloud.

  1. Crea un bucket Cloud Storage:
export BUCKET_NAME="${PROJECT_ID}-omni-backups"
gcloud storage buckets create gs://${BUCKET_NAME} --location=${REGION}
  1. Crea un service account con autorizzazioni amministrative Storage Object Admin e crea una chiave per questo account:

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. Crea il secret nello spazio dei nomi 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. Applica il manifest GCS BackupPlan. Il campo key è la cartella nel bucket in cui l'operatore scrive i backup. Deve iniziare con /.
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

Verifica lo stato del BackupPlan di GCS:

kubectl get backupplan backupplan-gcs -n omni-demo

Attendi fino a quando PHASE non segnala Ready e NEXTBACKUPTIME non viene pianificato.

8. Inserisci i dati, attiva il backup e testa il ripristino

In questo passaggio, inserirai i dati iniziali nel database primario, attiverai un backup manuale on demand, aggiungerai i dati successivi ed eseguirai il ripristino dal backup per dimostrare il rollback dei dati.

1. Populate Initial Data

Esegui un pod client PostgreSQL temporaneo per connetterti al database tramite il relativo servizio di lettura e scrittura al-adbo-rw-ilb come utente 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 viene richiesta la password, inserisci ChangeMe123. Questa è la password che hai codificato in base64 nel secret db-pw-adbo nel passaggio 5.

2. Attiva un backup on demand

Crea una risorsa personalizzata Backup manuale che faccia riferimento al tuo BackupPlan locale:

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

Monitora l'avanzamento del backup:

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

Attendi fino a quando PHASE non passa a Succeeded.

3. Modifica i dati (aggiungi nuovi record)

Inserisci record aggiuntivi dopo il 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;
  "

Il database ora contiene 4 righe.

4. Ripristina da backup

Attiva un ripristino dello stato acquisito in 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

Monitora l'operazione di ripristino:

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

Attendi finché PHASE non raggiunge ProvisionSucceeded e verifica che DBCluster torni a DBClusterReady:

kubectl get dbcluster adbo -n omni-demo -w

5. Verifica lo stato dei dati ripristinati

Esegui una query sulla tabella customers per verificare che esistano solo i record precedenti al 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 "
    SELECT * FROM customers;
  "

L'output conferma che sono presenti solo 2 righe (Alpha Co e Beta LLC), verificando che il database sia stato ripristinato allo stato esatto del backup.

9. Recupero point-in-time (PITR) in un database clonato

Il recupero point-in-time (PITR) consente di ripristinare un database in un secondo arbitrario all'interno della finestra di recupero utilizzando i backup di base e i log del flusso WAL, eseguendo il provisioning dei dati ripristinati in un nuovo cluster di database clonato.

Poiché l'operatore archivia continuamente il Write-Ahead Log (WAL), il PITR consente di eseguire il recupero da errori umani o dell'applicazione accidentali, ad esempio un DELETE o un DROP TABLE involontario alle 14:15:00, clonando il database al secondo esatto prima che si verificasse l'errore (14:14:59), senza toccare il cluster originale.

1. Registra il timestamp corrente e modifica i dati

Recupera il timestamp UTC corrente:

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

Inserisci un record di test che rappresenti una modifica indesiderata dopo questo timestamp:

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. Esegui il recupero point-in-time

Applica la risorsa personalizzata 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

Monitora l'operazione di ripristino finché PHASE non raggiunge ProvisionSucceeded:

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

3. Verifica il database clonato

Al termine del ripristino, attendi che il nuovo DBCluster clonato raggiunga DBClusterReady (premi Ctrl+C per uscire dalla modalità di controllo):

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

Esegui una query sul database clonato adbo-cloned tramite il relativo servizio di lettura e scrittura 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;
  "

Tieni presente che Unwanted Record Post-Timestamp non è presente nel cluster clonato, a dimostrazione del recupero accurato nel momento esatto del target.

10. Esegui il deployment del pooler di connessioni PgBouncer

Il pool di connessioni riduce l'overhead della memoria del database e la latenza della connessione. L'operatore gestisce le istanze PgBouncer in modo nativo tramite la risorsa personalizzata PgBouncer.

PostgreSQL esegue il fork di un processo del sistema operativo separato per ogni connessione client, quindi centinaia di connessioni simultanee da servizi web, microservizi o agenti AI possono esaurire la memoria del database. PgBouncer si trova davanti al database e multiplexa molte connessioni client di breve durata (fino a max_client_conn) in un piccolo pool di connessioni server PostgreSQL di lunga durata (default_pool_size per coppia utente/database, con un limite di max_db_connections).

1. Esegui il deployment di PgBouncer

Esegui il deployment di un pooler PgBouncer con 2 repliche collegato al 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. Verifica lo stato di PgBouncer

Controlla lo stato di PgBouncer finché PHASE non è Ready:

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

Controlla i pod e il servizio PgBouncer in esecuzione:

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

3. Connettiti tramite PgBouncer

Connetti un client tramite il servizio PgBouncer sulla 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;
  "

PgBouncer invia la query senza problemi al database AlloyDB Omni principale.

11. Esegui il deployment di pgAdmin4 per accedere al database

Puoi eseguire pgAdmin4 direttamente all'interno del cluster Kubernetes per fornire una console di amministrazione basata sul web per eseguire query, gestire e ispezionare AlloyDB Omni.

1. Installa pgAdmin4 tramite Helm

Installa pgadmin4 nello spazio dei nomi 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"

Questo grafico assegna alle risorse Kubernetes il nome pgadmin4 (Deployment, Service, PersistentVolumeClaim) e alle etichette dei pod il nome app=pgadmin4, indipendentemente dal nome della release Helm (my-pgadmin).

Verifica che il pod pgAdmin4 sia in esecuzione:

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

2. Forward Port and Access Web UI

Esegui il port forwarding di pgAdmin4 al tuo ambiente locale o a Cloud Shell:

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

kubectl port-forward continua a essere eseguito in primo piano finché utilizzi l'UI web di pgAdmin4. Apri un secondo terminale (o una nuova scheda di Cloud Shell) per altri comandi e premi Ctrl+C in questo terminale quando è tutto pronto per passare al passaggio successivo.

Apri l'interfaccia web di pgAdmin4:

  • Percorso 1 (Google Cloud Shell): fai clic sul pulsante Anteprima web nel menu in alto a destra, seleziona Cambia porta, inserisci 5050 e fai clic su Cambia e visualizza l'anteprima.
  • Percorso 2 (workstation locale): apri http://localhost:5050 nel browser mentre è in esecuzione il comando kubectl port-forward.

Accedi utilizzando:

  • Email: admin@example.com
  • Password: AdminPassword123

3. Registra AlloyDB Omni in pgAdmin4

  1. In pgAdmin4, fai clic con il tasto destro del mouse su Server > Registra > Server….
  2. Nella scheda Generale:
    • Nome: AlloyDB Omni Primary
  3. Nella scheda Connessione:
    • Nome host/indirizzo: al-adbo-rw-ilb.omni-demo.svc.cluster.local (o al-omni-pgbouncer-pgb-svc.omni-demo.svc.cluster.local per PgBouncer)
    • Porta: 5432 (o 6432 per PgBouncer)
    • Database di manutenzione: postgres
    • Nome utente: postgres
    • Password: ChangeMe123
  4. Fai clic su Salva e verifica la sessione e le tabelle del database attive.

12. Scala la CPU e la memoria con la manutenzione con tempi di inattività ridotti (LDTM)

Quando si esegue lo scale up di calcolo e memoria su un database di produzione, gli aggiornamenti tradizionali causano interruzioni del riavvio del database. AlloyDB Omni fornisce la manutenzione con tempi di inattività ridotti (LDTM) per eseguire gli aggiornamenti in sequenza tramite le repliche con un'interruzione minima dell'applicazione.

1. Abilita l'annotazione LDTM

Annota il DBCluster per abilitare LDTM per gli aggiornamenti:

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

2. Scala le risorse di CPU e memoria

Aggiorna le risorse principali da cpu: 1, memory: 4Gi a cpu: 2, memory: 8Gi:

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

3. Monitora l'avanzamento della scalabilità di LDTM

Monitora l'aggiornamento in sequenza e le condizioni di passaggio da standby a principale:

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

Osserva i pod che vengono aggiornati gradualmente:

kubectl get pods -n omni-demo -w

LDTM prepara prima lo standby aggiornato, verifica la replica in streaming, esegue un cambio rapido e aggiorna l'istanza rimanente senza interruzioni del servizio.

Verifica l'allocazione delle risorse aggiornata:

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

13. Esegui la pulizia delle risorse

Per liberare la capacità del cluster ed evitare addebiti non necessari sul tuo account Google Cloud, esegui la pulizia delle risorse di cui è stato eseguito il provisioning durante questo codelab.

Se esegui la pulizia in una nuova sessione del terminale (Percorso 1), le variabili di ambiente dei passaggi precedenti non sono più impostate. Esportale di nuovo con gli stessi valori utilizzati in precedenza:

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. Elimina i workload del database (percorso 1 e percorso 2)

Contrassegna entrambi i cluster come eliminati per superare i controlli del webhook di ammissione, attendi che l'operatore rimuova le risorse DBCluster, quindi elimina lo spazio dei nomi:

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 hai utilizzato il tuo cluster Kubernetes (Percorso 2) e vuoi anche rimuovere l'operatore AlloyDB Omni e 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. Elimina il bucket GCS e il service account IAM (solo percorso 1)

Se hai creato il bucket Google Cloud Storage e il service account nel Percorso 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. Elimina il cluster GKE (solo percorso 1)

Se hai eseguito il provisioning di un cluster GKE Autopilot nel Percorso 1:

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

14. Complimenti

Complimenti! Hai completato il codelab su AlloyDB Omni su Kubernetes.

Argomenti trattati

  • Aver eseguito il provisioning di un cluster GKE Autopilot (percorso 1) o preparato un cluster Kubernetes esistente (percorso 2).
  • Deployment di cert-manager e dell'operatore AlloyDB Omni Kubernetes tramite Helm.
  • È stato eseguito il deployment di un'istanza singola di AlloyDB Omni DBCluster.
  • È stato eseguito l'upgrade del cluster ad alta affidabilità (HA) con standby sincroni ed è stato abilitato il routing in standby di sola lettura.
  • Sono state create risorse BackupPlan automatizzate sia per l'archiviazione permanente locale sia per Google Cloud Storage (GCS).
  • Eseguito backup on demand e convalidato i ripristini del database.
  • Eseguito il recupero point-in-time (PITR) in un nuovo cluster di database clonato.
  • È stato eseguito il deployment di un pooler di connessioni PgBouncer per connessioni client scalabili.
  • pgAdmin4 è stato implementato e connesso per la gestione del database.
  • Eseguito la manutenzione con tempi di inattività ridotti (LDTM) per scalare dinamicamente le risorse di computing e memoria.

Passaggi successivi

15. Sondaggio

Come utilizzerai questo tutorial?

L'ho solo letta L'ho letta e ho completato gli esercizi