分享方式:


從 GitHub 或 Azure Repos 新增和設定目錄

本文說明如何為您的 Azure 部署環境開發人員中心或專案新增和設定目錄

目錄可協助您提供一組策展的基礎結構即程式碼 (IaC) 範本,稱為開發小組用來建立環境的環境定義。 您可以從 GitHub 或 Azure DevOps 附加自己的原始檔控制存放庫作為目錄,並使用您的環境定義指定資料夾。 部署環境會掃描資料夾以取得環境定義,並讓開發小組能夠建立環境。

為進一步保護您的範本,目錄會進行加密;Azure 部署環境支援使用平臺管理的加密金鑰進行待用加密,這些金鑰由 Microsoft Azure 服務來管理。

  • 若要瞭解如何在 GitHub 中裝載存放庫,請參閱開始使用 GitHub
  • 若要了解如何在 Azure Repos 專案中裝載 Git 存放庫,請參閱 Azure Repos

Microsoft 提供一個快速入門目錄,您可以將其新增至開發人員中心或專案,還提供了一個樣本目錄,可用作存放庫。 您也可以使用自己的私人存放庫,也可以分支並自訂範例目錄中的環境定義。

在本文中,您將學會如何:

  1. 設定專案層級目錄
  2. 設定受控識別
  3. 從 Azure Repos 或 GitHub 新增目錄
  4. 更新目錄
  5. 刪除目錄
  6. 針對目錄同步錯誤進行疑難排解

設定專案層級目錄

在專案層級附加目錄可讓平台工程師提供開發小組專屬的策展環境定義。 此外,它可讓指派為專案管理員的開發小組負責人管理提供給其小組的環境定義。

平台工程師可以完全控制專案層級的目錄使用。 必須先在開發人員中心層級啟用專案層級目錄的使用,才能將目錄新增至專案。 平台工程師也可以設定可在專案層級取用的目錄項目類型,例如環境定義。

根據預設會停用專案層級的目錄使用,且不會啟用任何目錄項目類型。 專案層級目錄的環境定義會在兩個條件下同步處理及使用。 首先,您必須在對應的開發人員中心層級啟用專案型目錄。 其次,您必須啟用項目的環境定義使用。

將目錄新增至專案

您必須先在開發人員中心層級啟用專案層級目錄,才能將目錄新增至專案。 您也應該啟用在專案層級使用環境定義。

若要在開發人員中心層級啟用專案層級目錄的使用:

  1. Azure 入口網站中,瀏覽至您的開發人員中心。

  2. 在左側功能表的 [設定] 底下,選取 [設定]

    顯示開發人員中心 [概觀] 頁面的螢幕快照,其中已醒目提示 [設定]。

  3. 在 [ 專案層級目錄] 窗格中,選取 [ 為每個專案啟用目錄],然後選取 [ 套用]。

    顯示 [專案層級目錄] 窗格的螢幕快照,其中已醒目提示 [啟用每個項目的目錄]。

若要啟用項目中的環境定義使用:

  1. Azure 入口網站 中,流覽至您的專案。

  2. 在左側功能表中的 [設定] 下,選取 [目錄]。

    顯示已醒目提示目錄之專案的 [概觀] 頁面螢幕快照。

  3. 在 [ 目錄] 頁面上,選取 [ 目錄項目許可權]。

    顯示 [目錄] 窗格的螢幕快照,其中已醒目提示目錄項目許可權。

  4. 在 [ 目錄項目設定 ] 窗格中,選取 [Azure 部署環境定義 ] 以啟用專案層級的環境定義。

    顯示 [目錄項目設定] 窗格的螢幕快照,其中已選取 Azure 部署環境定義。

現在,您可以將目錄新增至專案。

對於使用受控識別或個人存取令牌進行驗證的目錄,您必須為專案指派受控識別。 對於使用 PAT 的目錄,您必須將 PAT 儲存在金鑰保存庫中,並將密鑰保存庫秘密的受控識別存取權授與。

設定受控識別

您必須先設定也稱為受管理的服務識別 (MSI) 的受控識別,才能將目錄附加至開發人員中心或專案。 您可以附加系統指派的受控識別 (系統指派的 MSI),也可以附加使用者指派的受控識別 (使用者指派的 MSI)。 接著,您要將角色指派給受控識別,以便開發人員中心或專案能夠在訂用帳戶中建立環境類型,並讀取包含目錄存放庫的 Azure Repos 專案。

如果您的開發人員中心或專案未附加 MSI,請遵循設定受控識別中的步驟來建立一個 MSI,並指派受控識別的角色。

若要深入了解受控識別,請參閱什麼是 Azure 資源受控識別?

