Implementa y administra AlloyDB Omni en Kubernetes (GKE o clúster propio)

1. Introducción

En este codelab, aprenderás a instalar el operador de AlloyDB Omni para Kubernetes (el organizador de contenedores) en un clúster de Google Kubernetes Engine (GKE) Autopilot o en tu propio clúster de Kubernetes, y a administrar flujos de trabajo completos del ciclo de vida de la base de datos y recorridos críticos del usuario (CUJ).

AlloyDB Omni es una edición descargable de AlloyDB diseñada para ejecutarse en cualquier lugar, desde entornos locales hasta Google Cloud o el procesamiento perimetral. Con el organizador de contenedores, AlloyDB Omni automatiza la alta disponibilidad, las conmutaciones por error automáticas, la reparación automática, el mantenimiento progresivo con un tiempo de inactividad mínimo, la agrupación de conexiones, las copias de seguridad automatizadas y la recuperación de un momento determinado.

Elige la ruta de tu entorno

Puedes completar este codelab con cualquiera de las siguientes dos rutas de acceso:

  1. Ruta 1: Tener una cuenta de Google Cloud (GKE Autopilot): Aprovisiona un clúster de GKE Autopilot completamente administrado con Google Cloud Shell o la consola de Google Cloud.
  2. Ruta 2: No tienes una cuenta de Google Cloud (trae tu propio clúster de Kubernetes): Usa un clúster de Kubernetes existente (v1.21 o posterior) con kubectl y helm configurados en tu estación de trabajo. No se requiere una cuenta de Google Cloud ni la CLI de gcloud.

Requisitos previos

  • Familiaridad básica con los conceptos de Kubernetes (kubectl, Helm y definiciones de recursos personalizados)
  • Para la ruta 1 (Google Cloud / GKE Autopilot):
    • Un proyecto de Google Cloud con facturación habilitada.
    • Acceso a Google Cloud Shell o a una estación de trabajo configurada con gcloud, kubectl y helm.
  • Para la ruta 2 (Trae tu propio clúster de Kubernetes):
    • Un clúster de Kubernetes que ejecute la versión 1.21 o posterior con un StorageClass predeterminado para el aprovisionamiento dinámico de PersistentVolume.
    • Nodos trabajadores que ejecutan el kernel de Linux 4.18 o una versión posterior con cgroup v2 habilitado (x86-64/AMD64) y al menos 8 CPU virtuales y 24 GiB de RAM asignable en todo el clúster.
    • Una estación de trabajo configurada con kubectl y helm conectada a tu clúster.

Qué aprenderás

  • Cómo aprovisionar un clúster de GKE Autopilot (ruta 1) o validar un clúster de Kubernetes existente (ruta 2).
  • Cómo instalar cert-manager y el operador de Kubernetes de AlloyDB Omni a través de Helm.
  • Cómo implementar una instancia única de AlloyDB Omni DBCluster.
  • Cómo escalar a alta disponibilidad (HA) con instancias en espera síncronas y habilitar la capacidad de instancias en espera de solo lectura.
  • Cómo configurar copias de seguridad automáticas programadas en el almacenamiento del repositorio local (y, de forma opcional, en Google Cloud Storage en la ruta 1)
  • Cómo realizar copias de seguridad bajo demanda y verificar el restablecimiento de datos a un estado anterior
  • Cómo realizar una recuperación de un momento determinado (PITR) en un clúster de bases de datos clonado nuevo.
  • Cómo implementar la agrupación de conexiones de PgBouncer para escalar las conexiones de los clientes.
  • Cómo implementar pgAdmin4 para administrar y consultar la base de datos de forma visual
  • Cómo ejecutar el mantenimiento con poco tiempo de inactividad (LDTM) para el escalamiento de recursos de CPU y memoria.

Requisitos

  • Ruta 1: Google Cloud Shell con las utilidades gcloud, kubectl y helm preinstaladas.
  • Ruta 2: Una terminal con kubectl y helm conectada a tu clúster de Kubernetes.
  • Para obtener documentación de referencia, consulta la guía oficial de implementación de AlloyDB Omni.

