在 GKE 上部署 PostgreSQL 向量資料庫

自動駕駛標準

本教學課程說明如何在 Google Kubernetes Engine (GKE) 上部署 PostgreSQL 向量資料庫叢集。

PostgreSQL 隨附一系列模組和擴充功能，可擴充資料庫的功能。在本教學課程中，您會在部署至 GKE 的現有 PostgreSQL 叢集上安裝 pgvector 擴充功能。Pgvector 擴充功能可讓您將向量新增至 PostgreSQL，藉此將向量儲存在資料庫表格中。Pgvector 也提供相似度搜尋功能，只要執行常見的 SQL 查詢即可。

我們首先部署 CloudnativePG 運算子，簡化 PGvector 擴充功能部署作業，因為運算子提供擴充功能的套裝組合版本。

本教學課程的適用對象為雲端平台管理員和架構師、機器學習工程師，以及有興趣在 GKE 上部署 PostgreSQL 資料庫叢集的 MLOps (DevOps) 專業人員。

目標

在本教學課程中，您將瞭解以下內容：

為 PostgreSQL 部署 GKE 基礎架構。
在部署至 GKE 的 PostgreSQL 叢集上安裝 pgvector 擴充功能。
使用 Helm 部署及設定 CloudNativePG PostgreSQL 運算子。
上傳示範資料集，並使用 Jupyter Notebook 執行搜尋查詢。

費用

在本文件中，您會使用下列 Google Cloud的計費元件：

如要根據預測用量估算費用，請使用 Pricing Calculator。

初次使用 Google Cloud 的使用者可能符合免費試用期資格。

完成本文所述工作後，您可以刪除建立的資源，避免繼續計費，詳情請參閱「清除所用資源」。

事前準備

在本教學課程中，您將使用 Cloud Shell 執行指令。Cloud Shell 是殼層環境，用於管理託管在 Google Cloud的資源。這個環境已預先安裝 Google Cloud CLI、kubectl、Helm 和 Terraform 指令列工具。如果您未使用 Cloud Shell，則必須安裝 Google Cloud CLI。

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

安裝 Google Cloud CLI。

注意：如果您先前已安裝 gcloud CLI，請執行 gcloud components update，確認您使用的是最新版本。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

建立或選取 Google Cloud 專案。

選取或建立專案所需的角色

選取專案：選取專案時，不需要具備特定 IAM 角色，只要您已獲授角色，即可選取任何專案。
建立專案：如要建立專案，您需要具備專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

建立 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 服務帳戶憑證 API：

啟用 API 時所需的角色

如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

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

安裝 Google Cloud CLI。

注意：如果您先前已安裝 gcloud CLI，請執行 gcloud components update，確認您使用的是最新版本。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

建立或選取 Google Cloud 專案。

選取或建立專案所需的角色

選取專案：選取專案時，不需要具備特定 IAM 角色，只要您已獲授角色，即可選取任何專案。
建立專案：如要建立專案，您需要具備專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

建立 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 服務帳戶憑證 API：

啟用 API 時所需的角色

如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

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

將角色授予使用者帳戶。針對下列每個 IAM 角色，執行一次下列指令： 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：使用者帳戶的 ID。例如：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 資料庫。

您可以選擇使用Standard 或 Autopilot 叢集部署 PostgreSQL。每種都有各自的優點和不同的計費模式。

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 API 的互動
PROJECT_ID、REGION 和 KUBERNETES_CLUSTER_PREFIX 是在「設定環境」一節中定義的環境變數，並指派給您要建立的 Autopilot 叢集的新相關變數。

系統顯示提示訊息時，請輸入 yes。

Terraform 會建立下列資源：

Kubernetes 節點的自訂虛擬私有雲網路和私有子網路。
透過網路位址轉譯 (NAT) 存取網際網路的 Cloud Router。
us-central1 地區的私人 GKE 叢集。
具有叢集記錄和監控權限的 ServiceAccount。
Google Cloud Managed Service for Prometheus 設定，用於叢集監控和快訊。

輸出結果會與下列內容相似：

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

標準

如要部署 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 API 的互動。
PROJECT_ID、REGION 和 KUBERNETES_CLUSTER_PREFIX 是在「設定環境」一節中定義的環境變數，並指派給您要建立的標準叢集相關新變數。