新增目錄

可以從 Azure Repos 存放庫或 GitHub 存放庫新增目錄。 要選擇驗證,可以將權限指派給 MSI,也可以使用儲存在金鑰保存庫中的 PAT。

選取您要使用之存放庫類型和驗證的索引標籤。

若要新增目錄,請完成下列工作:

  • 在 Azure Repos 中指派受控識別的權限。
  • 將存放庫新增為目錄。

在 Azure Repos 中指派受控識別的權限

您必須將受控識別權限授與 Azure Repos 中的存放庫。

  1. 登入您的 Azure DevOps 組織

    注意

    您的 Azure DevOps 組織必須與包含開發人員中心或專案的 Azure 訂用帳戶位於同一個目錄中。

  2. 選取組織設定

    顯示 Azure DevOps 組織頁面的螢幕擷取畫面,其中已醒目提示 [組織設定]。

  3. 在 [概觀] 頁面上,選取 [使用者]

    顯示 [組織概觀] 頁面的螢幕擷取畫面,其中已醒目提示 [使用者]。

  4. 在 [使用者] 頁面上,選取 [新增使用者]

    顯示 [使用者] 頁面的螢幕擷取畫面,其中已醒目提示 [新增使用者]。

  5. 輸入或選取下列資訊以完成 [新增使用者],然後選取 [新增]

    名稱
    使用者或服務主體 輸入開發人員中心或專案的名稱。
    使用系統指派的 MSI 時,請指定開發人員中心或專案的名稱,而不是受控帳戶的物件識別碼。 使用使用者指派的 MSI 時,請使用受控帳戶的名稱。
    存取層級 選取 [基本]
    新增至專案 選取包含存放庫的專案。
    Azure DevOps 群組 選取 [專案讀取者]。
    傳送電子郵件邀請 (只給使用者) 清除核取方塊。

    顯示 [新增使用者] 的螢幕擷取畫面,其中已醒目提示範例項目和 [新增]。

將存放庫新增為目錄

Azure 部署環境支持連結 Azure Repos 存放庫和 GitHub 存放庫。 您可以將一組策展的 IaC 範本儲存在存放庫中。 將存放庫作為目錄附加至開發人員中心或專案可讓您的開發小組存取範本,並且能讓開發小組快速建立一致的環境。

下列步驟可讓您連結 Azure Repos 存放庫。

  1. Azure 入口網站中,瀏覽至您的開發人員中心或專案。

  2. 在左側功能表的 [環境設定] 下,選取 [目錄],然後選取 [新增]

    顯示 [目錄] 窗格的螢幕擷取畫面。

  3. 在 [新增目錄] 中,輸入下列資訊,然後選取 [新增]

    欄位
    名稱 輸入目錄的名稱。
    目錄位置 選取 [Azure DevOps]
    驗證類型 選取 [受控識別]。
    組織 選取您的 Azure DevOps 組織。
    計畫 從專案清單中,選取儲存存放庫的專案。
    存放庫 從存放庫清單中,選取您要新增的存放庫。
    分支 選取分支。
    資料夾路徑 開發箱會擷取分支中的資料夾清單。 選取儲存 IaC 範本的資料夾。

    顯示 [新增目錄] 窗格的螢幕擷取畫面,其中已醒目提示範例項目和 [新增]。

  4. 在開發人員中心或專案的 [目錄] 中,確認您的目錄有顯示。 連線成功時,[狀態] 會讀取 [同步成功]。 第一次連線到目錄可能需要幾分鐘的時間。

檢視同步的目錄項目

不論您使用的存放庫類型為何,您都可以檢視從目錄同步的目錄項目。

  1. 在開發人員中心或專案的左側功能表上,選取 [環境設定] 底下的 [目錄]

  2. 在 [目錄] 窗格中,選取目錄名稱。

    顯示 [目錄] 窗格的螢幕擷取畫面,其中已醒目提示附加的目錄名稱。

  3. 您會看到已成功同步的目錄項目清單。

    顯示已從附加目錄成功同步目錄項目的螢幕擷取畫面。

更新目錄

如果您在連結的存放庫中更新定義或範本內容,可以藉由同步目錄,將最新一組的環境定義提供給開發小組。 您可以手動或自動同步目錄。

手動同步目錄

當您手動同步目錄時,部署環境會掃描存放庫,並讓開發人員中心內所有相關聯專案都能使用最新的環境定義清單。

  1. 在開發人員中心的左側功能表上,選取 [環境設定] 底下的 [目錄]

  2. 選取特定的目錄,然後從命令列選取 [同步]

    顯示命令列中 [同步] 按鈕的螢幕擷取畫面。

自動同步目錄

