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 で検索クエリを実行する。

費用

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

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

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

始める前に

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

  1. 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.
  2. Install the Google Cloud CLI.

  3. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  4. To initialize the gcloud CLI, run the following command:

    gcloud init
  5. 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.

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

  7. 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
  8. Install the Google Cloud CLI.

  9. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  10. To initialize the gcloud CLI, run the following command:

    gcloud init
  11. 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.

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

  13. 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
  14. 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 を使用して環境を設定するには、次の操作を行います。

  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_IDREGIONKUBERNETES_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_IDREGIONKUBERNETES_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 クラスタにデプロイします。

  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. ノートブック セルを実行するには、各コードセルの横にある [ セルを実行] ボタンをクリックします。

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

クリーンアップ

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

プロジェクトを削除する

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

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

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

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

  1. 環境変数を設定します。

    export PROJECT_ID=${PROJECT_ID}
    export KUBERNETES_CLUSTER_PREFIX=postgres
    export REGION=us-central1
    
  2. 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 クラスタのタイプに応じて、FOLDERgke-autopilot または gke-standard に置き換えます。

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

次のステップ