從 Google Kubernetes Engine (GKE) 連線至 PostgreSQL 適用的 AlloyDB

如要將 Google Kubernetes Engine Autopilot 叢集中的容器化應用程式，安全地連線至 AlloyDB for PostgreSQL 執行個體，您可以透過私人 IP 網路連線，將 AlloyDB Auth Proxy 部署為邊車容器。

AlloyDB 是 Google Cloud中與 PostgreSQL 相容的全代管資料庫服務，Google Kubernetes Engine 則可協助您自動部署、擴充及管理 Kubernetes 工作負載。

目標

• 建構 AlloyDB 的 Docker 映像檔。
• 在 Google Kubernetes Engine 執行應用程式。
• 使用 AlloyDB Auth Proxy 和內部 IP 連線至 AlloyDB 執行個體。

費用

本教學課程使用 Google Cloud的計費元件，包括：

• AlloyDB
• Google Kubernetes Engine
• Artifact Registry

您可以使用 Pricing Calculator 來根據預測使用量產生預估費用。

事前準備

控制台

登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎 建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. 確認您具備完成本教學課程所需的權限。

2. 啟用建立及連線至 AlloyDB 所需的 Cloud API。

   啟用 API

   1. 在「確認專案」步驟中，點選「下一步」，確認要變更的專案名稱。

   2. 在「啟用 API」步驟中，點選「啟用」來啟用下列項目：

      • AlloyDB API
      • Artifact Registry API
      • Compute Engine API
      • Cloud Resource Manager API
      • Cloud Build API
      • Kubernetes Engine API
      • Service Networking API
   注意：如果您已啟用上述任何或所有 API，這些 API 就不會列在這裡。

gcloud

登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎 建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. 確認您具備完成本教學課程所需的權限。

在本教學課程中，請使用名為 gke-alloydb-app 的投票收集網頁應用程式範例。

必要的角色

如要取得完成本教學課程中各項工作所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

• 資料庫管理員 (roles/iam.databasesAdmin)
• Kubernetes Engine 叢集管理員 (roles/container.clusterAdmin)
• 專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin)
• Kubernetes Engine 管理員 (roles/container.admin)
• Artifact Registry 管理員 (roles/artifactregistry.admin)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

啟動 Cloud Shell

Cloud Shell 是一種殼層環境，可用來管理託管於Google Cloud的資源。

Cloud Shell 已預先安裝 Google Cloud CLI 和 kubectl 指令列工具。gcloud CLI 提供 Google Cloud的主要指令列介面。kubectl 提供主要指令列介面，用於對 Kubernetes 叢集執行指令。

控制台

如要啟動 Cloud Shell，請完成下列步驟。

1. 前往 Google Cloud 控制台。

   Google Cloud console

2. 按一下 Google Cloud 控制台頂端的「Activate Cloud Shell」(啟用 Cloud Shell) 圖示 。

3. 在「授權 Cloud Shell」對話方塊中，點選「授權」。

   此時 Cloud Shell 工作階段會在主控台底部的頁框中開啟，請使用這個殼層來執行 gcloud 和 kubectl 指令。

   1. 執行指令前，請先使用下列指令，在 Google Cloud CLI 設定預設專案：

      gcloud config set project PROJECT_ID

      將 PROJECT_ID 替換為專案 ID。

gcloud

1. 如要啟動 Cloud Shell，請完成下列步驟。

2. 在 Google Cloud 控制台啟用 Cloud Shell。

   啟用 Cloud Shell

   Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。

3. 如要初始化環境，請使用下列指令，在 Google Cloud CLI 中設定預設專案：

   gcloud config set project PROJECT_ID

   將 PROJECT_ID 替換為專案 ID。

4. 啟用必要的 Cloud API，以便建立及連線至 AlloyDB for PostgreSQL。

   gcloud services enable alloydb.googleapis.com \
       compute.googleapis.com \
       cloudresourcemanager.googleapis.com \
       cloudbuild.googleapis.com \
       servicenetworking.googleapis.com \
       artifactregistry.googleapis.com \
       container.googleapis.com

注意： 如果您已啟用部分或所有 API，這些 API 就不會列在這裡。

建立 AlloyDB 叢集及其主要執行個體

AlloyDB 叢集包含 Google 虛擬私有雲 (VPC) 中的多個節點。建立叢集時，您也必須在其中一個虛擬私有雲網路，與包含新叢集的 Google 代管虛擬私有雲網路之間，設定私人服務存取權。使用內部 IP 存取權，避免資料庫暴露在公開網際網路上。

如要從設定的虛擬私有雲網路外部連線至 AlloyDB for PostgreSQL 叢集，請在虛擬私有雲中為 AlloyDB 設定私人服務存取權，並使用預設虛擬私有雲網路，從部署在 GKE 叢集的應用程式執行查詢。

控制台

1. 前往「Clusters」(叢集) 頁面。

   前往叢集

2. 在「設定叢集」部分的「叢集 ID」欄位，輸入叢集 ID。開頭須為小寫英文字母，可以使用小寫英文字母、數字和連字號，例如 alloydb-cluster。

3. 在「Password」(密碼) 欄位中，輸入建立叢集時要用於預設 postgres 資料庫使用者的 CLUSTER_PASSWORD。

4. 在「Database version」(資料庫版本) 欄位中，選取新 AlloyDB 叢集的主要 POSTGRES_VERSION。

