Kubernetes（GKE または独自のクラスタ）に AlloyDB Omni をデプロイして管理する

1. はじめに

この Codelab では、Google Kubernetes Engine（GKE）Autopilot クラスタまたは独自の Kubernetes クラスタに AlloyDB Omni Kubernetes Operator（コンテナ オーケストレーター）をインストールし、エンドツーエンドのデータベース ライフサイクル ワークフローとクリティカル ユーザー ジャーニー（CUJ）を完全に管理する方法について説明します。

AlloyDB Omni は、オンプレミス環境から Google Cloud、エッジ コンピューティングまで、どこでも実行できるように設計された AlloyDB のダウンロード版です。コンテナ オーケストレーターを使用すると、AlloyDB Omni は高可用性、自動フェイルオーバー、セルフヒーリング、ダウンタイムを最小限に抑えたローリング メンテナンス、接続プーリング、自動バックアップ、ポイントインタイム リカバリを自動化します。

AlloyDB for PostgreSQL と AlloyDB Omni の比較: AlloyDB for PostgreSQL は、Google Cloud のフルマネージド データベース サービスです。AlloyDB Omni は、同じ AlloyDB データベース エンジンをダウンロード可能なコンテナにパッケージ化したもので、オンプレミス、他のパブリック クラウド（Amazon EKS や Azure AKS など）、OpenShift、デベロッパー ワークステーションで、データ所在地、ハイブリッド クラウド、ローカル開発の要件に合わせて、自分で実行して運用できます。実際のデプロイでは、通常、独自の Kubernetes クラスタで AlloyDB Omni Kubernetes Operator を実行します（パス 2）。パス 1 では、クラスタがまだない場合に、便利なゼロローカル セットアップの Kubernetes サンドボックスとしてのみ GKE Autopilot を使用します。

環境パスを選択する

この Codelab は、次の 2 つの方法のいずれかで完了できます。

1. パス 1: Google Cloud アカウント（GKE Autopilot）を使用する - Google Cloud Shell または Google Cloud コンソールを使用して、フルマネージド GKE Autopilot クラスタをプロビジョニングします。
2. パス 2: Google Cloud アカウントがない（独自の Kubernetes クラスタを使用する） - ワークステーションで kubectl と helm が構成された既存の Kubernetes クラスタ（v1.21 以降）を使用します。Google Cloud アカウントや gcloud CLI は必要ありません。

前提条件

• Kubernetes のコンセプト（kubectl、Helm、カスタム リソース定義）に関する基本的な知識。
• パス 1（Google Cloud / GKE Autopilot）の場合:
  • 課金を有効にした Google Cloud プロジェクト
  • Google Cloud Shell または gcloud、kubectl、helm で構成されたワークステーションへのアクセス。
• パス 2（独自の Kubernetes クラスタを使用する）の場合:
  • バージョン 1.21 以降が実行される Kubernetes クラスタ。動的 PersistentVolume プロビジョニング用のデフォルトの StorageClass が設定されている。
  • cgroup v2 が有効になっている Linux カーネル 4.18+（x86-64/AMD64）を実行し、クラスタ全体で 8 個以上の vCPU と 24 GiB 以上の割り当て可能な RAM を備えたワーカーノード。
  • kubectl と helm が構成され、クラスタに接続されているワークステーション。

学習内容

• GKE Autopilot クラスタをプロビジョニングする方法（パス 1）または既存の Kubernetes クラスタを検証する方法（パス 2）。
• Helm を使用して cert-manager と AlloyDB Omni Kubernetes オペレーターをインストールする方法。
• 単一インスタンスの AlloyDB Omni DBCluster をデプロイする方法。
• 同期スタンバイを使用して高可用性（HA）にスケーリングし、読み取り専用スタンバイ機能を有効にする方法。
• ローカル リポジトリ ストレージ（および必要に応じてパス 1 の Google Cloud Storage）へのスケジュール設定された自動バックアップを構成する方法。
• オンデマンド バックアップを実行し、以前の状態へのデータ復元を検証する方法。
• 新しくクローン作成されたデータベース クラスタにポイントインタイム リカバリ（PITR）を実行する方法。
• クライアント接続のスケーリングのために PgBouncer 接続プーリングをデプロイする方法。
• pgAdmin4 をデプロイして、データベースを視覚的に管理し、クエリを実行する方法。
• CPU とメモリリソースのスケーリングに低ダウンタイム メンテナンス（LDTM）を実行する方法。

