工具鏈與 Delivery Pipeline 的限制

資源從一個區域遷移至另一個區域時，須受下列限制。

1. 經典管道 不被支援。
2. DevOps Insights 不支援。
3. 直接儲存在工具鏈或 Delivery Pipeline （環境屬性或觸發器屬性）中的秘密將不會被複製。 export-secrets 指令可將機密匯出到一個 Secrets Manager 实例中，用 秘密引用 替换存储的秘密。 支援隱藏參照。
4. Tekton 管道 webhook 觸發器機密不會被複製，因為 webhook 觸發器機密不支援引用功能。 您需要在複製工具鏈後添加密鑰。
5. Tekton 管道執行歷史、記錄及資產將不會被複製。 您可暫時保留原始管線以存留歷史記錄。
6. GitHub 和 Git Repos and Issue Tracking 工具整合配置的 OAuth 類型驗證將自動轉換為使用執行複製的使用者（API 金鑰的擁有者）的 OAuth 身份，而非原始使用者。 此舉旨在簡化複製操作。 複製後，您可以重新配置工具整合功能，以便使用不同的使用者帳戶。
7. Git Repos and Issue Tracking 使用個人存取權標 (PAT) 進行驗證的工具整合將自動轉換為使用 OAuth。 複製後，您可以重新配置工具整合功能，以便再次使用預先授權金鑰。

Git Repos and Issue Tracking 的限制

以下限制僅適用於您正在遷移 Git Repos and Issue Tracking 專案的情況。

1. 個人專案不予支援。 如果您在 個人命名空間下建立專案，您可以 將個人專案移到群組，或是將個 人命名空間轉換為群組，然後以新的 URL 更新工具鏈中的引用。 建議您將專案儲存於群組中，此舉不僅能允許多位管理員參與，更能確保專案在長期運作中維持更佳的延續性。
2. 使用 GitLab 直接傳輸功能複製專案，此功能受某些 限制。
3. 複製大型專案，或包含大型檔案或眾多資源的專案，可能需要耗費時間。
4. 由於 Git Repos and Issue Tracking 的每個區域都是獨立的，因此您的專案使用者可能尚未存在於目標區域中。 此 copy-project-group 指令將確保使用者存在於新區域中，但可能與目標區域中的其他使用者發生使用者名稱衝突。 若發生使用者名稱衝突，可透過在目標區域的使用者名稱後添加後綴來稍作修改。

重要注意事項

在開始遷移之前，您必須審閱以下重要注意事項。

計費注意事項

在遷移過程中，您需要在目的地區域和資源群組中建立新的 Continuous Delivery 實例，以便在目的地區域啟用工具鏈、管道和專案。 您可能還希望在完成區域遷移前，將原始資源保留在來源區域供使用。 如果您將 Continuous Delivery 服務與專業方案一起使用，請注意，您將根據每個實例中設定的授權使用者數量對兩個區域收取費用。 如果擔心成本問題，您可以在過渡到新區域後，將來源區域 Continuous Delivery 範例中的計劃變更為 Lite。 如果您已超過 Lite 計劃的限制，資源將為唯讀。 然而，若您希望再次使用專業方案，隨時可切換回該方案。 進一步瞭解 Continuous Delivery 計費和計劃。

重複執行 Pipeline

在遷移過程中，您可在目標區域建立新的管道。 如果這些管道設有定時觸發程式，可根據排程自動執行，或 Git 觸發程式設定為在 Git 事件（如 PR 或提交）上自動執行，這些事件可能會觸發重複的管道執行（一個在原始管道中，另一個在新管道中）。 為避免潛在干擾，複製的管線預設將停用此類觸發器。 建議管理這些觸發器，確保每次僅啟用一組設定。 當您對新管道的轉換感到熟悉後，即可啟用該管道上的觸發器，並停用原始管道上的觸發器。

硬編碼假設

遷移之後，您的 Git Repos and Issue Tracking repos (如果適用) 將會有不同的 URL，而您的工具鏈和管道也會有不同的 ID 和 URL。 在您的 Tekton 定義、指令碼、環境屬性或其他自動化中，可能有一些關於 URL /ID 或資源位置的假設。 您有責任在遷移後更新這些資訊。

macOS

執行下列指令在 macOS 上安裝相依性。

brew install node
brew tap hashicorp/tap
brew install hashicorp/tap/terraform

其他平台

• Node.js 安裝說明
• Terraform 安裝說明

CRN

IBM Cloud 資源透過 雲端資源名稱(CRN) 進行唯一識別。 您需要複製工具鏈的課程註冊號碼（CRN）。 您可以透過以下幾種方式取得工具鏈的CRN：

1. 在「平台自動化 > 工具鏈」頁面中定位工具鏈，開啟該工具鏈後點擊「詳細資訊」即可查看工具鏈詳情，其中會顯示該工具鏈的CRN編號。
2. 在 資源清單 頁面中定位工具鏈，點擊工具鏈行以展開詳細資訊面板，該面板將顯示CRN編號。
3. 使用 ibmcloud 命令列介面，您可以透過以下方式列出工具鏈及其對應的 CRN：

   ibmcloud resource service-instances --service-name toolchain --long
   