5. 為叢集選取REGION，例如 us-central1。

6. 在「Configure your primary instance」(設定主要執行個體) 部分，執行下列操作：

   1. 在「Instance ID」(執行個體 ID) 欄位中，輸入主要執行個體的 INSTANCE_ID，例如 alloydb-primary。

   2. 選取機器系列，例如 N2。

   3. 選取機器類型，並指定虛擬處理單元 NUM_CPU 的數量，例如 2。

   4. 如要將 IP 範圍指派給服務對接，請設定私人服務存取連線：

      1. 在「Network」(網路) 清單中，選取「default」。

      2. 如果已預留 default-ip-range 等 IP 範圍，請從「Allocated IP range」(已分配的 IP 範圍) 清單中選取。

      3. 如果未指派 IP 範圍，請按一下「分配自訂 IP 範圍」，分配新的內部 IP_RANGE_NAME 並設定連線。

7. 點選「建立叢集」。

等待 AlloyDB 執行個體建立完成。這項作業可能需要幾分鐘才能完成。

gcloud

1. 在 Cloud Shell 中，檢查未使用的 IP 位址 (IPv4) 範圍是否已指派給服務對接：

   gcloud services vpc-peerings list --network=default

   如果輸出內容與下方類似，請略過下一個步驟：

   network: projects/493573376485/global/networks/default
   peering: servicenetworking-googleapis-com
   reservedPeeringRanges:
   - default-ip-range
   service: services/servicenetworking.googleapis.com
   

   在這項輸出內容中，reservedPeeringRanges 的值為 default-ip-range，您可以在步驟 3 中將其做為 IP_RANGE_NAME，建立私人連線。

2. (如果使用預設值 reservedPeeringRanges，請略過這個步驟) 如要分配虛擬私有雲中未使用的 IP 位址，請使用下列指令：

   gcloud compute addresses create IP_RANGE_NAME \
       --global \
       --purpose=VPC_PEERING \
       --prefix-length=16 \
       --description="VPC private service access" \
       --network=default

   將 IP_RANGE_NAME 替換為 AlloyDB 子網路內可用內部 IP 位址的名稱，例如 alloydb-gke-psa-01。

3. 如要使用分配的 IP 範圍設定服務存取權，請執行下列指令：

   gcloud services vpc-peerings connect \
       --service=servicenetworking.googleapis.com \
       --ranges=IP_RANGE_NAME \
       --network=default

4. 執行下列指令，部署 AlloyDB 叢集：

   gcloud alloydb clusters create CLUSTER_ID \
       --database-version=POSTGRES_VERSION \
       --password=CLUSTER_PASSWORD \
       --network=default \
       --region=REGION \
       --project=PROJECT_ID

   更改下列內容：

   • CLUSTER_ID：您要建立的叢集 ID。開頭須為小寫英文字母，且只能使用小寫英文字母、數字和連字號，例如 alloydb-cluster。

   • VERSION：叢集資料庫伺服器應相容的 PostgreSQL 主要版本。選擇下列其中一個選項：

     • 14：與 PostgreSQL 14 相容

     • 15：與 PostgreSQL 15 相容

     • 16：與 PostgreSQL 16 相容

     • 17：與 PostgreSQL 17 相容，這是支援的預設 PostgreSQL 版本

     • 18，與 PostgreSQL 18 相容

   • CLUSTER_PASSWORD：預設 postgres 使用者的密碼。

   • PROJECT_ID：要放置叢集的 Google Cloud 專案 ID。

   • REGION：建立 AlloyDB 叢集的區域名稱，例如 us-central1。

5. 執行下列指令，部署 AlloyDB 主要執行個體：

   gcloud alloydb instances create INSTANCE_ID \
       --instance-type=PRIMARY \
       --cpu-count=NUM_CPU \
       --region=REGION \
       --cluster=CLUSTER_ID \
       --project=PROJECT_ID

   更改下列內容：

   • INSTANCE_ID：您選擇的 AlloyDB 執行個體名稱，例如 alloydb-primary。
   • CLUSTER_ID：AlloyDB 叢集的名稱，例如 alloydb-cluster。
   • 將 NUM_CPU 替換為虛擬處理單元數量，例如 2。
   • 將 PROJECT_ID 替換為 Google Cloud 專案 ID。
   • REGION：AlloyDB 叢集建立所在區域的名稱，例如 us-central1。

   等待 AlloyDB 執行個體建立完成。這項作業可能需要幾分鐘才能完成。

連線至主要執行個體，並建立 AlloyDB 資料庫和使用者

如要在主要執行個體建立資料庫和資料庫使用者，請完成下列步驟：

控制台

1. 如果不在新建立叢集的「總覽」頁面，請前往 Google Cloud 控制台的「叢集」頁面。

   前往「Clusters」(叢集) 頁面

2. 如要顯示叢集的「總覽」頁面，請按一下 CLUSTER_ID 叢集名稱。

3. 在導覽選單中，點選「AlloyDB Studio」。

4. 在「Sign in to AlloyDB Studio」(登入 AlloyDB Studio) 頁面，執行下列操作：

   1. 在「Database」(資料庫) 清單中，選取「postgres」。

   2. 在「User」(使用者) 清單中，選取「postgres」。

   3. 在「Password」(密碼) 欄位中，輸入您在「建立 AlloyDB 叢集及其主要執行個體」中建立的 CLUSTER_PASSWORD。

   4. 按一下「Authenticate」(驗證)。「Explorer」窗格會顯示資料庫中的物件清單。