必要なもの

• パス 1: gcloud、kubectl、helm ユーティリティがプリインストールされた Google Cloud Shell。
• パス 2: kubectl と helm が Kubernetes クラスタに接続されているターミナル。
• リファレンス ドキュメントについては、公式の AlloyDB Omni デプロイガイドをご覧ください。

2. 設定と要件

Google Cloud アカウントを使用して GKE Autopilot クラスタを作成する場合はパス 1 を選択し、Google Cloud アカウントを使用せずに独自の Kubernetes クラスタを使用する場合はパス 2 を選択します。

パス 1: Google Cloud プロジェクトの設定（GKE Autopilot）

1. Google Cloud コンソールで、Google Cloud プロジェクトを選択または作成します。
2. お支払いが有効になっていることを確認します。詳しくは、課金ステータスを確認するをご覧ください。
3. Google Cloud コンソールの右上にある [Cloud Shell をアクティブにする] アイコンをクリックするか、shell.cloud.google.com にアクセスして、Google Cloud Shell を開きます。Cloud Shell は、gcloud、kubectl、helm が読み込まれたコンピューティング環境をプロビジョニングします。
4. プロジェクト ID を環境変数として設定し、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}

5. GKE と Cloud Storage に必要な Google Cloud APIs を有効にします。

gcloud services enable container.googleapis.com \
    storage.googleapis.com \
    cloudresourcemanager.googleapis.com

パス 2: 独自のクラスタの設定（Google Cloud アカウントなし）

Google Cloud アカウントをお持ちでなく、独自の Kubernetes クラスタを使用している場合は、続行する前にターミナルから次の前提条件を確認してください。

1. kubectl と helm がクラスタにアクセスできること、ノードが Ready であることを確認します。

kubectl get nodes
helm version

2. クラスタに (default) とマークされたデフォルトの StorageClass があることを確認します。DBCluster マニフェストと BackupPlan マニフェストは、クラスタのデフォルトの StorageClass を使用して PersistentVolumeClaim を動的にプロビジョニングします。

kubectl get storageclass

(default) とマークされた StorageClass がない場合は、続行する前に 1 つをデフォルトとして指定します。

kubectl patch storageclass <YOUR_STORAGE_CLASS_NAME> \
  -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

3. ワーカーノードがオペレーターのハードウェアと OS の要件を満たしていることを確認します。
   • OS とカーネル: x86-64/AMD64 ノードで cgroup v2 が有効になっている Linux カーネル 4.18 以降。
   • クラスタ容量: HA データベース インスタンス（ステップ 12 でそれぞれ 2 vCPU と 8 GiB にスケーリング）、PITR クローン インスタンス、PgBouncer、pgAdmin4 を同時に実行するために、ワーカーノード全体で少なくとも 8 vCPU と 24 GiB の割り当て可能なメモリが必要です。
   • ネットワーク アクセス: gcr.io/alloydb-omni、quay.io/jetstack、docker.io からコンテナ イメージを pull するためのアウトバウンド インターネット アクセス。

3. Kubernetes クラスタをプロビジョニングまたは接続する

独自の Kubernetes クラスタを使用する場合（パス 2）以下のオプション A とオプション B をスキップし、クラスタ接続を確認するでクラスタノードが Ready であることを確認して、次のステップに直接進みます。