當您設定目錄以自動同步時,部署環境每隔 30 分鐘會掃描一次存放庫,並讓開發人員中心內所有相關聯的專案都能使用最新的環境定義清單。

  1. 在開發人員中心或專案的左側功能表上,選取 [環境設定] 底下的 [目錄]

  2. 選取特定的目錄,然後選取 [編輯]。

    顯示目錄編輯按鈕的螢幕擷取畫面。

  3. 在 [編輯目錄] 窗格中,選取 [自動同步此目錄],然後選取 [儲存]

    顯示目錄編輯詳細資料窗格的螢幕擷取畫面,其中已醒目提示 [自動同步此目錄]。

刪除目錄

您可以刪除目錄,以從 Azure 部署環境開發人員中心或專案移除。 開發小組部署新環境時,已刪除目錄中的範本將無法使用。 針對使用已刪除目錄中的環境定義所建立的任何現有環境,更新環境定義參考。 若沒有更新參考並重新部署環境,部署就會失敗。

若要刪除目錄:

  1. 在開發人員中心或專案的左側功能表上,選取 [環境設定] 底下的 [目錄]

  2. 選取特定的目錄,然後選取 [刪除]

  3. 在 [刪除目錄] 對話方塊中,選取 [繼續] 以刪除目錄。

針對目錄同步錯誤進行疑難排解

新增或同步目錄時,可能會遇到同步錯誤或警告。 同步錯誤表示目錄無法成功同步,同步警告表示部分或所有目錄項目都有錯誤。 您可以在 Azure 入口網站中檢視同步狀態和錯誤,或使用 Azure CLI 和 REST API 來疑難排解並解決錯誤。

檢視目錄同步狀態

在 Azure 入口網站中,您可以選取狀態連結,以取得目錄同步狀態和任何警告或錯誤的詳細資訊。 狀態連結會開啟一個窗格,其中顯示同步狀態、已新增的環境定義數目,以及忽略或失敗的環境定義數目。

檢視目錄同步失敗

  1. 在開發人員中心或專案的左側功能表上,選取 [環境設定] 底下的 [目錄]

  2. 在 [狀態] 資料行中,選取無法同步目錄的狀態連結。

    顯示 [目錄] 窗格的螢幕擷取畫面,其中已醒目提示同步失敗。

  3. 您會看到詳細資料窗格,其中顯示上次同步的變更、同步錯誤數目,以及錯誤類型。

    顯示 [目錄同步失敗] 窗格的螢幕擷取畫面。

檢視目錄同步警告

  1. 在開發人員中心或專案的左側功能表上,選取 [環境設定] 底下的 [目錄]

  2. 在 [狀態] 資料行中,選取已同步但報告警告之目錄的狀態連結。

    顯示 [目錄] 窗格的螢幕擷取畫面,其中已醒目提示 3 個項目中的錯誤。

  3. 您會看到詳細資料窗格,其中顯示上次同步的變更、項目錯誤數目,以及每個錯誤的類型和來源。

    顯示 [目錄同步錯誤] 窗格的螢幕擷取畫面。

  4. 您可以從也報告同步錯誤的目錄中,檢視已成功同步的項目。 從 [目錄] 窗格中,選取目錄名稱。

    顯示 [目錄] 窗格的螢幕擷取畫面,其中已醒目提示目錄名稱。

  5. 您會看到已成功同步的目錄項目清單。

    顯示已成功同步的目錄項目的螢幕擷取畫面。

使用 Azure CLI 針對目錄同步錯誤進行疑難排解

使用 Azure CLI 或 REST API 來 GET 目錄。 GET 回應會顯示錯誤類型:

  • 已忽略偵測為重複項目的環境定義。
  • 因為結構描述、參考或驗證錯誤而失敗的環境定義無效。

解決「已忽略環境定義」錯誤

如果您新增兩個或多個具有相同名稱的環境定義,就會發生「已忽略環境定義」錯誤。 您可以藉由重新命名環境定義來解決此問題,這會讓每個環境定義在目錄中都有唯一名稱。

解決「環境定義無效」錯誤

發生「環境定義無效」錯誤的原因有很多:

  • 資訊清單結構描述錯誤。 請確定您的環境定義環境檔案符合所需的架構

  • 驗證錯誤。 檢查下列項目以解決驗證錯誤:

    • 確定環境檔案的引擎類型已正確設定。
    • 確定環境定義名稱介於 3 到 63 個字元。
    • 確定環境定義名稱只包含對 URL 有效的字元,即英數字元和以下符號:~!,.';:=-_+()*&$@
  • 參考錯誤。 確定環境定義參考的範本路徑是存放庫中檔案的有效相對路徑。