5. 在「Editor 1」(編輯器 1) 分頁中，完成下列操作：

   1. 建立 AlloyDB 資料庫：

      CREATE DATABASE DATABASE_NAME;
      

      將 DATABASE_NAME 替換成您選擇的名稱，例如 tutorial_db。

   2. 按一下「執行」。等待「結果」窗格顯示 Statement executed successfully 訊息。

   3. 按一下「清除」。

   4. 建立 AlloyDB 資料庫使用者和密碼：

      CREATE USER USERNAME WITH PASSWORD 'DATABASE_PASSWORD';
      

      更改下列內容：

      • USERNAME：AlloyDB 使用者名稱，例如 tutorial_user。

      • DATABASE_PASSWORD：AlloyDB 資料庫的密碼，例如 tutorial。

   5. 按一下「執行」。等待「結果」窗格顯示 Statement executed successfully 訊息。

6. 在 AlloyDB Studio 的「Explorer」窗格中，點選「 切換使用者/資料庫」。

7. 在「Sign in to AlloyDB Studio」(登入 AlloyDB Studio) 頁面，執行下列操作：

   1. 在「Database」(資料庫) 清單中，選取 DATABASE_NAME，例如 tutorial_db。

   2. 在「User」(使用者) 清單中，選取「postgres」。

   3. 在「Password」(密碼) 欄位中，輸入您在「建立 AlloyDB 叢集及其主要執行個體」中建立的 CLUSTER_PASSWORD。

   4. 按一下「Authenticate」(驗證)。「Explorer」窗格會顯示資料庫中的物件清單。

8. 在「Editor 1」(編輯器 1) 分頁中，完成下列操作：

   1. 將所有權限授予 AlloyDB 資料庫使用者：

      GRANT ALL PRIVILEGES ON DATABASE "DATABASE_NAME" to "USERNAME";
      

   2. 按一下「執行」。等待「結果」窗格顯示 Statement executed successfully 訊息。

   3. 按一下「清除」。

   4. 授予 AlloyDB 資料庫使用者公開結構定義的權限：

      GRANT CREATE ON SCHEMA public TO "USERNAME";
      

   5. 按一下「執行」。等待「結果」窗格顯示 Statement executed successfully 訊息。

9. 記下資料庫名稱、使用者名稱和密碼。您會在「建立 Kubernetes Secret」中使用這項資訊。

gcloud

1. 在 Cloud Shell 執行下列指令，建立 AlloyDB 資料庫使用者：

   gcloud alloydb users create USERNAME \
       --cluster=CLUSTER_ID \
       --region=REGION \
       --password=DATABASE_PASSWORD

   更改下列內容：

   • USERNAME：AlloyDB 使用者名稱，例如 tutorial_user。
   • CLUSTER_ID：叢集 ID，例如 alloydb-cluster。
   • REGION：叢集所在的區域，例如 us-central1。
   • DATABASE_PASSWORD：AlloyDB 資料庫的密碼，例如 tutorial。

2. 如要建立資料庫並授予權限，您必須連線至叢集並執行 SQL 指令。在 Cloud Shell 中，使用 psql 用戶端連線至執行個體。

   注意： 如要從 Cloud Shell 連線至 AlloyDB 執行個體，必須使用 AlloyDB Auth Proxy。如要簡化設定，您可以在 Google Cloud 控制台中使用 AlloyDB Studio 執行這些步驟。

3. 以 postgres 使用者身分連線至執行個體後，請建立資料庫：

   CREATE DATABASE DATABASE_NAME;
   

   將 DATABASE_NAME 替換成您選擇的名稱，例如 tutorial_db。

4. 將新資料庫的所有權限授予 AlloyDB 資料庫使用者：

   GRANT ALL PRIVILEGES ON DATABASE "DATABASE_NAME" to "USERNAME";
   

5. 連線至新資料庫，並授予 public 結構定義的權限：

   \c DATABASE_NAME
   GRANT CREATE ON SCHEMA public TO "USERNAME";
   

6. 記下資料庫名稱、使用者名稱和密碼。您會在「建立 Kubernetes Secret」中使用這項資訊。

建立 GKE Autopilot 叢集

一個叢集至少包含一個叢集控制層機器，以及多個稱為節點的工作站機器。節點是 Compute Engine 虛擬機器 (VM) 執行個體，會執行必要的 Kubernetes 程序，才能加入叢集。當您將應用程式部署至叢集之後，該應用程式就會在節點上執行。

控制台

1. 在 Google Cloud 控制台中，前往「Kubernetes Clusters」(Kubernetes 叢集) 頁面。

   開啟 Kubernetes 叢集清單

2. 點選「建立」。

3. 在「叢集基本資訊」頁面的「名稱」欄位中，為 Autopilot 叢集指定 GKE_CLUSTER_ID，例如 ap-cluster。

4. 在「Region」(區域) 欄位中，選取 REGION，例如 us-central1。

5. 點選「建立」。

   等待 GKE 叢集建立完成。這項作業可能需要幾分鐘才能完成。

gcloud

建立 Autopilot 叢集：

gcloud container clusters create-auto GKE_CLUSTER_ID \
    --location=REGION

更改下列內容：

