GKE に PostgreSQL ベクトル データベースをデプロイする

このチュートリアルでは、Google Kubernetes Engine（GKE）に PostgreSQL ベクトル データベース クラスタをデプロイする方法について説明します。

PostgreSQL には、データベースの機能を拡張するさまざまなモジュールと拡張機能が用意されています。このチュートリアルでは、GKE にデプロイされた既存の PostgreSQL クラスタに pgvector 拡張機能をインストールします。Pgvector 拡張機能を使用すると、ベクトル型を PostgreSQL に追加して、ベクトルをデータベース テーブルに格納できます。Pgvector は、一般的な SQL クエリによる類似性検索も提供します。

まず CloudnativePG オペレーターをデプロイして、PGvector 拡張機能のデプロイを簡素化します。このオペレーターは、拡張機能のバンドル バージョンを提供します。

このチュートリアルは、GKE に PostgreSQL データベース クラスタをデプロイすることに関心があるクラウド プラットフォーム管理者とアーキテクト、ML エンジニア、MLOps（DevOps）の専門家を対象としています。

目標

このチュートリアルでは、次の方法について学習します。

• PostgreSQL 用の GKE インフラストラクチャをデプロイする。
• GKE にデプロイされた PostgreSQL クラスタに pgvector 拡張機能をインストールする。
• Helm を使用して CloudNativePG PostgreSQL オペレーターをデプロイして構成する。
• デモ データセットをアップロードして Jupyter Notebook で検索クエリを実行する。

環境の設定

Cloud Shell を使用して環境を設定するには、次の操作を行います。

1. プロジェクト、リージョン、Kubernetes クラスタ リソースの接頭辞に環境変数を設定します。

   export PROJECT_ID=PROJECT_ID
   export KUBERNETES_CLUSTER_PREFIX=postgres
   export REGION=us-central1
   

   • PROJECT_ID は、実際の Google Cloudプロジェクト ID に置き換えます。

   このチュートリアルでは、us-central1 リージョンを使用します。

2. GitHub からサンプルコード リポジトリのクローンを作成します。

   git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples
   

3. postgres-pgvector ディレクトリに移動します。

   cd kubernetes-engine-samples/databases/postgres-pgvector
   

クラスタ インフラストラクチャを作成する

このセクションでは、Terraform スクリプトを実行して、限定公開の高可用性 GKE リージョン クラスタを作成し、PostgreSQL データベースをデプロイします。

PostgreSQL のデプロイには、Standard クラスタまたは Autopilot クラスタを使用できます。それぞれに利点があり、料金モデルも異なります。

Autopilot

Autopilot クラスタ インフラストラクチャをデプロイするには、Cloud Shell で次のコマンドを実行します。

export GOOGLE_OAUTH_ACCESS_TOKEN=$(gcloud auth print-access-token)
terraform -chdir=../postgresql-cloudnativepg/terraform/gke-autopilot init
terraform -chdir=../postgresql-cloudnativepg/terraform/gke-autopilot apply \
-var project_id=${PROJECT_ID} \
-var region=${REGION} \
-var cluster_prefix=${KUBERNETES_CLUSTER_PREFIX}

GKE は、実行時に次の変数を置き換えます。

• GOOGLE_OAUTH_ACCESS_TOKEN は、gcloud auth print-access-token コマンドを使用して、さまざまな Google Cloud APIs とのやり取りを認証するアクセス トークンを取得します。
• PROJECT_ID、REGION、KUBERNETES_CLUSTER_PREFIX は、環境を設定するセクションで定義した環境変数で、作成する Autopilot クラスタの新しい関連変数に割り当てられます。

プロンプトが表示されたら、「yes」と入力します。

Terraform が次のリソースを作成します。

• Kubernetes ノード用のカスタム VPC ネットワークとプライベート サブネット
• ネットワーク アドレス変換（NAT）を介してインターネットにアクセスするための Cloud Router。
• us-central1 リージョンの限定公開 GKE クラスタ。
• クラスタのロギングとモニタリングの権限を持つ ServiceAccount。
• クラスタのモニタリングおよびアラート用の Google Cloud Managed Service for Prometheus の構成。

出力は次のようになります。

...
Apply complete! Resources: 11 added, 0 changed, 0 destroyed.
...

Standard

Standard クラスタ インフラストラクチャをデプロイするには、Cloud Shell で次のコマンドを実行します。

