本文內容
本文說明如何為您的 Azure 部署環境開發人員中心或專案新增和設定目錄 。
目錄可協助您提供一組策展的基礎結構即程式碼 (IaC) 範本,稱為開發小組用來建立環境的環境定義。 您可以從 GitHub 或 Azure Repos 附加自己的原始檔控制存放庫做為目錄,並使用您的環境定義指定資料夾。 部署環境會掃描資料夾以取得環境定義,並讓開發小組能夠建立環境。
為進一步保護您的範本,目錄會進行加密;Azure 部署環境支援使用平臺管理的加密金鑰進行待用加密,這些金鑰由 Microsoft Azure 服務來管理。
Microsoft 提供一個快速入門 目錄 ,您可以將其新增至開發人員中心或專案,還提供了一個樣本目錄 ,可用作存放庫。 您也可以使用自己的私人存放庫,也可以分支並自訂範例目錄中的環境定義。
在本文中,您將學會如何:
設定專案層級目錄
設定受控識別
從 Azure Repos 或 GitHub 新增目錄
更新目錄
刪除目錄
針對目錄同步錯誤進行疑難排解
在專案層級附加目錄可讓平台工程師提供開發小組專屬的策展環境定義。 此外,它可讓指派為專案管理員的開發小組負責人管理提供給其小組的環境定義。
平台工程師可以完全控制專案層級的目錄使用。 必須先在開發人員中心層級啟用專案層級目錄的使用,才能將目錄新增至專案。 平台工程師也可以設定可在專案層級取用的目錄項目類型,例如環境定義。
根據預設會停用專案層級的目錄使用,且不會啟用任何目錄項目類型。 專案層級目錄的環境定義會在兩個條件下同步並可供使用。 首先,您必須在對應的開發人員中心層級啟用專案型目錄。 其次,您必須啟用專案的環境定義使用。
將目錄新增至專案
您必須先在開發人員中心層級啟用專案層級目錄,才能將目錄新增至專案。 您也應該啟用專案層級的環境定義使用功能。
若要在開發人員中心層級啟用專案層級目錄的使用功能:
在 Azure 入口網站 中,瀏覽至您的開發人員中心。
在左側功能表的 [設定] 底下,選取 [設定] 。
在 [專案層級目錄] 窗格中,選取 [啟用每個專案的目錄] ,然後選取 [套用] 。
若要啟用專案內的環境定義使用功能:
在 [Azure 入口網站] 中,瀏覽至您的專案。
在 [設定] 下方的左側功能表中,選取 [目錄] 。
在 [目錄] 頁面上,選取 [目錄項目權限] 。
在 [目錄項目設定] 窗格中,選取 [Azure 部署環境定義] ,以在專案層級啟用環境定義的使用功能。
現在,您可以將目錄新增至專案。
對於使用受控識別或個人存取權杖 (PAT) 進行驗證的目錄,您必須為專案指派受控識別。 對於使用 PAT 的目錄,您必須將 PAT 儲存在金鑰保存庫中,並授與金鑰保存庫祕密的受控識別存取權。
您必須先設定也稱為受管理的服務識別 (MSI) 的受控識別 ,才能將目錄附加至開發人員中心或專案。 您可以附加系統指派的受控識別 (系統指派的 MSI),也可以附加使用者指派的受控識別 (使用者指派的 MSI)。 接著,您要將角色指派給受控識別,以便開發人員中心或專案能夠在訂用帳戶中建立環境類型,並讀取包含目錄存放庫的 Azure Repos 專案。
如果您的開發人員中心或專案未附加 MSI,請遵循設定受控識別 中的步驟來建立一個 MSI,並指派受控識別的角色。
若要深入了解受控識別,請參閱什麼是 Azure 資源受控識別?
新增目錄
可以從 Azure Repos 存放庫或 GitHub 存放庫新增目錄。 要選擇驗證,可以將權限指派給 MSI,也可以使用儲存在金鑰保存庫中的 PAT。
選取您要使用之存放庫類型和驗證的索引標籤。
若要新增目錄,請完成下列工作:
在 Azure Repos 中指派受控識別的權限。
將存放庫新增為目錄。
在 Azure Repos 中指派受控識別的權限
您必須將受控識別權限授與 Azure Repos 中的存放庫。
登入您的 Azure DevOps 組織 。
注意
您的 Azure DevOps 組織必須與包含開發人員中心或專案的 Azure 訂用帳戶位於同一個目錄中。
選取組織設定 。
在 [概觀] 頁面上,選取 [使用者] 。
在 [使用者] 頁面上,選取 [新增使用者] 。
輸入或選取下列資訊以完成 [新增使用者] ,然後選取 [新增] :
名稱
值
使用者或服務主體
輸入開發人員中心或專案的名稱。 使用系統指派的 MSI 時,請指定開發人員中心或專案的名稱,而不是受控帳戶的物件識別碼。 使用使用者指派的 MSI 時,請使用受控帳戶的名稱。
存取層級
選取 [基本] 。
新增至專案
選取包含存放庫的專案。
Azure DevOps 群組
選取 [專案讀取者]。
傳送電子郵件邀請 (只給使用者)
清除核取方塊。
將存放庫新增為目錄
Azure 部署環境支持連結 Azure Repos 存放庫和 GitHub 存放庫。 您可以將一組策展的 IaC 範本儲存在存放庫中。 將存放庫作為目錄附加至開發人員中心或專案可讓您的開發小組存取範本,並且能讓開發小組快速建立一致的環境。
下列步驟可讓您連結 Azure Repos 存放庫。
在 Azure 入口網站 中,瀏覽至您的開發人員中心或專案。
在左側功能表的 [環境設定] 下,選取 [目錄] ,然後選取 [新增] 。
在 [新增目錄] 中,輸入下列資訊,然後選取 [新增] ︰
欄位
值
名稱
輸入目錄的名稱。
目錄位置
選取 [Azure DevOps] 。
驗證類型
選取 [受控識別]。
組織
選取您的 Azure DevOps 組織。
計畫
從專案清單中,選取儲存存放庫的專案。
存放庫
從存放庫清單中,選取您要新增的存放庫。
分支
選取分支。
資料夾路徑
開發箱會擷取分支中的資料夾清單。 選取儲存 IaC 範本的資料夾。
在開發人員中心或專案的 [目錄] 中,確認您的目錄有顯示。 連線成功時,[狀態] 會讀取 [同步成功] 。 第一次連線到目錄可能需要幾分鐘的時間。
若要新增目錄,請完成下列工作:
取得 Azure Repos 存放庫的複製 URL。
建立個人存取權杖 (PAT)。
將 PAT 儲存為 Azure Key Vault 中的金鑰保存庫秘密。
將存放庫新增為目錄。
取得 Azure Repos 存放庫的複製 URL
移至您的小組集合首頁 (例如 https://contoso-web-team.visualstudio.com
),然後選取專案。
取得 Azure Repos Git 存放庫的複製 URL 。
複製並儲存 URL。
在 Azure Repos 中建立個人存取權杖
移至您的小組集合首頁 (例如 https://contoso-web-team.visualstudio.com
),然後選取專案。
建立 PAT 。
複製並儲存產生的令牌,以供稍後使用。
建立 Key Vault
您需要 Azure Key Vault 來儲存 PAT,後者用來授與 Azure 對存放庫的存取權。 金鑰保存庫可以使用存取原則或角色型存取控制 (RBAC) 來控制存取。 如果您已經擁有一個金鑰保存庫,可以直接使用,但您應該檢查其是否使用存取原則或 RBAC 指派來控制存取。 如需瞭解有關設定金鑰保存庫存取原則的說明,請參閱指派金鑰保存庫存取原則 。
使用下列步驟建立 RBAC 金鑰保存庫:
登入 Azure 入口網站 。
在 [搜尋] 方塊中輸入 Key Vault 。
從結果清單中,選取 [Key Vault] 。
在 [金鑰保存庫] 頁面上,選取 [建立]。
在 [建立金鑰保存庫] 索引標籤上提供下列資訊:
名稱
數值
名稱
輸入金鑰保存庫的名稱。
訂用帳戶
選取您要在其中建立金鑰保存庫的訂用帳戶。
資源群組
使用現有的資源群組,或選取 [新建],然後輸入資源群組的名稱。
地點
選取您要建立金鑰保存庫的位置或區域。
請讓其他選項維持預設值。
在 [存取原則] 索引標籤上,選取 [Azure 角色型存取控制] ,然後選取 [檢閱 + 建立]。
在 [檢閱 + 建立] 索引標籤中,選取 [建立] 。
如果您的組織原則要求您保持 Key Vault 私人不向網際網路公開,您可以將 Key Vault 設定為允許受信任的 Microsoft 服務略過防火牆規則。
若要了解如何允許受信任的 Microsoft 服務略過防火牆,請參閱設定 Azure Key Vault 網路設定 。
將個人存取令牌儲存在金鑰保存庫中
在金鑰保存庫的左側功能表中,選取 [秘密]。
在 [秘密] 頁面上,選取 [產生/匯入]。
在 [建立秘密] 頁面上:
在 [名稱] 方塊中,輸入秘密的描述性名稱。
在 [秘密值] 方塊中,貼上您稍早複製的 PAT。
選取 建立 。
取得秘密標識碼
取得您在金鑰保存庫中建立之秘密的路徑。
在 Azure 入口網站中,瀏覽至您的金鑰保存庫。
在金鑰保存庫頁面上,從左側功能表中選取 [秘密]。
在 [秘密] 頁面上,選取您剛剛建立的秘密。
在 [版本] 頁面上,選取 [目前的版本]。
在 [目前的版本] 頁面上,針對 [秘密標識符],選取 [複製]。
將存放庫新增為目錄
在 Azure 入口網站 中,前往您的開發人員中心或專案。
確定連結至開發人員中心或專案的身分識別 可以存取儲存個人存取權杖的金鑰保存庫祕密 。
在左側功能表的 [環境設定] 下,選取 [目錄] ,然後選取 [新增] 。
在 [新增目錄] 中,輸入下列資訊,然後選取 [新增] ︰
欄位
值
名稱
輸入目錄的名稱。
目錄位置
選取 [Azure DevOps] 。
驗證類型
選取 [個人存取令牌]。
組織
選取裝載目錄存放庫的組織。
計畫
選取儲存目錄存放庫的專案。
存放庫
選取儲存目錄的存放庫。
資料夾路徑
選取保存 IaC 範本的資料夾。
祕密識別碼
輸入包含存放庫 PAT 的秘密標識碼。 當您複製秘密標識碼時,連接字串會在結尾包含版本標識碼,如下列範例所示:https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat/9376b432b72441a1b9e795695708ea5a
。 移除版本標識碼,這可確保部署環境會從金鑰保存庫擷取最新版本的秘密。 如果您的 PAT 到期,則只需要更新金鑰保存庫。 範例祕密識別碼: https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat
在 [目錄] 中,確認您的目錄出現。 如果連線成功,則 [狀態] 為 [已連線] 。
若要新增目錄,請完成下列工作:
安裝及設定 Microsoft 開發人員中心應用程式
在 GitHub 中為存放庫指派權限。
將存放庫新增為目錄。
安裝 Microsoft 開發人員中心應用程式
登入 Azure 入口網站 。
瀏覽至您的開發人員中心或專案。
在左側功能表的 [環境設定] 下,選取 [目錄] ,然後選取 [新增] 。
在 [新增目錄] 窗格中,輸入或選取下列項目:
欄位
值
名稱
輸入目錄的名稱。
目錄來源
選取 [GitHub] 。
驗證類型
選取 [GitHub 應用程式] 。
若要安裝 Microsoft 開發人員中心應用程式,請選取 [設定您的存放庫] 。
如果系統提示您向 GitHub 進行驗證,請進行驗證。
在 [Microsoft DevCenter] 頁面上,選取 [設定] 。
選取包含您要新增為目錄之存放庫的 GitHub 組織。 您必須是組織的擁有者,才能安裝此應用程式。
在 [安裝 Microsoft DevCenter] 頁面上,選取 [僅選取存放庫] ,選取您要新增為目錄的存放庫,然後選取 [安裝] 。
您可以選取多個存放庫以新增為目錄。 您必須將每個存放庫新增為個別目錄,如將存放庫新增為目錄 中所述。
在 [Microsoft 的 Microsoft DevCenter 想要權限以:] 頁面上,檢閱所需的權限,然後選取 [授權 Microsoft 開發人員中心] 。
將存放庫新增為目錄
切換回到 Azure 入口網站。
在 [新增目錄] 中,輸入下列資訊,然後選取 [新增] ︰
欄位
值
存放庫
選取您要新增為目錄的存放庫。
分支
選取分支。
資料夾路徑
選取包含保存您環境定義之子資料夾的資料夾。
在 [目錄] 中,確認您的目錄出現。 連線成功時,[狀態] 會讀取 [同步成功] 。
若要新增目錄,請完成下列工作:
取得 GitHub 存放庫的複製 URL。
在 GitHub 中建立個人存取權杖 (PAT)。
將 PAT 儲存為 Azure Key Vault 中的金鑰保存庫秘密。
將存放庫新增為目錄。
取得 GitHub 存放庫的複製 URL
前往包含範本定義的 GitHub 存放庫首頁。
取得 GitHub 存放庫複製 URL 。
複製並儲存 URL。
在 GitHub 中建立個人存取權杖
Azure 部署環境支援使用傳統權杖或細部權杖向 GitHub 存放庫進行驗證。 在此範例中,您會建立一個細部權杖。
前往包含範本定義的 GitHub 存放庫首頁。
選取 GitHub 右上角的設定檔影像,然後選取 [設定] 。
在左側提要欄位中,選取 [開發人員設定] > [個人存取權杖] > [細部權杖]。
選取 [產生新的權杖] 。
在 [新增細部個人存取權杖] 頁面上,提供下列資訊:
名稱
值
權杖名稱
輸入權杖的描述名稱。
到期
選取以天為單位的權杖到期期間。
說明
輸入權杖的描述。
資源擁有者
選取存放庫的擁有者。
存放庫存取
選取 [僅選取存放庫]。
選取存放庫
選取包含環境定義的存放庫。
存放庫權限
展開 [存放庫權限] ,針對 [內容] ,請從 [存取] 列表中選取 [程式碼讀取] 。
選取 [產生權杖] 。
複製並儲存產生的令牌,以供稍後使用。
重要
使用儲存在 GitHub 組織內的私人存放庫時,您必須確定 GitHub PAT 已設定為授與對正確組織和其中存放庫的存取權。
組織內的傳統權杖在建立之後,必須向特定組織進行 SSO 授權。
細部權杖必須將權杖的擁有者設定為要授權的組織自身。
設定不正確的 PAT 可能會導致出現「找不到存放庫」錯誤。
建立 Key Vault
您需要 Azure Key Vault 來儲存 PAT,後者用來授與 Azure 對存放庫的存取權。 金鑰保存庫可以使用存取原則或角色型存取控制 (RBAC) 來控制存取。 如果您已經擁有一個金鑰保存庫,可以直接使用,但您應該檢查其是否使用存取原則或 RBAC 指派來控制存取。 如需瞭解有關設定金鑰保存庫存取原則的說明,請參閱指派金鑰保存庫存取原則 。
使用下列步驟建立 RBAC 金鑰保存庫:
登入 Azure 入口網站 。
在 [搜尋] 方塊中輸入「key vault」 。
從結果清單中,選取 [Key Vault] 。
在 [金鑰保存庫] 頁面上,選取 [建立]。
在 [建立金鑰保存庫] 索引標籤上提供下列資訊:
名稱
數值
名稱
輸入金鑰保存庫的名稱。
訂用帳戶
選取您要在其中建立金鑰保存庫的訂用帳戶。
資源群組
使用現有的資源群組,或選取 [新建],然後輸入資源群組的名稱。
地點
選取您要建立金鑰保存庫的位置或區域。
請讓其他選項維持預設值。
在 [存取原則] 索引標籤上,選取 [Azure 角色型存取控制] ,然後選取 [檢閱 + 建立]。
在 [檢閱 + 建立] 索引標籤中,選取 [建立] 。
如果您的組織原則要求您保持 Key Vault 私人不向網際網路公開,您可以將 Key Vault 設定為允許受信任的 Microsoft 服務略過防火牆規則。
若要了解如何允許受信任的 Microsoft 服務略過防火牆,請參閱設定 Azure Key Vault 網路設定 。
將個人存取令牌儲存在金鑰保存庫中
在金鑰保存庫的左側功能表中,選取 [秘密]。
在 [秘密] 頁面上,選取 [產生/匯入]。
在 [建立秘密] 頁面上:
在 [名稱] 方塊中,輸入秘密的描述性名稱。
在 [秘密值] 方塊中,貼上您的 PAT。
選取 建立 。
取得秘密標識碼
取得您在金鑰保存庫中建立之秘密的路徑。
在 Azure 入口網站中,瀏覽至您的金鑰保存庫。
在金鑰保存庫頁面上,從左側功能表中選取 [秘密]。
在 [秘密] 頁面上,選取您剛剛建立的秘密。
在 [版本] 頁面上,選取 [目前的版本]。
在 [目前的版本] 頁面上,針對 [秘密標識符],選取 [複製]。
將存放庫新增為目錄
在 Azure 入口網站中,移至您的開發人員中心。
確定連結至開發人員中心或專案的受控識別 可以存取儲存個人存取權杖的金鑰保存庫祕密 。
在左側功能表的 [環境設定] 下,選取 [目錄] ,然後選取 [新增] 。
在 [新增目錄] 中,輸入下列資訊,然後選取 [新增] 。
欄位
值
名稱
輸入目錄的名稱。
目錄位置
選取 [GitHub] 。
存放庫
輸入或貼上 GitHub 存放庫或 Azure Repos 存放庫的複製 URL。目錄範例: https://github.com/Azure/deployment-environments.git
分支
輸入要連接的存放庫分支。目錄範例: main
資料夾路徑
輸入相對於複製 URI 的資料夾路徑,此路徑包含用於保存環境定義的子資料夾。 資料夾路徑適用於包含環境定義環境檔案之子資料夾的資料夾,不適用於具有環境定義環境檔案本身的資料夾。 下圖顯示範例目錄資料夾結構。目錄範例: /Environments
資料夾路徑的開頭可以是正斜線 (/
),也可以不是。
祕密識別碼
輸入包含存放庫 PAT 的秘密標識碼。 當您複製秘密標識碼時,連接字串會在結尾包含版本標識碼,如下列範例所示:https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat/9376b432b72441a1b9e795695708ea5a
。 移除版本標識碼,這可確保部署環境會從金鑰保存庫擷取最新版本的秘密。 如果您的 PAT 到期,則只需要更新金鑰保存庫。 範例祕密識別碼: https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat
在 [目錄] 中,確認您的目錄出現。 連線成功時,[狀態] 會讀取 [同步成功] 。
檢視同步的目錄項目
不論您使用的存放庫類型為何,您都可以檢視從目錄同步的目錄項目。
在開發人員中心或專案的左側功能表上,選取 [環境設定] 底下的 [目錄] 。
在 [目錄] 窗格中,選取目錄名稱。
您會看到已成功同步的目錄項目清單。
更新目錄
如果您在連結的存放庫中更新定義或範本內容,可以藉由同步目錄,將最新一組的環境定義提供給開發小組。 您可以手動或自動同步目錄。
手動同步目錄
當您手動同步目錄時,部署環境會掃描存放庫,並讓開發人員中心內所有相關聯專案都能使用最新的環境定義清單。
在開發人員中心的左側功能表上,選取 [環境設定] 底下的 [目錄] 。
選取特定的目錄,然後從命令列選取 [同步] 。
自動同步目錄
當您設定目錄以自動同步時,部署環境每隔 30 分鐘會掃描一次存放庫,並讓開發人員中心內所有相關聯的專案都能使用最新的環境定義清單。
在開發人員中心或專案的左側功能表上,選取 [環境設定] 底下的 [目錄] 。
選取特定的目錄,然後選取 [編輯]。
在 [編輯目錄] 窗格中,選取 [自動同步此目錄] ,然後選取 [儲存] 。
如果自動同步失敗,您應該執行手動同步處理。在手動同步處理成功之前,部署環境不會再進行任何自動同步處理嘗試。
刪除目錄
您可以刪除目錄,以從 Azure 部署環境開發人員中心或專案移除。 開發小組部署新環境時,已刪除目錄中的範本將無法使用。 針對使用已刪除目錄中的環境定義所建立的任何現有環境,更新環境定義參考。 若沒有更新參考並重新部署環境,部署就會失敗。
若要刪除目錄:
在開發人員中心或專案的左側功能表上,選取 [環境設定] 底下的 [目錄] 。
選取特定的目錄,然後選取 [刪除] 。
在 [刪除目錄] 對話方塊中,選取 [繼續] 以刪除目錄。
針對目錄同步錯誤進行疑難排解
新增或同步目錄時,可能會遇到同步錯誤或警告。 同步錯誤表示目錄無法成功同步,同步警告表示部分或所有目錄項目都有錯誤。 您可以在 Azure 入口網站中檢視同步狀態和錯誤,或使用 Azure CLI 和 REST API 來疑難排解並解決錯誤。
檢視目錄同步狀態
在 Azure 入口網站中,您可以選取狀態連結,以取得目錄同步狀態和任何警告或錯誤的詳細資訊。 狀態連結會開啟一個窗格,其中顯示同步狀態、已新增的環境定義數目,以及忽略或失敗的環境定義數目。
檢視目錄同步失敗
在開發人員中心或專案的左側功能表上,選取 [環境設定] 底下的 [目錄] 。
在 [狀態] 資料行中,選取無法同步目錄的狀態連結。
您會看到詳細資料窗格,其中顯示上次同步的變更、同步錯誤數目,以及錯誤類型。
檢視目錄同步警告
在開發人員中心或專案的左側功能表上,選取 [環境設定] 底下的 [目錄] 。
在 [狀態] 資料行中,選取已同步但報告警告之目錄的狀態連結。
您會看到詳細資料窗格,其中顯示上次同步的變更、項目錯誤數目,以及每個錯誤的類型和來源。
您可以從也報告同步錯誤的目錄,檢視成功同步處理的專案。 從 [目錄] 窗格中,選取目錄名稱。
您會看到已成功同步的目錄項目清單。
使用 Azure CLI 針對目錄同步錯誤進行疑難排解
使用 Azure CLI 或 REST API 來 GET 目錄。 GET 回應會顯示錯誤類型:
已忽略偵測為重複項目的環境定義。
因為結構描述、參考或驗證錯誤而失敗的環境定義無效。
解決「已忽略環境定義」錯誤
如果您新增兩個或多個具有相同名稱的環境定義,就會發生「已忽略環境定義」錯誤。 您可以藉由重新命名環境定義來解決此問題,這會讓每個環境定義在目錄中都有唯一名稱。
解決「環境定義無效」錯誤
發生「環境定義無效」錯誤的原因有很多:
相關內容