• GKE_CLUSTER_ID：Autopilot 叢集的名稱，例如 ap-cluster。
• REGION：部署 GKE 叢集的區域名稱，例如 us-central1。

等待 GKE 叢集建立完成。這項作業可能需要幾分鐘才能完成。

使用 AlloyDB Auth Proxy 連線至 AlloyDB

使用 AlloyDB Auth Proxy 連線至 AlloyDB。AlloyDB Auth Proxy 使用 Identity and Access Management (IAM) 提供強大的加密和驗證功能，有助於保護資料庫安全。

使用 AlloyDB Auth Proxy 連線時，系統會透過 sidecar 容器模式，將 Proxy 新增至 Pod。AlloyDB Auth Proxy 容器與應用程式位於同一個 Pod，因此應用程式可以使用 localhost 連線至 AlloyDB Auth Proxy，提高安全性和效能。

將 Artifact Registry 存取權授予預設 Compute Engine 服務帳戶

將 Artifact Registry 讀取者 (roles/artifactregistry.reader) 角色授予預設 Compute Engine 服務帳戶，讓 Google Kubernetes Engine 節點可以從 Artifact Registry 提取容器映像檔。

控制台

1. 前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面。

   前往「IAM」頁面

2. 在「專案『PROJECT_ID』的權限」頁面中，找出含有預設運算服務帳戶 [e-mail] 的資料列，然後按一下該列中的 「編輯主體」。

   如要取得系統為專案自動產生的專屬 ID PROJECT_NUMBER，請按照下列步驟操作：

   1. 前往 Google Cloud 控制台的「Dashboard」(資訊主頁) 頁面。

      前往資訊主頁

   2. 點選頁面頂端的「Select from」下拉式選單，在隨即顯示的「Select from」(選取來源) 視窗中，選取所需專案。

   PROJECT_NUMBER 會顯示在專案資訊主頁的「專案資訊」資訊卡中。

3. 按一下 「Add another role」(新增其他角色)。

4. 如要授予 roles/artifactregistry.reader 角色，請按一下「選取角色」，然後從「依產品或服務」中選擇「Artifact Registry」，並從「角色」中選擇「Artifact Registry Reader」。

5. 按一下 [儲存]。主體就會取得該角色。

gcloud

將專案的 Artifact Registry 讀取者角色 (roles/artifactregistry.reader) 授予預設的 Compute Engine 服務帳戶：

PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:$[e-mail]" \
    --role="roles/artifactregistry.reader" \
    --condition=None

將 PROJECT_ID 替換為專案 ID。

為範例應用程式設定 Workload Identity Federation for GKE

設定 Google Kubernetes Engine，使用 Workload Identity Federation for GKE 驗證 AlloyDB Auth Proxy。使用 GKE 適用的 Workload Identity Federation 時，您可以在 Google Kubernetes Engine 叢集中為應用程式建立 Kubernetes ServiceAccount，並將 IAM 角色授予該 Kubernetes ServiceAccount。為每個應用程式建立專屬的 Kubernetes ServiceAccount，以便限制個別應用程式的權限。

控制台

1. 如要啟動 Cloud Shell，請完成下列步驟。

2. 在 Google Cloud 控制台啟用 Cloud Shell。

   啟用 Cloud Shell

   Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。

3. 在 Cloud Shell 中取得叢集的憑證：

   gcloud container clusters get-credentials GKE_CLUSTER_ID --region REGION --project PROJECT_ID

   這項指令會設定 kubectl，使用您建立的 GKE 叢集。

4. 在您選擇的編輯器中，完成下列步驟：

   1. 使用 nano 開啟 service-account.yaml，例如：

      nano service-account.yaml

   2. 在編輯器中貼上以下內容：

      apiVersion: v1
      kind: ServiceAccount
      metadata:
        name: KUBERNETES_SERVICEACCOUNT
      

      將 KUBERNETES_SERVICEACCOUNT 替換為 Kubernetes ServiceAccount 名稱，例如 alloydb-sa。

   3. 依序按下 Control+O 和 Enter 鍵儲存變更，然後按下 Control+X 鍵退出編輯器。

5. 為範例應用程式建立 Kubernetes ServiceAccount：

   kubectl apply -f service-account.yaml

6. 如要將 IAM 角色授予 Kubernetes ServiceAccount，請在 Google Cloud 控制台中完成下列步驟：

   1. 前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面。

      前往「IAM」頁面

   2. 選取專案。

   3. 按一下「授予存取權」。

   4. 在「New principals」(新增主體) 欄位中輸入下列內容：

      principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/default/sa/KUBERNETES_SERVICEACCOUNT

      更改下列內容：

      • PROJECT_NUMBER：您的專案編號。
      • PROJECT_ID：您的專案 ID。
      • KUBERNETES_SERVICEACCOUNT：Kubernetes ServiceAccount 名稱，例如 alloydb-sa。

   5. 如要授予 roles/alloydb.client 角色，請在「Select a role」(選取角色) 清單中，依序選擇「AlloyDB for PostgreSQL」 >「AlloyDB Client」(AlloyDB 用戶端)。

   6. 按一下 「Add another role」(新增其他角色)。

   7. 如要授予 roles/serviceusage.serviceUsageConsumer 角色，請在「Select a role」(選取角色) 清單中，依序選擇「Service Usage」(服務使用情形) >「Service Usage Consumer」(服務使用情形消費者)。

   8. 按一下 [儲存]。