export GOOGLE_OAUTH_ACCESS_TOKEN=$(gcloud auth print-access-token)
terraform -chdir=../postgresql-cloudnativepg/terraform/gke-standard init
terraform -chdir=../postgresql-cloudnativepg/terraform/gke-standard apply \
-var project_id=${PROJECT_ID} \
-var region=${REGION} \
-var cluster_prefix=${KUBERNETES_CLUSTER_PREFIX}

GKE は、実行時に次の変数を置き換えます。

• GOOGLE_OAUTH_ACCESS_TOKEN は、gcloud auth print-access-token コマンドを使用して、さまざまな Google Cloud APIs とのやり取りを認証するアクセス トークンを取得します。
• PROJECT_ID、REGION、KUBERNETES_CLUSTER_PREFIX は、環境を設定するセクションで定義した環境変数で、作成する Standard クラスタの新しい関連変数に割り当てられます。

プロンプトが表示されたら、「yes」と入力します。これらのコマンドが完了し、クラスタが「準備完了」ステータスになるまでに数分かかることがあります。

Terraform が次のリソースを作成します。

• Kubernetes ノード用のカスタム VPC ネットワークとプライベート サブネット
• ネットワーク アドレス変換（NAT）を介してインターネットにアクセスするための Cloud Router。
• 自動スケーリングを有効にした us-central1 リージョンの限定公開 GKE クラスタ（ゾーンあたり 1～2 ノード）。
• クラスタのロギングとモニタリングの権限を持つ ServiceAccount。
• クラスタのモニタリングおよびアラート用の Google Cloud Managed Service for Prometheus の構成。

出力は次のようになります。

...
Apply complete! Resources: 14 added, 0 changed, 0 destroyed.
...

クラスタに接続する

認証情報を取得し、新しい GKE クラスタと通信できるように kubectl を構成します。

gcloud container clusters get-credentials \
    ${KUBERNETES_CLUSTER_PREFIX}-cluster --location ${REGION} --project ${PROJECT_ID}

CloudNativePG オペレーターをデプロイする

Helm チャートを使用して、CloudNativePG を Kubernetes クラスタにデプロイします。

1. Helm のバージョンを確認します。

   helm version
   

   3.13 より古い場合は、バージョンを更新します。

   curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
   

2. CloudNativePG オペレーターの Helm チャート リポジトリを追加します。

   helm repo add cnpg https://cloudnative-pg.github.io/charts
   

3. Helm コマンドライン ツールを使用して CloudNativePG オペレーターをデプロイします。

   helm upgrade --install cnpg \
       --namespace cnpg-system \
       --create-namespace \
       cnpg/cloudnative-pg
   

   出力は次のようになります。

   Release "cnpg" does not exist. Installing it now.
   NAME: cnpg
   LAST DEPLOYED: Fri Oct 13 13:52:36 2023
   NAMESPACE: cnpg-system
   STATUS: deployed
   REVISION: 1
   TEST SUITE: None
   ...
   

PostgreSQL ベクトル データベースをデプロイする

このセクションでは、PostgreSQL ベクトル データベースをデプロイします。

1. データベースに Namespace pg-ns を作成します。

   kubectl create ns pg-ns
   

2. マニフェストを適用して PostgreSQL クラスタをデプロイします。このクラスタ マニフェストにより、pgvector 拡張機能が有効になります。

   kubectl apply -n pg-ns -f manifests/01-basic-cluster/postgreSQL_cluster.yaml
   

   postgreSQL_cluster.yaml マニフェストには Deployment が記述されています。

   apiVersion: postgresql.cnpg.io/v1
   kind: Cluster
   metadata:
     name: gke-pg-cluster
   spec:
     description: "Standard GKE PostgreSQL cluster"
     imageName: ghcr.io/cloudnative-pg/postgresql:16.2
     enableSuperuserAccess: true
     instances: 3
     startDelay: 300
     primaryUpdateStrategy: unsupervised
     postgresql:
       pg_hba:
         - host all all 10.48.0.0/20 md5
     bootstrap:
       initdb:
         postInitTemplateSQL:
           - CREATE EXTENSION IF NOT EXISTS vector;
         database: app
     storage:
       storageClass: premium-rwo
       size: 2Gi
     resources:
       requests:
         memory: "1Gi"
         cpu: "1000m"
       limits:
         memory: "1Gi"
         cpu: "1000m"
     affinity:
       enablePodAntiAffinity: true
       tolerations:
       - key: cnpg.io/cluster
         effect: NoSchedule
         value: gke-pg-cluster
         operator: Equal
       additionalPodAffinity:
         preferredDuringSchedulingIgnoredDuringExecution:
         - weight: 1
           podAffinityTerm:
             labelSelector:
               matchExpressions:
               - key: app.component
                 operator: In
                 values:
                 - "pg-cluster"
             topologyKey: topology.kubernetes.io/zone
     monitoring:
       enablePodMonitor: true