パス 1（Google Cloud アカウント）に沿って進める場合、GKE Autopilot は、Google がクラスタ インフラストラクチャ、ノードのプロビジョニング、自動スケーリングを管理する、ハンズオフのフルマネージド Kubernetes モードを提供します。GKE Autopilot クラスタは、Google Cloud CLI または Google Cloud コンソールを使用して作成できます。

オプション A: CLI を使用して GKE Autopilot クラスタを作成する（パス 1）

Cloud Shell で次の gcloud コマンドを実行します。

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

オプション B: コンソールで GKE Autopilot クラスタを作成する（パス 1）

1. Google Cloud コンソールで Kubernetes Engine を開きます。
2. 左側のナビゲーション パネルで [クラスタ] をクリックします。
3. [作成] をクリックします。
4. [GKE Standard] セクションで [構成] をクリックします。
5. クラスタ名（omni-autopilot-cluster など）を指定し、優先リージョン（us-central1）を選択します。
6. [作成] をクリックします。

クラスタ接続を確認する（パス 1 とパス 2）

パス 1 で GKE Autopilot クラスタを作成した場合は、kubectl 認証情報を構成します。

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

パス 1 とパス 2 の両方で、Kubernetes クラスタへの接続を確認します。

kubectl get nodes

4. Operator の前提条件と Operator をインストールする

AlloyDB Omni Kubernetes Operator は、アドミッション Webhook TLS 証明書の管理に cert-manager を必要とします。

1. cert-manager をインストールする

公式の Helm チャートを使用して cert-manager をインストールします。

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

cert-manager Pod が実行されていることを確認します。

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

2. AlloyDB Omni Operator をインストールする

Helm を使用して、AlloyDB Omni Kubernetes オペレーターを alloydb-omni-system Namespace にデプロイします。

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

オペレーター Pod が正常で実行されていることを確認します。

kubectl get pods -n alloydb-omni-system

5. 単一インスタンス データベース クラスタを作成する

このステップでは、専用のアプリケーション Namespace を作成し、単一インスタンスの AlloyDB Omni DBCluster をデプロイします。

1. Namespace と管理者認証情報の Secret を作成する

データベース ワークロードに Namespace omni-demo を作成します。

kubectl create namespace omni-demo

デフォルトの postgres データベース管理者ユーザーのパスワードを保存する Kubernetes Secret を作成します。

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. 単一インスタンスの DBCluster をデプロイする

単一インスタンスの DBCluster マニフェストを作成します。

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. クラスタの準備状況を確認する

DBCLUSTERPHASE が DBClusterReady になるまで、クラスタのステータスをモニタリングします。最初のプロビジョニングには数分かかることがあります。オペレーターは永続ボリュームを作成してデータベース イメージを pull する必要があります。GKE Autopilot では、最初に新しいノードをプロビジョニングする必要がある場合があります。

kubectl get dbcluster -n omni-demo -w

DBCLUSTERPHASE が DBClusterReady に達したら、Ctrl+C を押して watch モードを終了します。

出力例:

NAME   PRIMARYENDPOINT   PRIMARYPHASE   DBCLUSTERPHASE   HAREADYSTATUS   HAREADYREASON
adbo   10.128.0.45       Ready          DBClusterReady

PRIMARYENDPOINT IP アドレスをメモします。これは、読み取り / 書き込み Kubernetes Service al-adbo-rw-ilb の ClusterIP です。AlloyDB Omni は、デフォルトの PostgreSQL ポート 5432 でリッスンします。

オペレーターが単一の DBCluster マニフェストから調整したリソース（データベース Pod、DataDisk PersistentVolumeClaim、al-adbo-rw-ilb Service）を調べます。

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

6. 高可用性（HA）にアップグレードして、読み取り専用スタンバイを有効にする

AlloyDB Omni は、ストリーミング レプリケーション、自動ヘルス モニタリング、自動フェイルオーバー、リードレプリカ サービスを備えた組み込みの高可用性（HA）を提供します。

