應用程式新手上路

1. 事前準備

自學環境設定

1. 登入 Google Cloud 控制台，然後建立新專案或重複使用現有專案。如果您還沒有 Gmail 或 Google Workspace 帳戶，請務必建立帳戶。

• 「Project name」是這個專案參與者的顯示名稱。這是 Google API 不使用的字元字串，您可以隨時更新。
• 專案 ID 在所有 Google Cloud 專案中不得重複，且無法變更 (設定後即無法變更)。Cloud 控制台會自動產生專屬字串，您通常不需要特別留意。在大多數程式碼研究室中，您需要參照專案 ID (通常會以 PROJECT_ID 表示)，因此如果不喜歡這個 ID，可以產生另一個隨機 ID，也可以嘗試使用自己的 ID，看看是否可用。然後在專案建立後「凍結」。
• 還有第三個值，也就是部分 API 使用的專案編號。如要進一步瞭解這三個值，請參閱說明文件。

注意：專案 ID 必須是全域唯一的，而且選定後即無法使用。您是該 ID 唯一的使用者。刪除專案後，該 ID 就無法再使用。

注意：如果你使用 Gmail 帳戶，可以將預設位置設為「無機構」。如果你使用 Google Workspace 帳戶，請選擇貴機構適用的位置。

2. 接著，您需要在 Cloud 控制台中啟用帳單功能，才能使用 Cloud 資源/API。執行本程式碼研究室時，費用應該不會太高，甚至可能不收費。如要關閉資源，以免產生本教學課程結束後產生的費用，請按照程式碼研究室結尾處提供的「清除所用資源」操作說明進行。Google Cloud 的新使用者符合 $300 美元免費試用計畫的資格。

2. 正在準備工作區

1. 前往下列網址開啟 Cloud Shell 編輯器

https://ide.cloud.google.com

2. 確認 CLI 中已設定專案名稱

gcloud config set project {{project-id}}

export PROJECT_ID=$(gcloud config get-value project)

export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')

3. 啟用 API

gcloud services enable \

cloudbuild.googleapis.com \

secretmanager.googleapis.com

4. 提供 CloudDeploy 的權限

gcloud projects add-iam-policy-binding --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" --role roles/clouddeploy.admin ${PROJECT_ID}

gcloud projects add-iam-policy-binding --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" --role roles/container.developer ${PROJECT_ID}

gcloud projects add-iam-policy-binding --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" --role roles/iam.serviceAccountUser ${PROJECT_ID}

gcloud projects add-iam-policy-binding --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" --role roles/clouddeploy.jobRunner ${PROJECT_ID}

5. 在終端機視窗中，使用下列指令複製應用程式來源：

git clone https://github.com/GoogleCloudPlatform/software-delivery-workshop.git

6. 切換至該目錄，並將 IDE 工作區設為存放區根目錄

cd software-delivery-workshop && rm -rf .git

cd delivery-platform && cloudshell workspace .

3. 使用預先定義和自訂的應用程式範本

開發人員應可從機構內常用的一組範本中進行選擇。在前置作業期間，系統會建立一組集中式範本存放區，並儲存在您的 GitHub 帳戶中。在後續步驟中，我們會複製並修改這些範本存放區，以做為新應用程式的基礎。在本實驗室中，您將使用此處提供的範例結構，為範本存放區提供種子資料。您可以新增範例的其他資料夾，藉此新增自己的範本。

在這個步驟中，您將根據提供的範例檔案，建立自己的存放區來儲存應用程式範本。我們提供輔助指令碼，簡化與 GitHub 的互動。

這些是用於填入範本存放區的一次性步驟。後續步驟會重複使用這些存放區。

設定 GitHub 存取權

本教學課程中的步驟呼叫 GitHub API 以建立及設定存放區。您將在後續的各個步驟中需要提供 GitHub 使用者名稱和個人存取權杖。下列指令碼可協助您取得值，並將這些值儲存為本機變數，以供日後使用。

source ./onboard-env.sh

echo Git Username: $GIT_USERNAME

echo Git Base URL: $GIT_BASE_URL

建立應用程式範本存放區

本研究室提供範例應用程式範本，並說明如何使用您的基本範本。在這個步驟中，您會在 GitHub 帳戶中建立名為 mcd-app-templates 的存放區，並在其中建立這些檔案的副本。

1. 將範本複製到工作目錄

cp -R $BASE_DIR/resources/repos/app-templates $WORK_DIR