系統顯示提示訊息時，請輸入 yes。這些指令可能需要幾分鐘才能完成，叢集也會在這段時間內顯示就緒狀態。

Terraform 會建立下列資源：

Kubernetes 節點的自訂虛擬私有雲網路和私有子網路。
透過網路位址轉譯 (NAT) 存取網際網路的 Cloud Router。
us-central1 地區中已啟用自動調度的私人 GKE 叢集 (每個區域有一到兩個節點)。
具有叢集記錄和監控權限的 ServiceAccount。
Google Cloud Managed Service for Prometheus 設定，用於叢集監控和快訊。

輸出結果會與下列內容相似：

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

連線至叢集

設定 kubectl，以擷取憑證並與新的 GKE 叢集通訊：

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 向量資料庫。

為資料庫建立命名空間 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 資料庫。您可以使用專屬的執行階段範本部署至 postgres-vpc，因此筆記本可以與 GKE 叢集中的資源通訊。

如要進一步瞭解 Vertex AI Colab Enterprise，請參閱 Colab Enterprise 說明文件。

建立執行階段範本

如要建立 Colab Enterprise 執行階段範本，請按照下列步驟操作：

前往 Google Cloud 控制台的 Colab Enterprise「執行階段範本」頁面，並確認已選取專案：

前往「執行階段範本」
按一下「新增範本」。「建立新的執行階段範本」頁面隨即顯示。
在「執行階段基本資訊」部分：
- 在「Display name」(顯示名稱) 欄位中，輸入 pgvector-connect。
- 在「Region」(區域) 下拉式清單中選取「us-central1」。與 GKE 叢集位於相同區域。
在「設定運算」部分：
- 在「機型」下拉式選單中，選取「e2-standard-2」。
- 在「Disk size」(磁碟大小) 欄位中，輸入 30。
在「網路與安全性」部分中：
- 在「Network」(網路) 下拉式選單中，選取 GKE 叢集所在的網路。
- 在「Subnetwork」(子網路) 下拉式清單中，選取對應的子網路。
- 取消勾選「啟用公開網際網路存取權」核取方塊。
按一下「建立」，完成建立執行階段範本。執行階段範本會顯示在「執行階段範本」分頁的清單中。

建立執行階段

如要建立 Colab Enterprise 執行階段，請按照下列步驟操作：

在剛建立的範本執行階段範本清單中，按一下「動作」欄中的，然後點選「建立執行階段」。「建立 Vertex AI 執行階段」窗格隨即顯示。
如要根據範本建立執行階段，請按一下「建立」。
在開啟的「執行階段」分頁中，等待狀態轉換為「正常」。

匯入筆記本

如要在 Colab Enterprise 中匯入筆記本，請按照下列步驟操作：

前往「我的筆記本」分頁，然後按一下「匯入」。「匯入筆記本」窗格隨即顯示。
在「匯入來源」中選取「網址」。

在「筆記本網址」下方，輸入下列連結：

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

按一下「匯入」。

連線至執行階段並執行查詢

如要連線至執行階段並執行查詢，請按照下列步驟操作：

在筆記本中，按一下「連線」按鈕旁邊的「其他連線選項」。系統隨即會顯示「連線至 Vertex AI 執行階段」窗格。
選取 連線到執行階段，然後選取 連線至現有的執行階段。
選取您啟動的執行階段，然後按一下「連線」。
如要執行筆記本儲存格，請按一下每個程式碼儲存格旁的「Run cell」(執行儲存格) 按鈕。

筆記本包含程式碼儲存格和說明每個程式碼區塊的文字。執行程式碼儲存格會執行指令並顯示輸出內容。您可以依序執行儲存格，也可以視需要執行個別儲存格。

清除所用資源

為避免因為本教學課程所用資源，導致系統向 Google Cloud 收取費用，請刪除含有相關資源的專案，或者保留專案但刪除個別資源。

刪除專案

如要避免付費，最簡單的方法就是刪除您為本教學課程建立的專案。

刪除 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

標準

連線至叢集

部署 CloudNativePG 運算子

部署 PostgreSQL 向量資料庫

使用 Vertex AI Colab Enterprise 筆記本執行查詢

建立執行階段範本

建立執行階段

匯入筆記本

連線至執行階段並執行查詢

清除所用資源

刪除專案

刪除個別資源

後續步驟

在 GKE 上部署 PostgreSQL 向量資料庫