1. HA とリードレプリカ機能を有効にする

DBCluster 仕様を更新して、1 つのスタンバイ インスタンスを構成し、読み取り専用スタンバイ ルーティングを有効にします。

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

2. HA の安定化を確認する

スタンバイ インスタンスがプロビジョニングされ、正常なストリーミング レプリケーションに達するまで待ちます（HAREADYSTATUS が True に達し、HAREADYREASON が Ready に達します）。その後、Ctrl+C を押してウォッチモードを終了します。

kubectl get dbcluster adbo -n omni-demo -w

HAReady のステータス条件を確認します。

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

読み取り / 書き込みエンドポイントと読み取り専用エンドポイントの両方が公開されていることを確認します。

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

出力例:

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

読み取り / 書き込みエンドポイント（al-adbo-rw-ilb Service）はプライマリ データベースにルーティングし、読み取り専用エンドポイント（al-adbo-ro-ilb Service）は読み取りクエリをスタンバイ インスタンスに分散します。

7. 自動 BackupPlan（ローカルと GCS）を構成する

AlloyDB Omni は、BackupPlan カスタム リソースを介して物理バックアップと WAL アーカイブを提供します。バックアップの保持、自動 cron スケジュール、バックアップ ターゲット（ローカル永続ボリュームまたは Google Cloud Storage）を構成できます。

1. ローカル BackupPlan を作成する

データベース インスタンスにアタッチされたローカル Kubernetes ストレージにバックアップを書き込む BackupPlan を作成します。

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

ローカル BackupPlan の準備ができていることを確認します。

kubectl get backupplan backupplan-local -n omni-demo

PHASE が Ready を報告し、NEXTBACKUPTIME がスケジュールされるまで待ちます。

2. GCS BackupPlan を作成する（パス 1: Google Cloud のみ - 省略可）

Google Cloud アカウントなしで独自の Kubernetes クラスタを使用する場合（パス 2）2. GCS BackupPlan を作成して、次のステップに直接進みます。この Codelab の残りのバックアップとポイントインタイム リカバリの演習では、前のセクションの backupplan-local を使用します。

バックアップを Google Cloud Storage バケットに外部保存するには、GCS バケットを作成し、サービス アカウント キーのシークレットを構成して、クラウド BackupPlan を適用します。

1. Cloud Storage バケットを作成します。

export BUCKET_NAME="${PROJECT_ID}-omni-backups"
gcloud storage buckets create gs://${BUCKET_NAME} --location=${REGION}

2. Storage オブジェクト管理者権限を持つサービス アカウントを作成し、そのキーを作成します。

注意: AlloyDB Omni Operator は、Kubernetes Secret に保存されているサービス アカウント キーから Cloud Storage 認証情報を読み取ります。オペレーターのドキュメントでは、Workload Identity Federation for GKE などの他の認証方法については説明していません。組織で iam.disableServiceAccountKeyCreation 組織ポリシーが適用されている場合、keys create コマンドは失敗します。その場合は、GCS BackupPlan を作成するの残りの部分をスキップします。この Codelab の残りの手順では、ローカル バックアップ プランを使用します。

サービス アカウント キーは有効期間の長い認証情報です。次のステップでローカルコピーを削除し、クリーンアップ ステップでサービス アカウントとそのキーを削除します。詳細については、Cloud Storage にバックアップを保存するプランを作成するをご覧ください。

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"

3. Kubernetes Namespace に Secret を作成します。

kubectl create secret generic gcs-backup-secret \
  --from-file=key.json=/tmp/gcs-key.json \
  -n omni-demo
rm /tmp/gcs-key.json

4. GCS BackupPlan マニフェストを適用します。key フィールドは、オペレーターがバックアップを書き込むバケット内のフォルダです。先頭を / にする必要があります。

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

GCS BackupPlan のステータスを確認します。

