關於自訂指定目標

本文說明 Cloud Deploy 中的自訂目標運作方式。

Cloud Deploy 內建支援各種執行階段環境，做為目標。但支援的目標類型清單是有限的。使用自訂目標時，您可以部署到支援的執行階段以外的其他系統。

自訂目標是指代表任意輸出環境的目標，而非 Cloud Deploy 支援的執行階段。

「建立自訂目標」頁面說明瞭定義自訂目標類型，並在推送管道中將其實作為目標的程序。

自訂目標包含哪些內容？

每個自訂目標都包含下列元件：

工作：定義如何為自訂目標類型算繪及部署

自訂算繪和自訂部署的實作項目會取用 Cloud Deploy 提供的值，且必須符合一組必要輸出內容。

自訂顯示為選用功能，但除非自訂目標使用 Cloud Deploy 內建顯示器顯示時可正常運作，否則您必須建立自訂顯示器。
自訂目標類型定義

CustomTargetType 是 Cloud Deploy 資源，可識別此類型目標用於版本轉譯和推出部署活動的任務。
目標定義

自訂目標的目標定義與任何目標類型相同，但包含 customTarget 屬性，其值為 CustomTargetType 的名稱。

有了這些元件，您就能像使用任何目標一樣使用目標，從推送管道進度參照目標，並充分運用 Cloud Deploy 功能，例如升級和核准，以及復原。

範例

「快速入門」定義及使用自訂目標類型會建立自訂目標類型，其中包含要在容器映像檔上執行的指令，一個用於轉譯，一個用於部署。在本例中，這些指令只會將文字新增至算繪和部署作業所需的輸出檔案。

如需更多範例，請參閱「自訂目標範例」。

必要輸入和輸出

為 Cloud Deploy 定義的任何自訂目標類型，都必須滿足轉譯和部署的輸入和輸出需求。本節列出必要輸入和輸出內容，以及提供方式。

Cloud Deploy 會以環境變數的形式，提供算繪和部署作業所需的輸入內容。以下各節列出這些輸入內容，以及自訂算繪和部署作業必須傳回的輸出內容。

將參數部署為環境變數

除了本節列出的環境變數外，Cloud Deploy 還可以將您設定的任何部署參數傳遞至自訂容器。

瞭解詳情。

自訂算繪的輸入內容

對於自訂算繪，Cloud Deploy 會以環境變數的形式提供下列輸入內容。如果是多階段推出 (初期測試部署)，Cloud Deploy 會為每個階段提供這些變數。

CLOUD_DEPLOY_PROJECT

自訂目標建立所在專案的 Google Cloud 專案編號。
CLOUD_DEPLOY_PROJECT_ID

專案的 Google Cloud 專案 ID。
CLOUD_DEPLOY_LOCATION

自訂目標類型的 Google Cloud 區域。
CLOUD_DEPLOY_DELIVERY_PIPELINE

參照自訂目標類型的 Cloud Deploy 推送管道名稱。
CLOUD_DEPLOY_RELEASE

要叫用算繪作業的版本名稱。
CLOUD_DEPLOY_TARGET

使用自訂目標類型的 Cloud Deploy 目標名稱。
CLOUD_DEPLOY_PHASE

與算繪對應的推出階段。
CLOUD_DEPLOY_REQUEST_TYPE

如果是自訂算繪，這項值一律為 RENDER。
CLOUD_DEPLOY_FEATURES

以半形逗號分隔的清單，列出自訂容器必須支援的 Cloud Deploy 功能。這個變數會根據您在推送管道中設定的功能填入。

如果您的實作方式不支援這份清單中的功能，建議在算繪期間失敗。

如果是標準部署，這個值會是空白。如果是初期測試部署，值為 CANARY。如果 Cloud Deploy 提供的值為 CANARY，系統會為 Canary 中的每個階段叫用算繪。每個階段的初期測試百分比會提供在 CLOUD_DEPLOY_PERCENTAGE_DEPLOY 環境變數中。
CLOUD_DEPLOY_PERCENTAGE_DEPLOY

與這個算繪作業相關聯的部署作業百分比。如果 CLOUD_DEPLOY_FEATURES 環境變數設為 CANARY，系統會為每個階段呼叫自訂算繪，並為每個階段將這個變數設為 Canary 百分比。如果是標準部署作業，以及已達到 stable 階段的初期測試部署作業，則為 100。
CLOUD_DEPLOY_STORAGE_TYPE