2. Configuración y requisitos

Elige la Ruta 1 si usas una cuenta de Google Cloud para crear un clúster de GKE Autopilot o la Ruta 2 si usas tu propio clúster de Kubernetes sin una cuenta de Google Cloud.

Ruta 1: Configuración del proyecto de Google Cloud (GKE Autopilot)

  1. En la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
  2. Confirma que la facturación esté habilitada para tu proyecto. Obtén información para verificar el estado de facturación.
  3. Para abrir Google Cloud Shell, haz clic en el ícono Activar Cloud Shell en la esquina superior derecha de la consola de Google Cloud o visita shell.cloud.google.com. Cloud Shell aprovisiona un entorno de procesamiento cargado con gcloud, kubectl y helm.
  4. Establece el ID del proyecto como una variable de entorno y 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. Habilita las APIs de Google Cloud requeridas para GKE y Cloud Storage:
gcloud services enable container.googleapis.com \
    storage.googleapis.com \
    cloudresourcemanager.googleapis.com

Ruta 2: Configuración de clúster propio (sin cuenta de Google Cloud)

Si no tienes una cuenta de Google Cloud y usas tu propio clúster de Kubernetes, verifica los siguientes requisitos previos desde tu terminal antes de continuar:

  1. Verifica que kubectl y helm puedan acceder a tu clúster y que tus nodos estén en estado Ready:
kubectl get nodes
helm version
  1. Verifica que tu clúster tenga un StorageClass predeterminado marcado como (default). Los manifiestos DBCluster y BackupPlan aprovisionan de forma dinámica PersistentVolumeClaims con la StorageClass predeterminada del clúster:
kubectl get storageclass

Si no hay ningún StorageClass marcado como (default), designa uno como predeterminado antes de continuar:

kubectl patch storageclass <YOUR_STORAGE_CLASS_NAME> \
  -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'
  1. Confirma que tus nodos trabajadores cumplan con los requisitos de hardware y SO del operador:
    • SO y kernel: Kernel de Linux 4.18 o posterior con cgroup v2 habilitado en nodos x86-64/AMD64.
    • Capacidad del clúster: Al menos 8 CPUs virtuales y 24 GiB de memoria asignable en tus nodos trabajadores para ejecutar las instancias de base de datos con alta disponibilidad (escaladas a 2 CPUs virtuales y 8 GiB cada una en el paso 12), la instancia clonada de PITR, PgBouncer y pgAdmin4 de forma simultánea.
    • Acceso a la red: Acceso a Internet saliente para extraer imágenes de contenedor de gcr.io/alloydb-omni, quay.io/jetstack y docker.io.

3. Aprovisiona tu clúster de Kubernetes o conéctate a él

Si sigues la Ruta 1 (cuenta de Google Cloud), GKE Autopilot proporciona un modo de Kubernetes completamente administrado y sin intervención, en el que Google administra la infraestructura del clúster, el aprovisionamiento de nodos y el ajuste de escala automático. Puedes crear tu clúster de GKE Autopilot con Google Cloud CLI o la consola de Google Cloud.

Opción A: Crea un clúster de GKE Autopilot con la CLI (ruta 1)

Ejecuta el siguiente comando de gcloud en Cloud Shell:

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

Opción B: Crea un clúster de GKE Autopilot a través de la consola (ruta 1)

  1. Abre Kubernetes Engine en la consola de Google Cloud.
  2. En el panel de navegación izquierdo, haz clic en Clústeres.
  3. Haz clic en Crear.
  4. En la sección GKE Autopilot, haz clic en Configurar.
  5. Especifica el nombre del clúster (por ejemplo, omni-autopilot-cluster) y selecciona la región que prefieras (us-central1).
  6. Haz clic en Crear.

Verifica la conectividad del clúster (ruta 1 y ruta 2)

Si creaste un clúster de GKE Autopilot en la Ruta 1, configura tus credenciales de kubectl:

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

Para la Ruta 1 y la Ruta 2, verifica la conectividad con tu clúster de Kubernetes:

kubectl get nodes