3. クラスタのステータスを確認します。

   kubectl get cluster -n pg-ns --watch
   

   出力に Cluster in healthy state のステータスが表示されるまで待ってから、次のステップに進みます。

Vertex AI Colab Enterprise ノートブックでクエリを実行する

このセクションでは、ベクトルを PostgreSQL テーブルにアップロードし、SQL 構文を使用してセマンティック検索クエリを実行します。

Colab Enterprise を使用して PostgreSQL データベースに接続します。ノートブックが GKE クラスタ内のリソースと通信できるように、postgres-vpc へのデプロイを行う専用のランタイム テンプレートを使用します。

Vertex AI Colab Enterprise の詳細については、Colab Enterprise のドキュメントをご覧ください。

ランタイム テンプレートを作成する

Colab Enterprise ランタイム テンプレートを作成するには:

1. Google Cloud コンソールで、Colab Enterprise の [ランタイム テンプレート] ページに移動し、プロジェクトが選択されていることを確認します。

   [ランタイム テンプレート] に移動

2. [ 新しいテンプレート] をクリックします。[ランタイム テンプレートの新規作成] ページが表示されます。

3. [ランタイムの基本情報] セクションで、次の操作を行います。

   • [表示名] フィールドに「pgvector-connect」と入力します。
   • [リージョン] プルダウン リストで、us-central1 を選択します。これは、GKE クラスタと同じリージョンです。

4. [コンピューティングの構成] セクションで、次の操作を行います。

   • [マシンタイプ] プルダウン リストで [e2-standard-2] を選択します。
   • [ディスクサイズ] フィールドに「30」と入力します。

5. [ネットワーキングとセキュリティ] セクションで、次の操作を行います。

   • [ネットワーク] プルダウン リストで、GKE クラスタが存在するネットワークを選択します。
   • [サブネットワーク] プルダウン リストで、対応するサブネットワークを選択します。
   • [公共のインターネット アクセスを有効にする] チェックボックスをオフにします。

6. ランタイム テンプレートの作成を完了するには、[作成] をクリックします。ランタイム テンプレートが [ランタイム テンプレート] タブのリストに表示されます。

ランタイムを作成する

Colab Enterprise ランタイムを作成するには:

1. ランタイム テンプレートのリストで、作成したテンプレートの [操作] 列の をクリックし、[ランタイムを作成] をクリックします。[Vertex AI ランタイムの作成] ペインが表示されます。

2. テンプレートに基づいてランタイムを作成するには、[作成] をクリックします。

3. 表示された [ランタイム] タブで、ステータスが「正常」に切り替わるまで待ちます。

ノートブックをインポートする

Colab Enterprise でノートブックをインポートするには:

1. [マイ ノートブック] タブに移動し、[インポート] をクリックします。[ノートブックのインポート] ペインが表示されます。

2. [インポート ソース] で [URL] を選択します。

3. [ノートブックの URL] に、次のリンクを貼り付けます。

   https://raw.githubusercontent.com/epam/kubernetes-engine-samples/internal_lb/databases/postgres-pgvector/manifests/02-notebook/vector-database.ipynb
   

4. [インポート] をクリックします。

ランタイムに接続してクエリを実行する

ランタイムに接続してクエリを実行するには:

1. ノートブックで、[接続] ボタンの横にある [ その他の接続オプション] をクリックします。[Vertex AI ランタイムへの接続] ペインが表示されます。

2. [ランタイムに接続] を選択し、[既存のランタイムに接続] を選択します。

3. 起動したランタイムを選択し、[接続] をクリックします。

4. ノートブック セルを実行するには、各コードセルの横にある [ セルを実行] ボタンをクリックします。

ノートブックには、コードセルと、各コードブロックを説明するテキストの両方が含まれています。コードセルを実行すると、そのコマンドが実行され、出力が表示されます。セルを順番に実行することも、必要に応じて個別に実行することもできます。