gcloud

1. 在 Google Cloud 控制台中開啟 Cloud Shell。

   開啟 Cloud Shell

2. 在 Cloud Shell 中取得叢集的憑證：

   gcloud container clusters get-credentials GKE_CLUSTER_ID --region REGION --project PROJECT_ID

   這項指令會設定 kubectl，使用您建立的 GKE 叢集。

3. 在您選擇的編輯器中，完成下列步驟：

   1. 使用 nano 開啟 service-account.yaml，例如：

      nano service-account.yaml

   2. 在編輯器中貼上以下內容：

      apiVersion: v1
      kind: ServiceAccount
      metadata:
        name: KUBERNETES_SERVICEACCOUNT
      

      將 KUBERNETES_SERVICEACCOUNT 替換為 Kubernetes ServiceAccount 名稱，例如 alloydb-sa。

   3. 依序按下 Control+O 和 Enter 鍵儲存變更，然後按下 Control+X 鍵退出編輯器。

4. 為範例應用程式建立 Kubernetes ServiceAccount：

   kubectl apply -f service-account.yaml

5. 將專案的 AlloyDB 用戶端 (roles/alloydb.client) 和服務使用情形消費者 (roles/serviceusage.serviceUsageConsumer) 角色授予 Kubernetes ServiceAccount：

   PROJECT_ID="PROJECT_ID"
   KUBERNETES_SERVICEACCOUNT="KUBERNETES_SERVICEACCOUNT"
   PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
   gcloud projects add-iam-policy-binding $PROJECT_ID \
       --member="principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$PROJECT_ID.svc.id.goog/subject/ns/default/sa/$KUBERNETES_SERVICEACCOUNT" \
       --role="roles/alloydb.client" \
       --condition=None
   gcloud projects add-iam-policy-binding $PROJECT_ID \
       --member="principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$PROJECT_ID.svc.id.goog/subject/ns/default/sa/$KUBERNETES_SERVICEACCOUNT" \
       --role="roles/serviceusage.serviceUsageConsumer" \
       --condition=None

   更改下列內容：

   • PROJECT_ID：您的專案 ID。
   • KUBERNETES_SERVICEACCOUNT：Kubernetes ServiceAccount 名稱，例如 alloydb-sa。

將範例應用程式的映像檔填入 Artifact Registry

如要建構範例應用程式的容器映像檔，並推送至存放區，請完成下列步驟。

控制台

1. 前往 Google Cloud 控制台的「Artifact Registry」頁面。

   前往「Artifact Registry」頁面

2. 如要建立存放區，請按一下 。

3. 在「Name」欄位中輸入 REPOSITORY_ID，例如 gke-alloydb-sample-app。

4. 在「Format」(格式) 部分，選取「Docker」。

5. 在「位置類型」部分，選取「區域」並選擇 REGION，例如 us-central1。

6. 點選「建立」。

7. 如要建構範例應用程式映像檔，請啟動 Cloud Shell，並完成下列步驟。

8. 在 Google Cloud 控制台啟用 Cloud Shell。

   啟用 Cloud Shell

   Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。

1. 在 Cloud Shell 中，從 GitHub 複製含有 gke-alloydb-app 應用程式程式碼範例的存放區：

     git clone https://github.com/GoogleCloudPlatform/alloydb-auth-proxy && cd alloydb-auth-proxy/examples/go

2. 在「授權 Cloud Shell」對話方塊中，點選「授權」。如果您先前已完成這個步驟，系統就不會顯示這則提示。

3. 執行下列指令，建構 Docker 容器並發布至 Artifact Registry：

     gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_ID/SAMPLE_APPLICATION --project PROJECT_ID

   更改下列內容：

   • PROJECT_ID：專案 ID。
   • REPOSITORY_ID：存放區名稱，例如 gke-alloydb-sample-app。
   • SAMPLE_APPLICATION：範例網頁應用程式的名稱，例如 gke-alloydb-app。

gcloud

1. 在 Cloud Shell 中，使用下列指令從 GitHub 複製含有 gke-alloydb-app 範例應用程式程式碼的存放區：

    git clone https://github.com/GoogleCloudPlatform/alloydb-auth-proxy && cd alloydb-auth-proxy/examples/go

2. 在 Artifact Registry 建立 Docker 映像檔存放區：

   gcloud artifacts repositories create REPOSITORY_ID --location REGION --repository-format=docker --project PROJECT_ID

   更改下列內容：

   • PROJECT_ID：專案 ID。
   • REPOSITORY_ID：存放區名稱，例如 gke-alloydb-sample-app。

3. 在「授權 Cloud Shell」對話方塊中，點選「授權」。如果您先前已完成這個步驟，系統就不會顯示這則提示。

4. 如要建構 Docker 容器並發布至 Artifact Registry，請使用下列指令：

    gcloud builds submit --tag  REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_ID/SAMPLE_APPLICATION --project PROJECT_ID

   更改下列內容：

   • PROJECT_ID：專案 ID。
   • REPOSITORY_ID：存放區名稱，例如 gke-alloydb-sample-app。
   • SAMPLE_APPLICATION：範例網頁應用程式的名稱，例如 gke-alloydb-app。

建立 Kubernetes Secret

