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

Autopilot Standard

このチュートリアルでは、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 で検索クエリを実行する。

費用

このドキュメントでは、Google Cloud の次の課金対象のコンポーネントを使用します。

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。新しい Google Cloud ユーザーは無料トライアルをご利用いただける場合があります。

このドキュメントに記載されているタスクの完了後、作成したリソースを削除すると、それ以上の請求は発生しません。詳細については、クリーンアップをご覧ください。

始める前に

このチュートリアルでは、Cloud Shell を使用してコマンドを実行します。Google Cloud Shell は、Google Cloud でホストされているリソースを管理するためのシェル環境です。これには、Google Cloud CLI、kubectl、Helm、Terraform コマンドラインツールがプリインストールされています。Cloud Shell を使用しない場合は、Google Cloud CLI をインストールする必要があります。

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

To initialize the gcloud CLI, run the following command:

gcloud init

Note: If you installed the gcloud CLI previously, make sure you have the latest version by running

gcloud components
      update

Create or select a Google Cloud project.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Make sure that billing is enabled for your Google Cloud project.

Enable the Cloud Resource Manager, Compute Engine, GKE, and IAM Service Account Credentials APIs:

gcloud services enable cloudresourcemanager.googleapis.com compute.googleapis.com container.googleapis.com iamcredentials.googleapis.com

Install the Google Cloud CLI.

To initialize the gcloud CLI, run the following command:

gcloud init

Note: If you installed the gcloud CLI previously, make sure you have the latest version by running

gcloud components
      update

Create or select a Google Cloud project.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Make sure that billing is enabled for your Google Cloud project.

Enable the Cloud Resource Manager, Compute Engine, GKE, and IAM Service Account Credentials APIs:

gcloud services enable cloudresourcemanager.googleapis.com compute.googleapis.com container.googleapis.com iamcredentials.googleapis.com

Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/compute.securityAdmin, roles/compute.viewer, roles/container.clusterAdmin, roles/container.admin, roles/iam.serviceAccountAdmin, roles/iam.serviceAccountUser
```
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
```
- Replace PROJECT_ID with your project ID.
- Replace USER_IDENTIFIER with the identifier for your user account. For example, user:myemail@example.com.
- Replace ROLE with each individual role.

環境を設定する

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

プロジェクト、リージョン、Kubernetes クラスタリソースの接頭辞に環境変数を設定します。
```
export PROJECT_ID=PROJECT_ID
export KUBERNETES_CLUSTER_PREFIX=postgres
export REGION=us-central1
```
- PROJECT_ID は、実際の Google Cloud プロジェクト ID に置き換えます。
このチュートリアルでは、us-central1 リージョンを使用します。
GitHub からサンプルコードリポジトリのクローンを作成します。
```
git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples
```

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 --region ${REGION} --project ${PROJECT_ID}

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

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

Helm のバージョンを確認します。
```
helm version
```
3.13 より古い場合は、バージョンを更新します。
```
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
```
CloudNativePG オペレーターの Helm チャートリポジトリを追加します。
```
helm repo add cnpg https://cloudnative-pg.github.io/charts
```

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 ベクトルデータベースをデプロイします。

データベースに Namespace pg-ns を作成します。
```
kubectl create ns pg-ns
```

マニフェストを適用して 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

クラスタのステータスを確認します。
```
kubectl get cluster -n pg-ns --watch
```
出力に Cluster in healthy state のステータスが表示されるまで待ってから、次のステップに進みます。

デモデータセットをアップロードして Jupyter Notebook で検索クエリを実行する

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

次の例では、さまざまなジャンルの書籍のリストを含む CSV ファイルのデータセットを使用します。pgvector は検索エンジンとして機能し、作成した Pod は PostgreSQL データベースをクエリするクライアントとして機能します。

PostgreSQL リーダー Pod が作成されて準備ができるまで待ちます。

while [[ $(kubectl get pod -l cnpg.io/cluster=gke-pg-cluster,role=primary -n pg-ns -o 'jsonpath={..status.conditions[?(@.type=="Ready")].status}') != "True" ]]; do
sleep 5
done

books-dataset を使用して Configmap を作成し、Jupyter Pod を実行して PostgreSQL クラスタを操作します。

kubectl create -n pg-ns configmap books-dataset --from-file=manifests/02-notebook/dataset.csv
kubectl create -n pg-ns configmap notebook --from-file=manifests/02-notebook/vector-database.ipynb
kubectl apply -n pg-ns -f manifests/02-notebook/jupyter.yaml

CloudNativePG オペレーターによって作成された gke-pg-cluster-superuser という名前の Secret が、CLIENTUSERNAME と CLIENTPASSWORD. という環境変数としてクライアント Pod にマウントされます。
books-dataset ConfigMap には、PostgreSQL データベースの書籍データを含む csv ファイルが含まれています。
demo-app ConfigMap には、books-dataset から PostgreSQL テーブルを作成する Python コードが含まれています。

jupyter.yaml マニフェストには、notebook Deployment とその Service が記述されています。

---
apiVersion: v1
kind: Service
metadata:
  labels: &labels
    app: jupyter-notebook
  name: notebook
spec:
  ports:
  - port: 8888
  selector: *labels
  type: LoadBalancer
  # type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: notebook
  labels: &labels
    app: jupyter-notebook