kubectl get backupplan backupplan-gcs -n omni-demo

PHASE が Ready を報告し、NEXTBACKUPTIME がスケジュールされるまで待ちます。

8. データを挿入し、バックアップをトリガーして、復元をテストする

このステップでは、プライマリ データベースに初期データを入力し、オンデマンドの手動バックアップをトリガーして、後続のデータを追加し、バックアップから復元してデータのロールバックを検証します。

1. 初期データを入力する

一時的な PostgreSQL クライアント Pod を実行して、読み取り / 書き込みサービス al-adbo-rw-ilb を介して 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;
  "

パスワードを求められたら「ChangeMe123」と入力します。これは、ステップ 5 で db-pw-adbo Secret で Base64 でエンコードしたパスワードです。

注: この Codelab の残りの kubectl run pg-client コマンドは --env="PGPASSWORD=ChangeMe123" を渡すため、psql はインタラクティブなプロンプトなしで認証を行います。これはデモの便宜上のものであり、本番環境のパスワードをコマンドラインに配置しないでください。

2. オンデマンド バックアップをトリガーする

ローカル BackupPlan を参照する手動 Backup カスタム リソースを作成します。

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

バックアップの進行状況をモニタリングします。

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

PHASE が Succeeded に移行するまで待ちます。

3. Mutate Data（新しいレコードを追加）

バックアップ後に追加のレコードを挿入します。

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

データベースに 4 行が含まれるようになりました。

4. バックアップから復元する

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

復元オペレーションをモニタリングします。

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

PHASE が ProvisionSucceeded に達するまで待機し、DBCluster が DBClusterReady に戻ることを確認します。

kubectl get dbcluster adbo -n omni-demo -w

5. 復元されたデータの状態を確認する

customers テーブルに対してクエリを実行して、バックアップ前のレコードのみが存在することを確認します。

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

出力には 2 行（Alpha Co と Beta LLC）のみが表示され、データベースがバックアップの状態に正確に復元されたことが確認できます。

9. クローン作成されたデータベースへのポイントインタイム リカバリ（PITR）

ポイントインタイム リカバリ（PITR）を使用すると、ベース バックアップと WAL ストリーム ログを使用して、リカバリ ウィンドウ内の任意の秒にデータベースを復元し、復元されたデータを新しいクローン データベース クラスタにプロビジョニングできます。

オペレーターは write-ahead log 書き込み（WAL）を継続的にアーカイブするため、PITR を使用すると、偶発的な人的エラーやアプリケーション エラー（午後 2 時 15 分 00 秒に意図しない DELETE や DROP TABLE が発生した場合など）から復元できます。これは、元のクラスタに触れることなく、エラーが発生する直前の秒（午後 2 時 14 分 59 秒）にデータベースのクローンを作成することで行われます。

1. 現在のタイムスタンプを記録してデータを変更する

現在の UTC タイムスタンプを取得します。

export PITR_TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
echo "PITR Target Timestamp: ${PITR_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. ポイントインタイム復元を実行する

注: オペレーターは、クローン作成された DBCluster をソースクラスタ omni-demo と同じ Namespace に作成します。別の Namespace へのクローン作成はサポートされていません。詳細については、特定の時点からクラスタのクローンを作成するをご覧ください。

pointInTime と clonedDBClusterConfig を構成する Restore カスタム リソースを適用します。

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

PHASE が ProvisionSucceeded になるまで、復元オペレーションをモニタリングします。

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

3. クローン作成されたデータベースを確認する

復元が完了したら、新しいクローン DBCluster が DBClusterReady になるまで待ちます（Ctrl+C を押してウォッチモードを終了します）。

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

読み取り / 書き込みサービス al-adbo-cloned-rw-ilb を介して、クローン作成されたデータベース adbo-cloned にクエリを実行します。

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

クローン作成されたクラスタに Unwanted Record Post-Timestamp が存在しないことに注目してください。これは、正確なターゲット時点に正確に復元されたことを示しています。