4. Instala los requisitos previos del operador y el operador

El operador de Kubernetes de AlloyDB Omni requiere cert-manager para administrar los certificados TLS de webhook de admisión.

1. Instala cert-manager

Instala cert-manager con su gráfico de Helm oficial:

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 que los Pods de cert-manager se estén ejecutando:

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

2. Instala el operador de AlloyDB Omni

Implementa el operador de Kubernetes de AlloyDB Omni en el espacio de nombres alloydb-omni-system con 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 que los Pods del operador estén en buen estado y en ejecución:

kubectl get pods -n alloydb-omni-system

5. Crea un clúster de base de datos de instancia única

En este paso, crearás un espacio de nombres de aplicación dedicado y, luego, implementarás un DBCluster de AlloyDB Omni de instancia única.

1. Crea el espacio de nombres y el Secret de credenciales de administrador

Crea un espacio de nombres omni-demo para las cargas de trabajo de la base de datos:

kubectl create namespace omni-demo

Crea un Secret de Kubernetes que almacene la contraseña del usuario administrador de la base de datos postgres predeterminado:

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. Implementa un DBCluster de instancia única

Crea un manifiesto DBCluster de instancia única:

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

3. Verifica la preparación del clúster

Supervisa el estado del clúster hasta que DBCLUSTERPHASE alcance DBClusterReady. El aprovisionamiento inicial puede tardar varios minutos: el operador debe crear el volumen persistente y extraer la imagen de la base de datos, y, en GKE Autopilot, es posible que primero se deba aprovisionar un nodo nuevo.

kubectl get dbcluster -n omni-demo -w

Presiona Ctrl+C para salir del modo de observación una vez que DBCLUSTERPHASE alcance DBClusterReady.

Resultado de muestra:

NAME   PRIMARYENDPOINT   PRIMARYPHASE   DBCLUSTERPHASE   HAREADYSTATUS   HAREADYREASON
adbo   10.128.0.45       Ready          DBClusterReady

Toma nota de la dirección IP PRIMARYENDPOINT, que es la ClusterIP del Service de Kubernetes de lectura y escritura al-adbo-rw-ilb. AlloyDB Omni escucha en el puerto predeterminado de PostgreSQL 5432.

Inspecciona los recursos que el operador concilió a partir del manifiesto DBCluster único: el Pod de la base de datos, el PersistentVolumeClaim DataDisk y el Service al-adbo-rw-ilb:

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

6. Actualiza a alta disponibilidad (HA) y habilita la instancia en espera de solo lectura

AlloyDB Omni proporciona alta disponibilidad (HA) integrada con replicación de transmisión, supervisión automática del estado, conmutación por error automatizada y entrega de réplicas de lectura.

1. Habilitar la alta disponibilidad y la capacidad de réplica de lectura

Actualiza la especificación DBCluster para configurar 1 instancia en espera y habilitar el enrutamiento en espera de solo lectura:

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

2. Verifica la estabilización de la alta disponibilidad

Espera a que la instancia en espera se aprovisione y alcance una replicación de transmisión en buen estado (HAREADYSTATUS alcanza True y HAREADYREASON alcanza Ready) y, luego, presiona Ctrl+C para salir del modo de observación:

kubectl get dbcluster adbo -n omni-demo -w

Verifica la condición de estado HAReady:

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

Verifica que se publiquen los extremos de lectura y escritura, y de solo lectura:

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

Resultado de muestra:

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

El extremo de lectura y escritura (servicio al-adbo-rw-ilb) enruta a la base de datos principal, mientras que el extremo de solo lectura (servicio al-adbo-ro-ilb) distribuye las consultas de lectura entre las instancias en espera.

7. Configura BackupPlans automatizados (locales y de GCS)

AlloyDB Omni proporciona copias de seguridad físicas y archivado de WAL a través del recurso personalizado BackupPlan. Puedes configurar la retención de copias de seguridad, las programaciones cron automatizadas y los destinos de las copias de seguridad (volúmenes persistentes locales o Google Cloud Storage).

1. Crea un BackupPlan local

