本頁面由 Cloud Translation API 翻譯而成。

關於自訂指定目標

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

Cloud Deploy 內建支援各種執行階段環境，並將這些環境做為目標。但支援的目標類型清單有限。您可以使用自訂目標，將應用程式部署至支援的執行階段以外的其他系統。

自訂目標是代表任意輸出環境的目標，但不包括 Cloud Deploy 支援的執行階段。

「建立自訂目標」頁面說明定義自訂目標類型，並將其做為提交管道中的目標導入的程序。

自訂目標包含哪些內容？

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

在 skaffold.yaml 中定義的自訂動作

這類似於定義部署掛鉤的方式。在 skaffold.yaml 檔案中，您會定義 customActions，其中每個自訂動作都會識別要使用的容器映像檔，以及要在該容器中執行的指令。

因此，自訂目標只是自訂定義的動作或一組動作。

對於任何自訂目標類型，您都需要設定自訂轉譯動作和自訂部署動作。這些動作會使用 Cloud Deploy 提供的值，且必須滿足一組必要輸出內容。

自訂轉譯動作是選用項目，但您必須建立一個，除非您的自訂目標在由 skaffold render 轉譯時能正常運作，而 skaffold render 是 Cloud Deploy 的預設值。
自訂目標類型定義

CustomTargetType 是 Cloud Deploy 資源，可識別這類目標的自訂動作 (在 skaffold.yaml 中個別定義)，用於版本轉譯和推出部署活動。
目標定義

自訂目標的目標定義與任何目標類型相同，但包含 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 部署，這個值為 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 值區中。

算繪的設定檔
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 部署，這個值為 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 路徑。
CLOUD_DEPLOY_MANIFEST_GCS_PATH

要轉譯的資訊清單檔案的 Cloud Storage 路徑。
CLOUD_DEPLOY_OUTPUT_GCS_PATH

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

部署動作的輸出內容

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

檔案必須包含下列項目：

表示自訂部署動作的成功或失敗狀態。

有效的狀態如下：
- 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 叢集中執行。

使用可重複使用的遠端 Skaffold 設定

如本文所述，您可以在建立版本時提供的 skaffold.yaml 檔案中設定自訂動作。不過，您也可以將 Skaffold 設定儲存在 Git 存放區或 Cloud Storage 值區中，並從自訂目標類型定義中參照這些設定。這樣一來，您就能使用在單一共用位置定義及儲存的自訂動作，而非在每個版本的 skaffold.yaml 檔案中加入自訂動作。

自訂目標和部署策略

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

只要自訂轉譯器和部署工具支援初期測試功能，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 執行環境。

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