您會為範例應用程式使用的資料庫、使用者和使用者密碼建立 Kubernetes Secret。每個 Secret 的值，取決於您在本教學課程「連線至主要執行個體，並建立 AlloyDB 資料庫和使用者」步驟中指定的值。詳情請參閱「密鑰」。

控制台

在開啟的 Cloud Shell 中，使用 Kubernetes SECRET (例如 gke-alloydb-secret) 儲存連線資訊：

kubectl create secret generic SECRET \
  --from-literal=database=DATABASE_NAME \
  --from-literal=username=USERNAME \
  --from-literal=password=DATABASE_PASSWORD

gcloud

使用 Kubernetes SECRET (例如 gke-alloydb-secret) 儲存連線資訊：

kubectl create secret generic SECRET \
  --from-literal=database=DATABASE_NAME \
  --from-literal=username=USERNAME \
  --from-literal=password=DATABASE_PASSWORD

以 sidecar 模式部署及執行 AlloyDB Auth Proxy

建議您以 sidecar 模式執行驗證 Proxy，做為與應用程式共用 Pod 的額外容器，原因如下：

• 防止 SQL 流量在本機公開。Auth Proxy 會為傳出連線提供加密，但您必須限制傳入連線的曝光。
• 避免單點故障。每個應用程式對資料庫的存取權都彼此獨立，因此更具彈性。
• 限制 Auth Proxy 的存取權，讓您能依應用程式使用 IAM 權限，而非向整個叢集公開資料庫。
• 更準確地界定資源要求範圍。由於 Auth Proxy 耗用的資源與用量成正比，因此這種模式可讓您更準確地界定及要求資源，以配合應用程式擴充。
• 可讓您設定應用程式，使用指令區段中指定的 DB_PORT 上的 127.0.0.1 進行連線。

建立 GKE 叢集並為應用程式建構容器映像檔後，請將容器化應用程式部署至 GKE 叢集。

控制台

在本教學課程中，您將部署範例投票收集網頁應用程式 gke-alloydb-app，並使用 AlloyDB 做為資料儲存庫。

1. 取得 AlloyDB 主要執行個體的連線 URI (INSTANCE_URI)：

   1. 前往 Google Cloud 控制台的「Clusters」(叢集) 頁面。

      前往「Clusters」(叢集) 頁面

   2. 在「Resource name」(資源名稱) 欄中，按一下叢集名稱，即可顯示叢集的「Overview」(總覽) 頁面。

   3. 在「叢集內的執行個體」部分，找出主要執行個體，然後前往「連線能力」部分 (或點選「查看連線設定」)。

   4. 在「Connection URI」欄位中，按一下「複製到剪貼簿」按鈕 。

   您可以在本節步驟 2.b 的 proxy_sidecar_deployment.yaml 定義檔案中指定這個 INSTANCE_URI。

2. 在開啟的 Cloud Shell 中，完成下列步驟：

   1. 使用您選擇的編輯器 (例如 nano) 開啟 proxy_sidecar_deployment.yaml：

      nano proxy_sidecar_deployment.yaml

   2. 在編輯器中貼上以下內容：

      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: gke-alloydb
      spec:
        selector:
          matchLabels:
            app: SAMPLE_APPLICATION
        template:
          metadata:
            labels:
              app: SAMPLE_APPLICATION
          spec:
            serviceAccountName: KUBERNETES_SERVICEACCOUNT
            containers:
            - name: SAMPLE_APPLICATION
              # Replace <PROJECT_ID> and <REGION> with your project ID and region.
              image: REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_ID/SAMPLE_APPLICATION:latest
              imagePullPolicy: Always
              # This app listens on port 8080 for web traffic by default.
              ports:
              - containerPort: 8080
              env:
              - name: PORT
                value: "8080"
              - name: INSTANCE_HOST
                value: "127.0.0.1"
              - name: DB_PORT
                value: "5432"
              - name: DB_USER
                valueFrom:
                  secretKeyRef:
                    name: SECRET
                    key: username
              - name: DB_PASS
                valueFrom:
                 secretKeyRef:
                    name: SECRET
                    key: password
              - name: DB_NAME
                valueFrom:
                  secretKeyRef:
                    name: SECRET
                    key: database
            - name: alloydb-proxy
              # This uses the latest version of the AlloyDB Auth proxy
              image: gcr.io/alloydb-connectors/alloydb-auth-proxy:1.17.2
              command:
                - "/alloydb-auth-proxy"
                #AlloyDB instance name as parameter for the AlloyDB proxy
                - "INSTANCE_URI"
              securityContext:
                runAsNonRoot: true
              resources:
                requests:
                  memory: "2Gi"
                  cpu:    "1"
      

      將 KUBERNETES_SERVICEACCOUNT 替換為 Kubernetes ServiceAccount 名稱，並將 INSTANCE_URI 替換為您在步驟 1 複製的路徑。

   3. 依序按下 Control+O 和 Enter 鍵儲存變更，然後按下 Control+X 鍵退出編輯器。

3. 如要部署 gke-alloydb-app 應用程式，請套用定義檔：

   kubectl apply -f proxy_sidecar_deployment.yaml

4. 如要確認應用程式是否正在執行，請前往 Google Cloud 控制台的「Workloads」(工作負載) 頁面：

   前往「Workloads」(工作負載)

   確認 gke-alloydb 部署作業的狀態為「OK」(確定)。