10. PgBouncer 接続プーラーをデプロイする

接続プーリングにより、データベースのメモリ オーバーヘッドと接続レイテンシが削減されます。オペレーターは、PgBouncer カスタム リソースを介して PgBouncer インスタンスをネイティブに管理します。

PostgreSQL はクライアント接続ごとに個別のオペレーティング システム プロセスをフォークするため、ウェブサービス、マイクロサービス、AI エージェントからの数百の同時接続によってデータベース メモリが枯渇する可能性があります。PgBouncer はデータベースの前に配置され、多くの短期間のクライアント接続（最大 max_client_conn）を、長期間の PostgreSQL サーバー接続の小さなプール（ユーザー/データベースのペアごとに default_pool_size、上限は max_db_connections）に多重化します。

1. PgBouncer をデプロイする

クラスタ adbo にリンクされた 2 レプリカの PgBouncer プーラーをデプロイします。

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. PgBouncer のステータスを確認する

PHASE が Ready になるまで PgBouncer のステータスを監視します。

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

実行中の PgBouncer Pod と Service を確認します。

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

3. PgBouncer 経由で接続する

ポート 6432 の PgBouncer サービスを介してクライアントを接続します。

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 は、クエリをプライマリ AlloyDB Omni データベースにシームレスにプロキシします。

11. pgAdmin4 をデプロイしてデータベースにアクセスする

Kubernetes クラスタ内で pgAdmin4 を直接実行して、AlloyDB Omni のクエリ、管理、検査を行うウェブベースの管理コンソールを提供できます。

1. Helm を使用して pgAdmin4 をインストールする

omni-demo Namespace に pgadmin4 をインストールします。

helm install my-pgadmin oci://docker.io/dpage/pgadmin4-helm \
  --namespace omni-demo \
  --set ingress.enabled=false \
  --set image.tag=latest \
  --set auth.email="[e-mail]" \
  --set auth.password="AdminPassword123"

このチャートでは、Helm リリース名（my-pgadmin）に関係なく、Kubernetes リソースに pgadmin4（Deployment、Service、PersistentVolumeClaim）という名前を付け、Pod に app=pgadmin4 というラベルを付けます。

pgAdmin4 Pod が実行されていることを確認します。

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

2. ポートを転送してウェブ UI にアクセスする

pgAdmin4 をローカル環境または Cloud Shell にポート転送します。

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

kubectl port-forward は、pgAdmin4 ウェブ UI を使用している間、フォアグラウンドで実行され続けます。他のコマンド用に 2 つ目のターミナル（または新しい Cloud Shell タブ）を開き、次のステップに進む準備ができたら、このターミナルで Ctrl+C を押します。

pgAdmin4 ウェブ インターフェースを開きます。

• パス 1（Google Cloud Shell）: 右上のメニューにある [ウェブでプレビュー] ボタンをクリックし、[ポートを変更] を選択して「5050」と入力し、[変更してプレビュー] をクリックします。
• パス 2（ローカル ワークステーション）: kubectl port-forward コマンドの実行中に、ブラウザで http://localhost:5050 を開きます。

ログイン方法:

• メール: [e-mail]
• パスワード: AdminPassword123

3. pgAdmin4 に AlloyDB Omni を登録する

1. pgAdmin4 で、[Servers] > [Register] > [Server...] を右クリックします。
2. [全般] タブで、次の操作を行います。
   • 名前: AlloyDB Omni Primary
3. [接続] タブで、次の操作を行います。
   • ホスト名/アドレス: al-adbo-rw-ilb.omni-demo.svc.cluster.local（PgBouncer の場合は al-omni-pgbouncer-pgb-svc.omni-demo.svc.cluster.local）
   • ポート: 5432（PgBouncer の場合は 6432）
   • メンテナンス データベース: postgres
   • ユーザー名: postgres
   • パスワード: ChangeMe123