儲存空間供應商。一律 GCS。
CLOUD_DEPLOY_INPUT_GCS_PATH

建立版本時寫入的算繪檔案封存檔 Cloud Storage 路徑。
CLOUD_DEPLOY_OUTPUT_GCS_PATH

自訂算繪容器預期會將構件上傳至這個 Cloud Storage 路徑，以供部署作業使用。請注意，算繪作業必須上傳名為 results.json 的檔案，其中包含這項算繪作業的結果。詳情請參閱「自訂算繪的輸出內容」。

自訂算繪的輸出內容

自訂算繪必須提供本節所述資訊。這項資訊必須包含在名為 results.json 的結果檔案中，該檔案位於 Cloud Deploy 提供的 Cloud Storage bucket (CLOUD_DEPLOY_OUTPUT_GCS_PATH)。

已算繪的設定檔
results.json 檔案，內含下列資訊：
- 指出自訂算繪的成功或失敗狀態。
  
  有效值為 SUCCEEDED 和 FAILED。
- (選用) 自訂算繪產生的任何錯誤訊息。
- 已算繪設定檔的 Cloud Storage 路徑。
  
  所有已算繪設定檔的路徑都是完整 URI。您可以使用 Cloud Deploy 提供的 CLOUD_DEPLOY_OUTPUT_GCS_PATH 值，部分填入這個欄位。
  
  即使設定檔是空白，也必須提供經過算繪的設定檔。檔案內容不限，格式也不限，只要自訂部署作業可使用即可。建議您讓這個檔案可供人閱讀，這樣您和貴機構的其他使用者就能在版本檢查器中查看這個檔案。
- (選用) 要納入的任何中繼資料對應
  
  自訂目標會建立這項中繼資料。這項中繼資料會儲存在發行內容的 custom_metadata 欄位中。

如要檢查 results.json 檔案 (例如進行偵錯)，可以在 Cloud Build 記錄中找到該檔案的 Cloud Storage URI。

範例算繪結果檔案

以下是自訂算繪作業的 results.json 檔案輸出範例：

{
  "resultStatus": "SUCCEEDED",
  "manifestFile": "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/manifest.yaml",
  "failureMessage": "",
  "metadata": {
    "key1": "val",
    "key2": "val"
  }
}

自訂部署的輸入內容

如果是自訂部署作業，Cloud Deploy 會以環境變數的形式提供下列輸入內容：

CLOUD_DEPLOY_PROJECT

自訂目標建立所在專案的 Google Cloud 專案編號。
CLOUD_DEPLOY_PROJECT_ID

專案的 Google Cloud 專案 ID。
CLOUD_DEPLOY_LOCATION

自訂目標類型的 Google Cloud 區域。
CLOUD_DEPLOY_DELIVERY_PIPELINE

Cloud Deploy 部署管道的名稱，該管道會參照使用自訂目標類型的目標。
CLOUD_DEPLOY_RELEASE

要叫用部署作業的版本名稱。
CLOUD_DEPLOY_ROLLOUT

這項部署作業所屬的 Cloud Deploy 推出作業名稱。
CLOUD_DEPLOY_TARGET

使用自訂目標類型的 Cloud Deploy 目標名稱。
CLOUD_DEPLOY_PHASE

部署作業對應的發布階段。
CLOUD_DEPLOY_REQUEST_TYPE

如果是自訂部署，這項值一律為 DEPLOY。
CLOUD_DEPLOY_FEATURES

以半形逗號分隔的清單，列出自訂容器必須支援的 Cloud Deploy 功能。這個變數會根據您在推送管道中設定的功能填入。

如果您的實作方式不支援這份清單中的功能，建議在算繪期間失敗。

如果是標準部署，這個值會是空白。如果是初期測試部署，值為 CANARY。如果 Cloud Deploy 提供的值為 CANARY，系統會為 Canary 中的每個階段叫用部署作業。每個階段的初期測試百分比會提供在 CLOUD_DEPLOY_PERCENTAGE_DEPLOY 環境變數中。
CLOUD_DEPLOY_PERCENTAGE_DEPLOY

與這項部署作業相關聯的部署作業百分比。如果 CLOUD_DEPLOY_FEATURES 環境變數設為 CANARY，系統會為每個階段呼叫自訂部署作業，並將這個變數設為每個階段的 Canary 百分比。您必須為每個階段執行部署作業。
CLOUD_DEPLOY_STORAGE_TYPE

