このチュートリアルでは、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コンポーネントを使用します。
料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。
このドキュメントに記載されているタスクの完了後、作成したリソースを削除すると、それ以上の請求は発生しません。詳細については、クリーンアップをご覧ください。
始める前に
このチュートリアルでは、Cloud Shell を使用してコマンドを実行します。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.
-
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
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.
-
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
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.
- Replace
環境の設定
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 が記述されています。クラスタのステータスを確認します。
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 の [ランタイム テンプレート] ページに移動し、プロジェクトが選択されていることを確認します。
[add_box 新しいテンプレート] をクリックします。[ランタイム テンプレートの新規作成] ページが表示されます。
[ランタイムの基本情報] セクションで、次の操作を行います。
- [表示名] フィールドに「
pgvector-connect
」と入力します。 - [リージョン] プルダウン リストで、
us-central1
を選択します。これは、GKE クラスタと同じリージョンです。
- [表示名] フィールドに「
[コンピューティングの構成] セクションで、次の操作を行います。
- [マシンタイプ] プルダウン リストで [
e2-standard-2
] を選択します。 - [ディスクサイズ] フィールドに「
30
」と入力します。
- [マシンタイプ] プルダウン リストで [
[ネットワーキングとセキュリティ] セクションで、次の操作を行います。
- [ネットワーク] プルダウン リストで、GKE クラスタが存在するネットワークを選択します。
- [サブネットワーク] プルダウン リストで、対応するサブネットワークを選択します。
- [公共のインターネット アクセスを有効にする] チェックボックスをオフにします。
ランタイム テンプレートの作成を完了するには、[作成] をクリックします。ランタイム テンプレートが [ランタイム テンプレート] タブのリストに表示されます。
ランタイムを作成する
Colab Enterprise ランタイムを作成するには:
ランタイム テンプレートのリストで、作成したテンプレートの [操作] 列の more_vert をクリックし、[ランタイムを作成] をクリックします。[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
[インポート] をクリックします。
ランタイムに接続してクエリを実行する
ランタイムに接続してクエリを実行するには:
ノートブックで、[接続] ボタンの横にある [arrow_drop_down その他の接続オプション] をクリックします。[Vertex AI ランタイムへの接続] ペインが表示されます。
[ランタイムに接続] を選択し、[既存のランタイムに接続] を選択します。
起動したランタイムを選択し、[接続] をクリックします。
ノートブック セルを実行するには、各コードセルの横にある [
セルを実行] ボタンをクリックします。
ノートブックには、コードセルと、各コードブロックを説明するテキストの両方が含まれています。コードセルを実行すると、そのコマンドが実行され、出力が表示されます。セルを順番に実行することも、必要に応じて個別に実行することもできます。
クリーンアップ
このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。
プロジェクトを削除する
課金が発生しないようにする最も簡単な方法は、このチュートリアル用に作成したプロジェクトを削除することです。
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 でデータ量の多いワークロードを実行するためのソリューションを確認する。