cd $WORK_DIR/app-templates

2. 在 GitHub 帳戶中建立空白的遠端存放區

$BASE_DIR/scripts/git/gh.sh create mcd-app-templates

3. 將範本存放區推送至遠端存放區

git init && git symbolic-ref HEAD refs/heads/main && git add . && git commit -m "initial commit"

git remote add origin $GIT_BASE_URL/mcd-app-templates

git push origin main

4. 清理工作目錄

cd $BASE_DIR

rm -rf $WORK_DIR/app-templates

建立共用基礎設定存放區

本教學課程使用 Kustomize 工具，透過多個團隊共用的基本設定檔，疊加應用程式專屬設定。這麼做可讓平台團隊跨多個團隊和環境擴大規模。

在這個步驟中，您會從提供的範例建立名為 mcd-shared_kustomize 的共用設定存放區

1. 將範本複製到工作目錄

cp -R $BASE_DIR/resources/repos/shared-kustomize $WORK_DIR

cd $WORK_DIR/shared-kustomize

2. 在 GitHub 帳戶中建立空白的遠端存放區

$BASE_DIR/scripts/git/gh.sh create mcd-shared_kustomize

3. 將範本存放區推送至遠端存放區

git init && git symbolic-ref HEAD refs/heads/main && git add . && git commit -m "initial commit"

git remote add origin $GIT_BASE_URL/mcd-shared_kustomize

git push origin main

4. 清理工作目錄

cd $BASE_DIR

rm -rf $WORK_DIR/shared-kustomize

範本存放區建立完成後，您就可以使用這些範本建立應用程式執行個體

4. 建立應用程式的新例項

使用範本建立新的應用程式時，通常需要在範本結構的多個檔案中將預留位置變數替換為實際值。替換完成後，系統會為新的應用程式執行個體建立新的存放區。開發人員會在日常開發工作中複製及使用這個應用程式執行個體存放區。

在這個步驟中，您將替換應用程式範本中的值，並將產生的檔案發布至新的存放區。

定義新應用程式的名稱

export APP_NAME=my-app

擷取 Golang 範本存放區

cd $WORK_DIR/

git clone -b main $GIT_BASE_URL/mcd-app-templates app-templates

rm -rf app-templates/.git

cd app-templates/golang

替換預留位置值

新手上路時最常見的需求之一，就是將範本中的變數換成應用程式中使用的實際例項。例如，提供應用程式名稱。以下指令會使用儲存在環境變數中的值，建立所有 .tmpl 檔案的例項。

for template in $(find . -name '*.tmpl'); do envsubst < ${template} > ${template%.*}; done

建立新的存放區並儲存更新的檔案

1. 在 GitHub 帳戶中建立空白的遠端存放區

$BASE_DIR/scripts/git/gh.sh create ${APP_NAME}

2. 將範本存放區推送至遠端存放區

git init && git symbolic-ref HEAD refs/heads/main && git add . && git commit -m "initial commit"

git remote add origin $GIT_BASE_URL/${APP_NAME}

git push origin main

應用程式執行個體已建立完成，現在可以實作持續建構作業。

5. 設定自動化管道執行作業

持續整合系統的核心部分，就是根據來源控制系統產生的事件，執行管道邏輯。開發人員在存放區中提交程式碼時，系統會觸發事件，可設定為觸發其他系統中的程序。

在這個步驟中，您將設定 GitHub 在使用者在存放區中提交或標記程式碼時，呼叫 Google Cloud Build 並執行管道。

啟用安全存取功能

您需要 2 個元素，才能設定應用程式管道的安全存取權。管道專屬的 API 金鑰和密鑰。

API 金鑰

API 金鑰可用於識別呼叫特定 API 的用戶端。在這種情況下，用戶端會是 GitHub。這裡未提及的最佳做法，是將 API 金鑰的範圍鎖定為用戶端將存取的特定 API。您在上一個步驟中建立了金鑰。

1. 您可以按一下這個連結來查看金鑰
2. 您可以執行下列指令，確認已設定值

echo $API_KEY_VALUE

管道密鑰

密鑰會用於授權呼叫端，並確保呼叫端擁有特定 Cloud Build 目標工作作業的權限。您可能在 GitHub 中擁有 2 個不同的存放區，且這些存放區只能存取各自的管道。雖然 API_KEY 會限制 github 可使用的 API (在本例中為呼叫的 Cloud Build API)，但機密值會限制用戶端可執行的 Cloud Build API 工作。