4. 使用 工具鏈 API。

檢查儲存的工具鏈/管道秘密

工具鏈和 Tekton 管道可以在下列地方包含秘密，也就是 API 金鑰或密碼等敏感值：

• 工具整合屬性，例如 Delivery Pipeline Private Worker 工具整合的服務 ID API 金鑰屬性
• Tekton 管線環境特性
• Tekton 管線觸發屬性

配置機密資訊有兩種方式：

1. 直接儲存在工具鏈或管道中
2. 參考 儲存於秘密儲存服務中的秘密，例如 IBM Cloud Secrets Manager 或 IBM Cloud Key Protect.

複製工具鏈會自動包含 秘密參考，這些參考在新工具鏈中會保持不變。 不過，為了將洩漏敏感資料的風險降到最低，直接儲存在工具鏈或管道中的秘密將不會包含在工具鏈副本中。 您可以使用下一節所述的 export-secrets 指令，或在複製後在複製的工具鏈或管道中再次手動輸入秘密。 但是請注意，如果您沒有匯出秘訣，在複製工具鏈時，某些工具整合可能會因為缺少所需的秘訣值而無法成功提供，可能需要在執行指令後手動重新建立。

首先，檢查您的工具鏈或其 Tekton 管線是否包含任何儲存的秘密，而這些秘密並非透過執行來引用：

npx @ibm-cloud/cd-tools export-secrets -c ${CRN} --check

匯出儲存的工具鏈/管道秘密到 Secrets Manager

如果您的工具鏈或管道不包含任何儲存的機密，您可以跳過此步驟，繼續複製工具鏈。 匯出機密到 Secrets Manager 會在 Secrets Manager 範例中建立機密，也會修改您原本的工具鏈，將現有的機密轉換為引用 Secrets Manager 中新建立的機密。 這將允許在複製工具鏈時，保持秘密參照的完整，這是為了增加安全性而推薦的做法。

為了防止意外暴露機密，您應該檢閱實體的 IAM 權限，以確保只允許預期的讀取權限。Secrets Manager 實例的 IAM 權限，以確保只授予讀取機密的預期存取權。

若要將儲存在工具鏈或管道中的秘密匯出到 Secrets Manager，請遵循以下步驟：

1. 如果您還沒有 Secrets Manager 實例，請 建立一個。 請注意，該實例必須在與您要使用的 API 金鑰相關聯的帳戶中建立。
2. 確保您要使用的 API 金鑰的擁有者擁有在 Secrets Manager 範例中建立秘密的 IAM 權限。
3. 開啟工具鏈和 Secrets Manager 工具整合，在出現提示時建立授權政策，然後再建立工具整合。
4. 執行 export-secrets 指令以匯出機密資訊：

   npx @ibm-cloud/cd-tools export-secrets -c ${CRN}
   

5. 出現提示時，請從工具鏈中選擇 Secrets Manager 範例來儲存秘密。 如果您沒有看到您的實例列出，可能是在不同的帳戶中。 確保您使用的 API 金鑰與實體帳號相同。
6. 出現提示時，針對找到的每個秘密，指定是否複製該秘密，以及儲存該秘密的名稱和群組，或按 Enter 接受預設值。

您可以依需要多次執行此指令，以輸出所有秘密。

複製工具鏈

要複製工具鏈，請執行 @ibm-cloud/cd-tools copy-toolchain 指令。 若要查看可用選項，請執行：

npx @ibm-cloud/cd-tools copy-toolchain -h
Usage: @ibm-cloud/cd-tools copy-toolchain [options]

Copies a toolchain, including tool integrations and Tekton pipelines, to another region or resource group.

Examples:
  export IBMCLOUD_API_KEY='...'
  npx @ibm-cloud/cd-tools copy-toolchain -c ${TOOLCHAIN_CRN} -r us-south
      Copy a toolchain to the Dallas region with the same name, in the same resource group.
  npx @ibm-cloud/cd-tools copy-toolchain -c ${TOOLCHAIN_CRN} -r eu-de -n new-toolchain-name -g new-resource-group --apikey ${APIKEY}
      Copy a toolchain to the Frankfurt region with the specified name and target resource group, using the given API key

Environment Variables:
  IBMCLOUD_API_KEY                       API key used to authenticate. Must be a user API key, with IAM permission to read and create toolchains and service-to-service authorizations in source and target
region / resource group

Basic options:
  -c, --toolchain-crn <crn>              The CRN of the source toolchain to copy
  -r, --region <region>                  The destination region of the copied toolchain (choices: "br-sao", "eu-de", "eu-gb", "jp-tok", "us-south")
  -a, --apikey <api_key>                 API key used to authenticate. Must be a user API key, with IAM permission to read and create toolchains and service-to-service authorizations in source and target
                                         region / resource group
  -n, --name <name>                      (Optional) The name of the copied toolchain (default: same name as original)
  -g, --resource-group <resource_group>  (Optional) The name or ID of destination resource group of the copied toolchain (default: same resource group as original)
  -t, --tag <tag>                        (Optional) The tag to add to the copied toolchain
  -h, --help                             Display help for command