5. 如要使用外部負載平衡器連線至範例應用程式，請在開啟的 Cloud Shell 中完成下列步驟：

   1. 開啟 service.yaml：

      nano service.yaml

   2. 貼上下列內容：

      apiVersion: v1
      kind: Service
      metadata:
        name: SAMPLE_APPLICATION
      spec:
        type: LoadBalancer
        selector:
          app: SAMPLE_APPLICATION
        ports:
        - port: 80
          targetPort: 8080
      

      將 SAMPLE_APPLICATION 替換為應用程式名稱，例如 gke-alloydb-app。

   3. 儲存並退出編輯器，然後套用服務：

      kubectl apply -f service.yaml

6. 如要取得應用程式的外部 IP 位址，請前往 Google Cloud 控制台的「Services & Ingress」(Service 與 Ingress) 頁面：

   前往「Services & Ingress」(Service 與 Ingress) 頁面

7. 使用「External endpoints」(外部端點) 欄中的值，透過下列網址存取應用程式：

   http://EXTERNAL_IP

gcloud

在本教學課程中，您將部署範例投票收集網頁應用程式 gke-alloydb-app，並使用 AlloyDB 做為資料儲存庫。

1. 取得要讓 Auth Proxy 連線的 AlloyDB 主要執行個體連線 INSTANCE_URI：

      gcloud alloydb instances describe INSTANCE_ID \
      --cluster=CLUSTER_ID \
      --region=REGION \
      --format="value(name)"

   更改下列內容：

   • INSTANCE_ID：執行個體的名稱，例如 alloydb-primary。
   • CLUSTER_ID：叢集名稱，例如 alloydb-cluster。

   輸出內容包含您在本節步驟 2.b 的 proxy_sidecar_deployment.yaml 定義檔案中指定的 INSTANCE_URI。

2. 在您選擇的編輯器 (例如 nano) 中，完成下列步驟：

   1. 使用您選擇的編輯器 (例如 nano) 開啟 proxy_sidecar_deployment.yaml：

      nano proxy_sidecar_deployment.yaml

   2. 在編輯器中貼上以下內容：

      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: gke-alloydb
      spec:
        selector:
          matchLabels:
            app: SAMPLE_APPLICATION
        template:
          metadata:
            labels:
              app: SAMPLE_APPLICATION
          spec:
            serviceAccountName: KUBERNETES_SERVICEACCOUNT
            containers:
            - name: SAMPLE_APPLICATION
              # Replace <PROJECT_ID> and <REGION> with your project ID and region.
              image: REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_ID/SAMPLE_APPLICATION:latest
              imagePullPolicy: Always
              # This app listens on port 8080 for web traffic by default.
              ports:
              - containerPort: 8080
              env:
              - name: PORT
                value: "8080"
              # This project uses environment variables to determine
              # how you would like to run your application
              # To use the Go connector (recommended) - use INSTANCE NAME
              # To use TCP - Setting INSTANCE_HOST will use TCP (e.g., 127.0.0.1)
              - name: INSTANCE_HOST
                value: "127.0.0.1"
              - name: DB_PORT
                value: "5432"
              # To use Automatic IAM Authentication (recommended)
              # use DB_IAM_USER instead of DB_USER
              # you may also remove the DB_PASS environment variable
              - name: DB_USER
                valueFrom:
                  secretKeyRef:
                    name: SECRET
                    key: username
              - name: DB_PASS
                valueFrom:
                 secretKeyRef:
                    name: SECRET
                    key: password
              - name: DB_NAME
                valueFrom:
                  secretKeyRef:
                    name: SECRET
                    key: database
           # If you are using the Go connector (recommended), you can
            # remove alloydb-proxy (everything below this line)
            - name: alloydb-proxy
              # This uses the latest version of the AlloyDB Auth proxy
              # It is recommended to use a specific version for production environments.
              # See: https://github.com/GoogleCloudPlatform/alloydb-auth-proxy
              image: gcr.io/alloydb-connectors/alloydb-auth-proxy:1.17.2
              command:
                - "/alloydb-auth-proxy"
                #AlloyDB instance name as parameter for the AlloyDB proxy
                # Use <INSTANCE_URI>
                - "INSTANCE_URI"
              securityContext:
                # The default AlloyDB Auth proxy image runs as the
                # "nonroot" user and group (uid: 65532) by default.
                runAsNonRoot: true
              resources:
                requests:
                  # The proxy's memory use scales linearly with the number of active
                  # connections. Fewer open connections will use less memory. Adjust
                  # this value based on your application's requirements.
                  memory: "2Gi"
                  # The proxy's CPU use scales linearly with the amount of IO between
                  # the database and the application. Adjust this value based on your
                  # application's requirements.
                  cpu:    "1"
      

      將 KUBERNETES_SERVICEACCOUNT 替換為 Kubernetes ServiceAccount 名稱，並將 INSTANCE_URI 替換為步驟 1 中 AlloyDB 主要執行個體的路徑，例如 projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID/instances/INSTANCE_ID。

   3. 依序按下 Control+O 和 Enter 鍵儲存變更，然後按下 Control+X 鍵退出編輯器。

3. 如要部署 gke-alloydb-app 應用程式，請套用您在上一個步驟中建立的 proxy_sidecar_deployment.yaml 定義檔案：

   kubectl apply -f proxy_sidecar_deployment.yaml