1. 定義密鑰名稱、位置和值

SECRET_NAME=${APP_NAME}-webhook-trigger-cd-secret

SECRET_PATH=projects/${PROJECT_NUMBER}/secrets/${SECRET_NAME}/versions/1

SECRET_VALUE=$(sed "s/[^a-zA-Z0-9]//g" <<< $(openssl rand -base64 15))

2. 建立密鑰

printf ${SECRET_VALUE} | gcloud secrets create ${SECRET_NAME} --data-file=-

3. 允許 Cloud Build 讀取密鑰

gcloud secrets add-iam-policy-binding ${SECRET_NAME} \

--member=serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com \

--role='roles/secretmanager.secretAccessor'

建立 Cloud Build 觸發條件

Cloud Build 觸發條件是實際執行 CICD 程序的設定。

建立工作時，您必須提供幾個關鍵值，才能正確設定觸發條件。

4. 定義觸發事件的名稱和設定檔所在位置

export TRIGGER_NAME=${APP_NAME}-clouddeploy-webhook-trigger

export BUILD_YAML_PATH=$WORK_DIR/app-templates/golang/build/cloudbuild-cd.yaml

5. 定義共用基本設定存放區的位置。

export KUSTOMIZE_REPO=${GIT_BASE_URL}/mcd-shared_kustomize

6. 在定義專案的容器登錄檔的 onboard-env.sh 指令碼中設定了變數。請使用下列指令查看值。

echo $IMAGE_REPO

7. 使用先前建立的變數建立 CloudBuild Webhook 觸發條件。應用程式存放區位置會從 GitHub 要求的內容中提取。以下值參照要求內容中該值所在的路徑gcloud alpha builds triggers create webhook \

    `--name=${TRIGGER_NAME} \`
   
    `--substitutions='_APP_NAME='${APP_NAME}',_APP_REPO=$(body.repository.git_url),_CONFIG_REPO='${GIT_BASE_URL}'/'${CLUSTER_CONFIG_REPO}',_DEFAULT_IMAGE_REPO='${IMAGE_REPO}',_KUSTOMIZE_REPO='${GIT_BASE_URL}'/'${SHARED_KUSTOMIZE_REPO}',_REF=$(body.ref)' \`
   
    `--inline-config=$BUILD_YAML_PATH \`
   
    `--secret=${SECRET_PATH}`
   

8. 請前往這個連結，在控制台中查看新建立的 Cloud Build 觸發條件
9. 定義端點網址的變數，GitHub 會在下一個步驟使用

WEBHOOK_URL="https://cloudbuild.googleapis.com/v1/projects/${PROJECT_ID}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY_VALUE}&secret=${SECRET_VALUE}"

設定 GitHub Webhook

1. 在 GitHub 中設定 Webhook

$BASE_DIR/scripts/git/gh.sh create_webhook ${APP_NAME} $WEBHOOK_URL

2. 前往應用程式存放區，查看新設定的 webhook

REPO_URL=${GIT_BASE_URL}/${APP_NAME}/settings/hooks

echo $REPO_URL

您已手動完成建立新應用程式所需的所有步驟，現在可以透過指令碼自動執行這些步驟。

6. 自動化所有新手上路步驟

實際上，您無法為每個新應用程式執行上述每個步驟。請改為將邏輯納入指令碼中，以便執行。上述步驟已納入指令碼，供您使用。

在這個步驟中，您將使用提供的指令碼建立新應用程式

建立新應用程式

1. 確認您位於正確的目錄

cd $BASE_DIR

2. 建立新應用程式

export APP_NAME=demo-app

./app.sh create ${APP_NAME}

系統會自動執行所有步驟。

查看 GitHub 存放區

此時您可以在 GitHub 中查看新的存放區

1. 執行下列指令，擷取 GitHub 存放區網址

echo ${GIT_BASE_URL}/demo-app

2. 使用網路瀏覽器開啟網址，查看新申請
3. 請注意，範本變數已替換為實例值，如以下網址所示

echo ${GIT_BASE_URL}/demo-app/blob/main/k8s/prod/deployment.yaml#L24

4. 查看在下方網址設定的 Webhook

echo ${GIT_BASE_URL}/demo-app/settings/hooks

查看 Cloud Build 觸發條件

觸發條件是由指令碼自動設定

1. 請前往這個連結，在控制台中查看 Cloud Build 觸發條件
2. 查看這個頁面的建構歷史記錄