Advanced options:
  -d, --terraform-dir <path>             (Optional) The target local directory to store the generated Terraform (.tf) files
  -D, --dry-run                          (Optional) Skip running terraform apply; only generate the Terraform (.tf) files
  -f, --force                            (Optional) Force the copy toolchain command to run without user confirmation
  -S, --skip-s2s                         (Optional) Skip creating toolchain-generated service-to-service authorizations
  -T, --skip-disable-triggers            (Optional) Skip disabling Tekton pipeline Git or timed triggers. Note: This may result in duplicate pipeline runs
  -C, --compact                          (Optional) Generate all resources in a single resources.tf file
  -v, --verbose                          (Optional) Increase log output
  -q, --quiet                            (Optional) Suppress non-essential output, only errors and critical warnings are displayed

copy-toolchain 的運作方式是先將工具鏈轉譯為 Terraform (.tf) 檔案，然後應用 Terraform 在目的地區域建立新的工具鏈。 該指令會顯示 Terraform 輸出，並在建立工具鏈之前提示確認。 您可以在建立新的工具鏈副本之前檢閱 Terraform 的輸出。

export IBMCLOUD_API_KEY='<your_api_key>'
npx @ibm-cloud/cd-tools copy-toolchain -c 'crn:v1:bluemix:public:toolchain:au-syd:a/9d5d528aa786af01ce99593a827a05f0:69e8d78b-0d1a-49ed-9a46-3b4c1bb4f24a::' -r jp-tok

npx @ibm-cloud/cd-tools copy-toolchain -c "${CRN}" -r eu-de --apikey '<your_api_key>'

export IBMCLOUD_API_KEY='<your_api_key>'
npx @ibm-cloud/cd-tools copy-toolchain -c "${CRN}" -r us-south -n 'toolchain-dallas'

for i in $(ibmcloud resource service-instances --service-name toolchain --location ca-tor --all-resource-groups -o json | jq -r '.[].crn'); do
    npx @ibm-cloud/cd-tools copy-toolchain -c ${i} -r us-south --dry-run -f
done

for i in $(ibmcloud resource service-instances --service-name toolchain -g my-resource-group -o json | jq -r '.[].crn'); do
    npx @ibm-cloud/cd-tools copy-toolchain -c ${i} -r eu-de -q
done

for i in $(ibmcloud resource service-instances --service-name toolchain --all-resource-groups -o json | jq -r '.[] | select(.name | startswith("test-")) | .crn'); do
    npx @ibm-cloud/cd-tools copy-toolchain -c ${i} -r jp-tok
done

$ cd output-1764102115772
$ terraform apply
var.ibmcloud_api_key
  Enter a value: {api_key}
...

驗證資源

將工具鏈、Tekton 管線和 Git Repos and Issue Tracking 專案 (如果適用) 複製到新區域後，您應該在停用或刪除原始資源之前，驗證它們是否已正確複製且運作正常。 請注意：

• Tekton 管道定時和 Git 觸發器在複製管道中並未依預設啟用，以防止新管道和原始管道重複執行。 當您感到舒適時，就可以啟用新管道中的觸發器，並停用原始管道中的觸發器。
• 如果您有任何 webhook 類型的 Tekton 管道觸發器，您需要重新設定觸發器，並重新輸入秘訣。 此密碼不支援 密碼引用，且不會隨管道複製。
• 在已複製的 Git Repos and Issue Tracking 專案中擁有個人存取權限的使用者將需要重新建立新的權限，因為這些權限沒有被複製。
• Git Repos and Issue Tracking repos 的工具整合將已轉換為使用執行複製的使用者的 OAuth 身份。 如果您希望使用不同的身分，請使用該使用者登入，並重新儲存工具整合，或改用個人存取代碼。
• 在您的 Tekton 定義、指令碼、環境屬性或其他自動化程式中，可能會假設資源的 ID、URL 或位置。 建議您檢閱這些內容，以確保使用新的 ID、URL 和位置。

停用原始資源

在確認複製的資源正常運作後，您可以停用原始資源，以避免衝突或混亂。

• 對於 Tekton 管道，您可以停用您的觸發器，以避免不必要的管道執行，並向其他使用者示意不應再使用這些觸發器。
• 對於 Continuous Delivery 服務實例，如果您使用的是專業方案，您可以切換到精簡方案，以避免對原始資源收取更多的費用。 如果您超出了 Lite 計劃的限制，這可能會導致您的資源變成唯讀，但如果您需要再次使用這些資源，您可以隨時切換回 Professional。
• 對於 Git Repos 和問題追蹤專案 (如果適用)，您可以將原始專案歸檔，使其成為唯讀專案，防止使用者進一步變更，並可選擇更新專案說明或 readme，以指出新專案的位置。

即使您不打算保留原始資源，也可能希望保留原始資源一段時間作為備份，以防日後發現問題。 當您感到舒適時，就可以刪除原始資源。