spec:
  selector:
    matchLabels: *labels
  template:
    metadata: 
      labels: *labels
    spec:
      containers:
      - name: jupyter
        image: tensorflow/tensorflow:2.15.0-jupyter
        resources:
          requests:
            memory: "4500Mi"
            cpu: "1"
          limits:
            memory: "4500Mi"
            cpu: "1"
        ports:
        - containerPort: 8888
        env:
        - name: CLIENTPASSWORD
          valueFrom:
            secretKeyRef:
              name: gke-pg-cluster-superuser
              key: password
        - name: CLIENTUSERNAME
          valueFrom:
            secretKeyRef:
              name: gke-pg-cluster-superuser
              key: username
        volumeMounts:
        - name: books-dataset
          mountPath: /usr/local/dataset
        - name: notebook
          mountPath: /tf
      volumes:
      - name: books-dataset
        configMap:
          name: books-dataset
      - name: notebook
        configMap:
          name: notebook

GKE が Jupyter Pod を起動するまで待ちます。

kubectl wait pods -l app=jupyter-notebook --for condition=Ready --timeout=300s -n pg-ns

Jupyter に接続するためのアクセストークンを含む URL を取得します。

export EXTERNAL_IP=$(kubectl -n pg-ns get svc notebook --output jsonpath='{.status.loadBalancer.ingress[0].ip}')
kubectl logs deploy/notebook -n pg-ns| grep '^ .*http://127'|sed "s|127.0.0.1|${EXTERNAL_IP}|"

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

http://34.123.21.1:8888/tree?token=a1d48d3531c48328695d6901004c94060aa0aa3554ff7463

この URL を開き、vector-database.ipynb ファイルをクリックします。

[Run] > [Run all cells] をクリックします。Jupyter がコードを実行し、テキスト drama about people and unhappy love の検索クエリを実行します。

このクエリは、PostgreSQL の documents テーブルにセマンティック検索を行い、クエリに関連する一致スコアが最も高い検索結果を最大 2 件取得します。

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

Title: Romeo and Juliet, Author: William Shakespeare, Paul Werstine (Editor),
Barbara A. Mowat (Editor), Paavo Emil Cajander (Translator)
In Romeo and Juliet, Shakespeare creates a violent world, in which two young
people fall in love. It is not simply that their families disapprove; the Montagues
and the Capulets are engaged in a blood feud.In this death-filled setting, the
movement from love at first sight to the lovers' final union in death seems
almost inevitable. And yet, this play set in an extraordinary world has become
the quintessential story of young love. In part because of its exquisite language,
it is easy to respond as if it were about all young lovers.
---------
Title: A Midsummer Night's Dream, Author: William Shakespeare, Paul Werstine (Editor),
Barbara A. Mowat (Editor), Catherine Belsey (Contributor)
Shakespeare's intertwined love polygons begin to get complicated from the start--Demetrius
and Lysander both want Hermia but she only has eyes for Lysander. Bad news is,
Hermia's father wants Demetrius for a son-in-law. On the outside is Helena,
whose unreturned love burns hot for Demetrius. Hermia and Lysander plan to flee
from the city under cover of darkness but are pursued by an enraged Demetrius
(who is himself pursued by an enraptured Helena). In the forest, unbeknownst
to the mortals, Oberon and Titania (King and Queen of the faeries) are having
a spat over a servant boy. The plot twists up when Oberon's head mischief-maker,
Puck, runs loose with a flower which causes people to fall in love with the
first thing they see upon waking. Throw in a group of labourers preparing a
play for the Duke's wedding (one of whom is given a donkey's head and Titania
for a lover by Puck) and the complications become fantastically funny.
---------

クリーンアップ

このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。

プロジェクトを削除する

課金が発生しないようにする最も簡単な方法は、このチュートリアル用に作成したプロジェクトを削除することです。

注意: プロジェクトを削除すると、次のような影響があります。

プロジェクト内のすべてのものが削除されます。このドキュメントのタスクで既存のプロジェクトを使用した場合、それを削除すると、そのプロジェクトで行った他の作業もすべて削除されます。
カスタムプロジェクト ID が失われます。このプロジェクトを作成したときに、将来使用するカスタムプロジェクト ID を作成した可能性があります。そのプロジェクト ID を使用した URL（たとえば、appspot.com）を保持するには、プロジェクト全体ではなくプロジェクト内の選択したリソースだけを削除します。

複数のアーキテクチャ、チュートリアル、クイックスタートを実施する予定がある場合は、プロジェクトを再利用すると、プロジェクトの割り当て上限を超えないようにすることができます。

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

プロジェクトを削除すると、クリーンアップが完了します。プロジェクトを削除していない場合は、個々のリソースを削除します。

リソースを個別に削除する

環境変数を設定します。

export PROJECT_ID=${PROJECT_ID}
export KUBERNETES_CLUSTER_PREFIX=postgres
export REGION=us-central1

terraform destroy コマンドを実行します。

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

作成した GKE クラスタのタイプに応じて、FOLDER を gke-autopilot または gke-standard に置き換えます。

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

次のステップ

CloudNativePG オペレーターを使用して GKE に PostgreSQL クラスタをデプロイする方法を確認する。
GKE にデータベースをデプロイするためのベストプラクティスについて学習する。
GKE でデータ量の多いワークロードを実行するためのソリューションを確認する。

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

目標

費用

始める前に

環境を設定する

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

Autopilot

Standard

クラスタに接続する

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

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

デモ データセットをアップロードして Jupyter Notebook で検索クエリを実行する

クリーンアップ

プロジェクトを削除する

リソースを個別に削除する

次のステップ

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

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

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

デモデータセットをアップロードして Jupyter Notebook で検索クエリを実行する