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

Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

Google Cloud CLI をインストールします。

注: すでに gcloud CLI をインストールしている場合は、gcloud components update を実行して、最新バージョンがインストールされていることを確認してください。

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

Google Cloud プロジェクトを作成または選択します。

プロジェクトの選択または作成に必要なロール

プロジェクトを選択する: プロジェクトの選択に特定の IAM ロールは必要ありません。ロールが付与されているプロジェクトであれば、どのプロジェクトでも選択できます。
プロジェクトを作成する: プロジェクトを作成するには、resourcemanager.projects.create 権限を含むプロジェクト作成者ロール（roles/resourcemanager.projectCreator）が必要です。ロールを付与する方法を確認する。

Google Cloud プロジェクトを作成します。
```
gcloud projects create PROJECT_ID
```
PROJECT_ID は、作成する Google Cloud プロジェクトの名前に置き換えます。
作成した Google Cloud プロジェクトを選択します。
```
gcloud config set project PROJECT_ID
```
PROJECT_ID は、 Google Cloud プロジェクトの名前に置き換えます。

Google Cloud プロジェクトに対して課金が有効になっていることを確認します。

Cloud Resource Manager、Compute Engine、GKE、IAM Service Account Credentials API を有効にします。

API を有効にするために必要なロール

API を有効にするには、serviceusage.services.enable 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。ロールを付与する方法を確認する。

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

Google Cloud CLI をインストールします。

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

Google Cloud プロジェクトを作成または選択します。

プロジェクトの選択または作成に必要なロール

プロジェクトを選択する: プロジェクトの選択に特定の IAM ロールは必要ありません。ロールが付与されているプロジェクトであれば、どのプロジェクトでも選択できます。
プロジェクトを作成する: プロジェクトを作成するには、resourcemanager.projects.create 権限を含むプロジェクト作成者ロール（roles/resourcemanager.projectCreator）が必要です。ロールを付与する方法を確認する。

Google Cloud プロジェクトを作成します。
```
gcloud projects create PROJECT_ID
```
PROJECT_ID は、作成する Google Cloud プロジェクトの名前に置き換えます。
作成した Google Cloud プロジェクトを選択します。
```
gcloud config set project PROJECT_ID
```
PROJECT_ID は、 Google Cloud プロジェクトの名前に置き換えます。

Google Cloud プロジェクトに対して課金が有効になっていることを確認します。

Cloud Resource Manager、Compute Engine、GKE、IAM Service Account Credentials API を有効にします。

API を有効にするために必要なロール

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

ユーザーアカウントにロールを付与します。次の IAM ロールごとに次のコマンドを 1 回実行します。 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
```
次のように置き換えます。
- PROJECT_ID: プロジェクト ID。
- USER_IDENTIFIER: ユーザーアカウントの識別子。例: myemail@example.com
- ROLE: ユーザーアカウントに付与する IAM ロール。

環境の設定

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 --location ${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 のステータスが表示されるまで待ってから、次のステップに進みます。

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

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

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

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

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

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

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

[ランタイムテンプレート] に移動
[ 新しいテンプレート] をクリックします。[ランタイムテンプレートの新規作成] ページが表示されます。
[ランタイムの基本情報] セクションで、次の操作を行います。
- [表示名] フィールドに「pgvector-connect」と入力します。
- [リージョン] プルダウンリストで、us-central1 を選択します。これは、GKE クラスタと同じリージョンです。
[コンピューティングの構成] セクションで、次の操作を行います。
- [マシンタイプ] プルダウンリストで [e2-standard-2] を選択します。
- [ディスクサイズ] フィールドに「30」と入力します。
[ネットワーキングとセキュリティ] セクションで、次の操作を行います。
- [ネットワーク] プルダウンリストで、GKE クラスタが存在するネットワークを選択します。
- [サブネットワーク] プルダウンリストで、対応するサブネットワークを選択します。
- [公共のインターネットアクセスを有効にする] チェックボックスをオフにします。
ランタイムテンプレートの作成を完了するには、[作成] をクリックします。ランタイムテンプレートが [ランタイムテンプレート] タブのリストに表示されます。

ランタイムを作成する

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

ランタイムテンプレートのリストで、作成したテンプレートの [操作] 列のをクリックし、[ランタイムを作成] をクリックします。[Vertex AI ランタイムの作成] ペインが表示されます。
テンプレートに基づいてランタイムを作成するには、[作成] をクリックします。
表示された [ランタイム] タブで、ステータスが「正常」に切り替わるまで待ちます。

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

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

[マイノートブック] タブに移動し、[インポート] をクリックします。[ノートブックのインポート] ペインが表示されます。
[インポートソース] で [URL] を選択します。

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

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

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

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

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

ノートブックで、[接続] ボタンの横にある [ その他の接続オプション] をクリックします。[Vertex AI ランタイムへの接続] ペインが表示されます。
[ランタイムに接続] を選択し、[既存のランタイムに接続] を選択します。
起動したランタイムを選択し、[接続] をクリックします。
ノートブックセルを実行するには、各コードセルの横にある [ セルを実行] ボタンをクリックします。

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

クリーンアップ

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

プロジェクトを削除する

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

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

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

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

Google Cloud プロジェクトを削除します。

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

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

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

ランタイムを作成する

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

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

クリーンアップ

プロジェクトを削除する

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

次のステップ

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

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

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

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