Crea un BackupPlan que escriba copias de seguridad en el almacenamiento local de Kubernetes conectado a las instancias de base de datos:

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 que el BackupPlan local esté listo:

kubectl get backupplan backupplan-local -n omni-demo

Espera hasta que PHASE informe Ready y se programe NEXTBACKUPTIME.

2. Crea un BackupPlan de GCS (ruta de acceso 1: solo Google Cloud, opcional)

Para almacenar copias de seguridad de forma externa en un bucket de Google Cloud Storage, crea un bucket de GCS, configura un Secret de clave de cuenta de servicio y aplica un BackupPlan de Cloud.

  1. Crea un bucket de Cloud Storage:
export BUCKET_NAME="${PROJECT_ID}-omni-backups"
gcloud storage buckets create gs://${BUCKET_NAME} --location=${REGION}
  1. Crea una cuenta de servicio con permisos de administrador de objetos de Storage y crea una clave para ella:

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 el Secret en tu espacio de nombres de 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. Aplica el manifiesto BackupPlan de GCS. El campo key es la carpeta del bucket en la que el operador escribe las copias de seguridad. Debe comenzar 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 el estado del BackupPlan de GCS:

kubectl get backupplan backupplan-gcs -n omni-demo

Espera hasta que PHASE informe Ready y se programe NEXTBACKUPTIME.

8. Inserta datos, activa la copia de seguridad y prueba el restablecimiento

En este paso, propagarás los datos iniciales en la base de datos principal, activarás una copia de seguridad manual on demand, agregarás datos posteriores y restablecerás desde la copia de seguridad para probar la reversión de datos.

1. Propaga los datos iniciales

Ejecuta un Pod de cliente de PostgreSQL temporal para conectarte a la base de datos a través de su Service de lectura y escritura al-adbo-rw-ilb como el usuario 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;
  "

Cuando se te solicite la contraseña, ingresa ChangeMe123. Esta es la contraseña que codificaste en Base64 en el Secret db-pw-adbo en el paso 5.

2. Activa una copia de seguridad a pedido

Crea un recurso personalizado Backup manual que haga referencia a tu BackupPlan local:

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

Supervisa el progreso de la copia de seguridad:

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

Espera hasta que PHASE cambie a Succeeded.

3. Modifica datos (agrega registros nuevos)

Inserta registros adicionales después de la copia de seguridad:

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

La base de datos ahora contiene 4 filas.

4. Restablece los datos desde la copia de seguridad

Activa un restablecimiento al estado capturado en 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

Supervisa la operación de restablecimiento:

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

Espera hasta que PHASE alcance ProvisionSucceeded y verifica que DBCluster vuelva a DBClusterReady:

kubectl get dbcluster adbo -n omni-demo -w

5. Verifica el estado de los datos restablecidos

Consulta la tabla customers para verificar que solo existan los registros anteriores a la copia de seguridad:

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

El resultado confirma que solo hay 2 filas (Alpha Co y Beta LLC), lo que verifica que la base de datos se restableció al estado exacto de la copia de seguridad.

9. Recuperación de un momento determinado (PITR) en una base de datos clonada

La recuperación de un momento determinado (PITR) permite restablecer una base de datos a cualquier segundo arbitrario dentro de la ventana de recuperación con copias de seguridad base y registros de transmisión de WAL, lo que aprovisiona los datos restablecidos en un nuevo clúster de base de datos clonado.

Debido a que el operador archiva de forma continua el registro de escritura anticipada (WAL), la PITR te permite recuperarte de errores humanos o de aplicaciones accidentales, por ejemplo, un DELETE o DROP TABLE no deseado a las 2:15:00 p.m., clonando la base de datos al segundo exacto antes de que ocurriera el error (2:14:59 p.m.), sin tocar el clúster original.

1. Registra la marca de tiempo actual y muta los datos

Recupera la marca de tiempo UTC actual:

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

Inserta un registro de prueba que represente una modificación no deseada después de esta marca de tiempo:

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. Realiza un restablecimiento de un momento determinado