4. 確認 Pod 中兩個容器的狀態皆為 running：

   kubectl get pods

   輸出內容範例：

    NAME                          READY   STATUS    RESTARTS   AGE
    gke-alloydb-8d59bb4cc-62xgh   2/2     Running   0          2m53s
   

5. 如要連線至 gke-alloydb-app 範例應用程式，請使用服務，例如外部 HTTP 負載平衡器。在您選擇的編輯器中，按照下列步驟操作：

   1. 使用 nano 開啟 service.yaml，例如：

      nano service.yaml

   2. 在 nano 編輯器中，貼上下列內容：

      apiVersion: v1
      kind: Service
      metadata:
        name: SAMPLE_APPLICATION
      spec:
        type: LoadBalancer
        selector:
          app: SAMPLE_APPLICATION
        ports:
        - port: 80
          targetPort: 8080
      

      將 SAMPLE_APPLICATION 替換為範例網頁應用程式的名稱，例如 gke-alloydb-app。

   3. 依序按下 Control+O 和 Enter 鍵儲存變更，然後按下 Control+X 鍵退出編輯器。

6. 如要部署服務 gke-alloydb-app 應用程式，請套用 service.yaml 檔案：

    kubectl apply -f service.yaml

7. 如要取得服務詳細資料 (包括服務的外部 IP 位址)，請使用下列指令：

   kubectl get service

   輸出內容範例：

   NAME              TYPE           CLUSTER-IP       EXTERNAL-IP     PORT(S)        AGE
   gke-alloydb-app   LoadBalancer   34.118.229.246   35.188.16.172   80:32712/TCP   45s
   kubernetes        ClusterIP      34.118.224.1     <none>          443/TCP        85m
   

8. 使用上一步的外部 IP 值，透過下列網址存取範例應用程式：

   http://EXTERNAL-IP
   

設定檔範例

proxy_sidecar_deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: <YOUR-DEPLOYMENT-NAME>
spec:
  selector:
    matchLabels:
      app: <YOUR-APPLICATION-NAME>
  template:
    metadata:
      labels:
        app: <YOUR-APPLICATION-NAME>
    spec:
      serviceAccountName: <YOUR-KSA-NAME>
      containers:
      # Your application container goes here.
      - name: <YOUR-APPLICATION-NAME>
        image: <YOUR-APPLICATION-IMAGE-URL>
        env:
        - name: DB_HOST
          # The port value here (5432) should match the --port flag below.
          value: "localhost:5432"
        - name: DB_USER
          valueFrom:
            secretKeyRef:
              name: <YOUR-DB-SECRET>
              key: username
        - name: DB_PASS
          valueFrom:
            secretKeyRef:
              name: <YOUR-DB-SECRET>
              key: password
        - name: DB_NAME
          valueFrom:
            secretKeyRef:
              name: <YOUR-DB-SECRET>
              key: database
      # The Auth Proxy sidecar goes here.
      - name: alloydb-auth-proxy
        # Make sure you have automation that upgrades this version regularly.
        # A new version of the Proxy is released monthly with bug fixes,
        # security updates, and new features.
        image: gcr.io/alloydb-connectors/alloydb-auth-proxy:1.10.1
        args:
          # If you're connecting over public IP, enable this flag.
          # - "--public-ip"

          # If you're connecting with PSC, enable this flag:
          # - "--psc"

          # If you're using auto IAM authentication, enable this flag:
          # - "--auto-iam-authn"

          # Enable structured logging with Google's LogEntry format:
          - "--structured-logs"

          # Listen on localhost:5432 by default.
          - "--port=5432"
          # Specify your instance URI, e.g.,
          # "projects/myproject/locations/us-central1/clusters/mycluster/instances/myinstance"
          - "<INSTANCE-URI>"

        securityContext:
          # The default AlloyDB Auth Proxy image runs as the "nonroot" user and
          # group (uid: 65532) by default.
          runAsNonRoot: true
        # You should use resource requests/limits as a best practice to prevent
        # pods from consuming too many resources and affecting the execution of
        # other pods. You should adjust the following values based on what your
        # application needs. For details, see
        # https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
        resources:
          requests:
            # The proxy's memory use scales linearly with the number of active
            # connections. Fewer open connections will use less memory. Adjust
            # this value based on your application's requirements.
            memory: "2Gi"
            # The proxy's CPU use scales linearly with the amount of IO between
            # the database and the application. Adjust this value based on your
            # application's requirements.
            cpu:    "1"

service.yaml

apiVersion: v1
kind: Service
metadata:
  name: <YOUR-SERVICE-NAME>
spec:
  type: LoadBalancer
  selector:
    app: <YOUR-APPLICATION-NAME>
  ports:
  - port: 80
    targetPort: 8080

service-account.yaml

apiVersion: v1
kind: ServiceAccount
metadata:
  name: <YOUR-KSA-NAME> # TODO(developer): replace this value

清除所用資源

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

刪除專案

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

如要刪除專案，請進行以下操作：

1. 前往 Google Cloud 控制台的「Manage resources」(管理資源) 頁面。

   管理資源

2. 在專案清單中選取要刪除的專案，然後點按「刪除」。

3. 在對話方塊中輸入PROJECT_ID，然後按一下「Shut down」(關閉) 刪除專案。

後續步驟

• AlloyDB Auth Proxy 簡介
• 內部 IP 總覽
• Google Kubernetes Engine 說明文件