儲存空間供應商。一律 GCS。
CLOUD_DEPLOY_INPUT_GCS_PATH

自訂算繪器寫入算繪設定檔的 Cloud Storage 路徑。
CLOUD_DEPLOY_SKAFFOLD_GCS_PATH

已算繪 Skaffold 設定的 Cloud Storage 路徑。如果您在發布版本時提供 Skaffold 設定。
CLOUD_DEPLOY_MANIFEST_GCS_PATH

已算繪資訊清單檔案的 Cloud Storage 路徑。
CLOUD_DEPLOY_OUTPUT_GCS_PATH

自訂部署容器預期上傳部署構件的 Cloud Storage 目錄路徑。詳情請參閱「自訂部署的輸出內容」。

自訂部署作業的輸出內容

自訂部署作業必須寫入 results.json 輸出檔案。這個檔案必須位於 Cloud Deploy 提供的 Cloud Storage 值區 (CLOUD_DEPLOY_OUTPUT_GCS_PATH)。

檔案必須包含下列項目：

自訂部署的成功或失敗狀態指標。

有效狀態如下：
- SUCCEEDED
- FAILED
- SKIPPED
這是指略過初期測試階段的初期測試部署，可直接進入 stable。
(選用) 部署構件檔案清單，格式為 Cloud Storage 路徑

路徑是完整 URI。您可以使用 Cloud Deploy CLOUD_DEPLOY_OUTPUT_GCS_PATH 提供的值，部分填入這個欄位。

這裡列出的檔案會填入工作執行資源，做為部署構件。
(選用) 如果自訂部署失敗 (傳回 FAILED 狀態)，則為失敗訊息

這個訊息會用來填入這項部署的工作執行中的 failure_message。
(選用) 略過訊息，在部署作業傳回 SKIPPED 狀態時提供額外資訊。
(選用) 要納入的任何中繼資料對應

自訂目標會建立這項中繼資料。這項中繼資料會儲存在工作執行和推出作業的 custom_metadata 欄位中。

如需檢查 results.json 檔案 (例如進行偵錯)，您可以在 Cloud Build 記錄中找到該檔案的 Cloud Storage URI。

部署結果檔案範例

以下是自訂部署作業輸出的範例 results.json 檔案：

{
  "resultStatus": "SUCCEEDED",
  "artifactFiles": [
    "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file1.yaml",
    "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file2.yaml"
  ],
  "failureMessage": "",
  "skipMessage": "",
  "metadata": {
    "key1": "val",
    "key2": "val"
  }
}

進一步瞭解自訂目標

設定及使用自訂目標類型時，請注意下列事項。

執行工作

自訂轉譯和部署工作會在 Cloud Deploy 執行環境中執行。您無法設定工作，讓工作在 Google Kubernetes Engine 叢集上執行。

自訂目標和部署策略

標準部署作業完全支援自訂目標。

只要自訂的算繪器和部署工具支援初期測試功能，Cloud Deploy 就支援初期測試部署。

您必須使用自訂 Canary 設定。自訂目標不支援自動和自訂自動 Canary。

自訂目標和部署參數

您可以搭配自訂目標使用部署參數。您可以在放送管道的階段、使用自訂目標類型的目標，或版本中設定這些目標。

除了已提供的參數，部署參數也會以環境變數的形式，傳遞至自訂轉譯和部署容器。

自訂目標範例

cloud-deploy-samples 存放區包含一組自訂目標實作範例。以下是可用的範例：

GitOps
Vertex AI
Terraform
Infrastructure Manager
Helm

每個範例都包含快速入門導覽課程。

這些樣品並非支援的 Google Cloud 產品，且不適用於 Google Cloud 支援合約。如要回報 Google Cloud 產品錯誤或要求功能，請與 Google Cloud支援團隊聯絡。

後續步驟

現在您已瞭解自訂目標，請參閱這篇文章，瞭解如何設定及使用自訂目標。
請嘗試快速入門導覽課程：定義及使用自訂目標類型。
進一步瞭解如何設定 Cloud Deploy 目標。
瞭解 Cloud Deploy 執行環境。

關於自訂指定目標 透過集合功能整理內容 你可以依據偏好儲存及分類內容。