Aplica el recurso personalizado Restore que configura pointInTime y 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

Supervisa la operación de restablecimiento hasta que PHASE alcance ProvisionSucceeded:

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

3. Verifica la base de datos clonada

Una vez que se complete el restablecimiento, espera a que el nuevo DBCluster clonado alcance el estado DBClusterReady (presiona Ctrl+C para salir del modo de observación):

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

Consulta la base de datos clonada adbo-cloned a través de su Service de lectura y escritura 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;
  "

Observa que Unwanted Record Post-Timestamp no está presente en el clúster clonado, lo que demuestra una recuperación precisa al momento objetivo exacto.

10. Implementa el agrupador de conexiones de PgBouncer

La agrupación de conexiones reduce la sobrecarga de memoria de la base de datos y la latencia de conexión. El operador administra las instancias de PgBouncer de forma nativa a través del recurso personalizado PgBouncer.

PostgreSQL bifurca un proceso de sistema operativo independiente para cada conexión de cliente, por lo que cientos de conexiones simultáneas de servicios web, microservicios o agentes de IA pueden agotar la memoria de la base de datos. PgBouncer se ubica frente a la base de datos y multiplexa muchas conexiones de cliente de corta duración (hasta max_client_conn) en un pequeño grupo de conexiones de servidor de PostgreSQL de larga duración (default_pool_size por par de usuario/base de datos, con un límite de max_db_connections).

1. Implementa PgBouncer

Implementa un agrupador de PgBouncer de 2 réplicas vinculado al clúster 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 el estado de PgBouncer

Observa el estado de PgBouncer hasta que PHASE sea Ready:

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

Verifica los Pods y el Service de PgBouncer en ejecución:

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

3. Conéctate a través de PgBouncer

Conecta un cliente a través del servicio de PgBouncer en el puerto 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 envía la consulta de forma transparente a la base de datos principal de AlloyDB Omni.

11. Implementa pgAdmin4 para acceder a la base de datos

Puedes ejecutar pgAdmin4 directamente dentro del clúster de Kubernetes para proporcionar una consola de administración basada en la Web que permita consultar, administrar y, también, inspeccionar AlloyDB Omni.

1. Instala pgAdmin4 con Helm

Instala pgadmin4 en el espacio de nombres 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"

Este gráfico asigna el nombre pgadmin4 a sus recursos de Kubernetes (Deployment, Service y PersistentVolumeClaim) y etiqueta sus Pods con app=pgadmin4, independientemente del nombre de la versión de Helm (my-pgadmin).

Verifica que el Pod de pgAdmin4 se esté ejecutando:

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

2. Reenvía el puerto y accede a la IU web

Redirecciona los puertos de pgAdmin4 a tu entorno local o a Cloud Shell:

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

kubectl port-forward se sigue ejecutando en primer plano mientras usas la IU web de pgAdmin4. Abre una segunda terminal (o una nueva pestaña de Cloud Shell) para otros comandos y presiona Ctrl+C en esta terminal cuando tengas todo listo para avanzar al siguiente paso.

Abre la interfaz web de pgAdmin4:

  • Ruta 1 (Google Cloud Shell): Haz clic en el botón Vista previa en la Web en el menú de la esquina superior derecha, selecciona Cambiar puerto, ingresa 5050 y haz clic en Cambiar y obtener vista previa.
  • Ruta 2 (estación de trabajo local): Abre http://localhost:5050 en tu navegador mientras se ejecuta el comando kubectl port-forward.

Accede con lo siguiente:

  • Correo electrónico: admin@example.com
  • Contraseña: AdminPassword123

3. Registra AlloyDB Omni en pgAdmin4

  1. En pgAdmin4, haz clic con el botón derecho en Servers > Register > Server….
  2. En la pestaña General, haz lo siguiente:
    • Nombre: AlloyDB Omni Primary
  3. En la pestaña Conexión, haz lo siguiente:
    • Nombre o dirección del host: al-adbo-rw-ilb.omni-demo.svc.cluster.local (o al-omni-pgbouncer-pgb-svc.omni-demo.svc.cluster.local para PgBouncer)
    • Puerto: 5432 (o 6432 para PgBouncer)
    • Base de datos de mantenimiento: postgres
    • Nombre de usuario: postgres
    • Contraseña: ChangeMe123
  4. Haz clic en Guardar y verifica la sesión y las tablas de la base de datos activa.