4. [Save] をクリックし、アクティブなデータベース セッションとテーブルを確認します。

12. 低ダウンタイム メンテナンス（LDTM）で CPU とメモリをスケーリングする

本番環境データベースでコンピューティングとメモリを垂直方向にスケーリングする場合、従来の更新ではデータベースの再起動による中断が発生します。AlloyDB Omni は、低ダウンタイム メンテナンス（LDTM）を提供し、アプリケーションの中断を最小限に抑えながらレプリカを介して更新をローリング アップデートします。

1. LDTM アノテーションを有効にする

DBCluster にアノテーションを付けて、更新に LDTM を有効にします。

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

2. CPU リソースとメモリリソースをスケーリングする

プライマリ リソースを cpu: 1, memory: 4Gi から cpu: 2, memory: 8Gi に更新します。

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

3. LDTM のスケーリングの進行状況をモニタリングする

ローリング アップデートとスタンバイからプライマリへの切り替え条件をモニタリングします。

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

Pod が正常にローリングされていることを確認します。

kubectl get pods -n omni-demo -w

LDTM は、まず更新されたスタンバイを準備し、ストリーミング レプリケーションを検証して、高速スイッチオーバーを実行し、サービスを中断することなく残りのインスタンスを更新します。

更新されたリソース割り当てを確認します。

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

13. リソースをクリーンアップする

クラスタの容量を解放し、Google Cloud アカウントに不要な料金が発生しないようにするには、この Codelab でプロビジョニングしたリソースをクリーンアップします。

新しいターミナル セッション（パス 1）でクリーンアップを実行している場合、前の手順の環境変数は設定されなくなります。以前に使用した値と同じ値で再エクスポートします。

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. データベース ワークロードを削除する（パス 1 とパス 2）

両方のクラスタを削除済みとしてマークして、アドミッション Webhook チェックに合格し、オペレーターが DBCluster リソースを削除するのを待ってから、名前空間を削除します。

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

独自の Kubernetes クラスタ（パス 2）を使用し、AlloyDB Omni Operator と 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. GCS バケットと IAM サービス アカウントを削除する（パス 1 のみ）

パス 1 で Google Cloud Storage バケットとサービス アカウントを作成した場合:

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. GKE クラスタを削除する（パス 1 のみ）

パス 1 で GKE Autopilot クラスタをプロビジョニングした場合:

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

14. 完了

おめでとうございます！Kubernetes での AlloyDB Omni の Codelab を完了しました。

学習した内容

• GKE Autopilot クラスタをプロビジョニングした（パス 1）か、既存の Kubernetes クラスタを準備した（パス 2）。
• Helm を介して cert-manager と AlloyDB Omni Kubernetes Operator をデプロイしました。
• 単一インスタンスの AlloyDB Omni DBCluster をデプロイしました。
• クラスタを同期スタンバイを備えた高可用性（HA）にアップグレードし、読み取り専用スタンバイ ルーティングを有効にしました。
• ローカル永続ストレージと Google Cloud Storage（GCS）の両方に自動化された BackupPlan リソースを作成しました。
• オンデマンド バックアップを実行し、データベースの復元を検証しました。
• 新しいクローン データベース クラスタに対してポイントインタイム リカバリ（PITR）を実行しました。
• スケーラブルなクライアント接続のために PgBouncer 接続プーラーをデプロイしました。
• データベース管理用に pgAdmin4 をデプロイして接続しました。
• 低ダウンタイム メンテナンス（LDTM）を実行して、コンピューティング リソースとメモリリソースを動的にスケーリングしました。

次のステップ

• マルチクラスタ環境での AlloyDB Omni 障害復旧（DR）について確認する。
• AlloyDB Omni AI と pgvector の機能の詳細を確認する。

15. アンケート

このチュートリアルの利用方法をお選びください。

全体を通して読むだけ 内容を読んで演習をやり遂げる