12. Escala la CPU y la memoria con el mantenimiento con poco tiempo de inactividad (LDTM)

Cuando se escala verticalmente el procesamiento y la memoria en una base de datos de producción, las actualizaciones tradicionales causan interrupciones en el reinicio de la base de datos. AlloyDB Omni proporciona mantenimiento con poco tiempo de inactividad (LDTM) para implementar actualizaciones progresivas a través de réplicas con una interrupción mínima de la aplicación.

1. Habilitar la anotación de LDTM

Anota el DBCluster para habilitar LDTM para las actualizaciones:

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

2. Escala los recursos de CPU y memoria

Actualiza los recursos principales de 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. Supervisa el progreso del escalamiento de LDTM

Supervisa la actualización progresiva y las condiciones de cambio de la instancia en espera a la principal:

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

Observa cómo se actualizan los Pods de forma gradual:

kubectl get pods -n omni-demo -w

LDTM prepara primero la instancia en espera actualizada, verifica la replicación de transmisión, ejecuta un cambio rápido y actualiza la instancia restante sin interrupciones del servicio.

Verifica la asignación de recursos actualizada:

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

13. Limpia los recursos

Para liberar capacidad del clúster y evitar cargos innecesarios en tu cuenta de Google Cloud, limpia los recursos aprovisionados durante este codelab.

Si ejecutas la limpieza en una nueva sesión de terminal (Ruta 1), las variables de entorno de los pasos anteriores ya no estarán configuradas. Vuelve a exportarlas con los mismos valores que usaste antes:

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

1. Borra las cargas de trabajo de la base de datos (ruta 1 y ruta 2)

Marca ambos clústeres como borrados para pasar las verificaciones del webhook de admisión, espera a que el operador quite los recursos DBCluster y, luego, borra el espacio de nombres:

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

Si usaste tu propio clúster de Kubernetes (Ruta 2) y también quieres quitar el operador de AlloyDB Omni y cert-manager, haz lo siguiente:

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. Borra el bucket de GCS y la cuenta de servicio de IAM (solo para la ruta 1)

Si creaste el bucket de Google Cloud Storage y la cuenta de servicio en la Ruta 1, haz lo siguiente:

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. Borra el clúster de GKE (solo para la ruta 1)

Si aprovisionaste un clúster de GKE Autopilot en la Ruta 1, haz lo siguiente:

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

14. Felicitaciones

¡Felicitaciones! Completaste el codelab de AlloyDB Omni en Kubernetes.

Temas abordados

  • Aprovisionaste un clúster de GKE Autopilot (ruta 1) o preparaste un clúster de Kubernetes existente (ruta 2).
  • Se implementó cert-manager y el operador de Kubernetes de AlloyDB Omni a través de Helm.
  • Implementaste una instancia única de AlloyDB Omni DBCluster.
  • Se actualizó el clúster a alta disponibilidad (HA) con instancias en espera síncronas y se habilitó el enrutamiento de instancias en espera de solo lectura.
  • Se crearon recursos de BackupPlan automatizados para el almacenamiento persistente local y Google Cloud Storage (GCS).
  • Realicé copias de seguridad bajo demanda y validé los restablecimientos de bases de datos.
  • Ejecutaste la recuperación de un momento determinado (PITR) en un nuevo clúster de base de datos clonado.
  • Se implementó un agrupador de conexiones de PgBouncer para conexiones de clientes escalables.
  • Implementaste y conectaste pgAdmin4 para la administración de bases de datos.
  • Se ejecutó el mantenimiento con poco tiempo de inactividad (LDTM) para escalar de forma dinámica los recursos de procesamiento y memoria.

Próximos pasos

15. Encuesta

¿Cómo usarás este instructivo?

Solo lo leeré Lo leeré y completaré los ejercicios