設定容器映像以使用ARM和 Bicep 執行部署

文章
05/31/2024

在本文中，您將瞭解如何建置自定義的 Azure Resource Manager （ARM）和 Bicep 容器映射，以在 Azure 部署環境（ADE）中部署您的環境定義。

環境定義至少包含兩個檔案：範本檔案，例如 azuredeploy.json 或 main.bicep，以及名為 environment.yaml 的指令清單檔。 ADE 會使用容器來部署環境定義，並原生支援ARM和BicepIaC架構。

ADE 擴充性模型可讓您建立自定義容器映像，以搭配您的環境定義使用。藉由使用擴充性模型，您可以建立自己的自定義容器映像，並將其儲存在 DockerHub 等容器登錄中。然後，您可以在環境定義中參考這些映像來部署環境。

ADE 小組提供一系列映射，讓您開始使用，包括核心映射，以及 Azure Resource Manager （ARM）/Bicep 映射。您可以在 [執行器映射] 資料夾中存取這些範例影像。

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
在 Azure 訂用帳戶中設定的 Azure 部署環境。
- 若要設定 ADE，請遵循快速入門：設定 Azure 部署環境。

搭配 ADE 使用容器映像

您可以使用下列其中一種方法搭配 ADE 使用容器映像：

使用標準容器映像： 針對簡單案例，請使用 ADE 所提供的標準 Bicep 容器映像。
建立自定義容器映像： 針對更複雜的案例，請建立符合您特定需求的自定義容器映像。

無論您選擇哪種方法，都必須在環境定義中指定容器映像，以部署 Azure 資源。

使用標準 Bicep 容器映像

ADE 原生支援 Bicep，因此您可以將範本檔案（azuredeploy.json 和 environment.yaml）新增至目錄，以設定環境定義，以部署環境的 Azure 資源。 ADE 接著會使用標準 Bicep 容器映像來建立部署環境。

在 environment.yaml 檔案中，執行器屬性會指定您想要使用的容器映像位置。若要使用 Microsoft 成品登錄上發佈的範例映像，請使用下表所列的個別標識符執行器。

下列範例顯示參考範例 Bicep 容器映像的執行器：

    name: WebApp
    version: 1.0.0
    summary: Azure Web App Environment
    description: Deploys a web app in Azure without a datastore
    runner: Bicep
    templatePath: azuredeploy.json

您可以在 ARM-Bicep 映射的 [執行器-Images] 資料夾下的 ADE 範例存放庫中看到標準 Bicep 容器映像。

如需有關如何建立使用 ADE 容器映射來部署 Azure 資源的環境定義的詳細資訊，請參閱新增和設定環境定義。

建立自定義 Bicep 容器映像

建立自訂容器映像可讓您自定義部署以符合您的需求。您可以根據 ADE 標準容器映像建立自訂映像。

完成映像自定義之後，您必須建置映像，並將其推送至容器登錄。

使用 Docker 建立和自訂容器映像

在此範例中，您會瞭解如何建置 Docker 映像，以利用 ADE 部署並存取 ADE CLI，以您的映像作為其中一個 ADE 撰寫映像的基礎。

ADE CLI 是一種工具，可讓您使用 ADE 基底映射來建置自定義映像。您可以使用 ADE CLI 來自定義您的部署和刪除，以符合您的工作流程。 ADE CLI 會預先安裝在範例映像上。若要深入了解 ADE CLI，請參閱 CLI 自訂執行器映像參考 (部分機器翻譯)。

若要建立針對 ADE 設定的映像，請遵循下列步驟：

使用FROM語句，以 ADE 撰寫的範例影像或您選擇的影像為基礎。
使用 RUN 語句為您的映像安裝任何必要的套件。
在 與 Dockerfile 相同的層級建立腳本 資料夾、儲存 您的 deploy.sh 和 delete.sh 檔案，並確保這些腳本可在您建立的容器內探索和可執行檔。部署必須使用 ADE 核心映像執行此步驟。

使用 FROM 陳述式選取範例容器映像

在已建立的 DockerFile 中包含一個 FROM 陳述式，讓您的新映像指向 Microsoft 成品登錄上裝載的範例映像。

以下是參考範例核心映像的範例 FROM 陳述式：

FROM mcr.microsoft.com/deployment-environments/runners/core:latest

此陳述式會提取最近發佈的核心映像，並使它成為自訂映像的基礎。

在 Dockerfile 中安裝 Bicep

您可以使用 RUN 語句來安裝 Bicep 套件與 Azure CLI，如下列範例所示：

RUN az bicep install

ADE 範例映像是以 Azure CLI 映像為基礎，並預先安裝 ADE CLI 和 JQ 封裝。您可以深入了解 Azure CLI (部份機器翻譯) 和 JQ 封裝 (英文)。

若要在映像中安裝您需要的更多套件，請使用 RUN 陳述式。

執行作業殼層指令碼

在範例映像中，會根據作業名稱來決定和執行作業。目前，支援的兩個作業名稱為 deploy 和 delete。

若要設定自訂映像以利用此結構，請在名為 scripts 的 Dockerfile 層級指定一個資料夾，然後指定 deploy.sh 和 delete.sh 這兩個檔案。部署殼層指令碼會在建立或重新部署環境時執行，而刪除殼層指令碼會在刪除環境時執行。您可以在 ARM-Bicep 映射的 Runner-Images 資料夾下，查看存放庫中殼層腳本的範例。

若要確保這些殼層指令碼可執行，請將下列幾行新增至您的 Dockerfile：

COPY scripts/* /scripts/
RUN find /scripts/ -type f -iname "*.sh" -exec dos2unix '{}' '+'
RUN find /scripts/ -type f -iname "*.sh" -exec chmod +x {} \;

撰寫作業殼層腳本以部署ARM或 Bicep 範本

若要確保您可以透過 ADE 成功部署 ARM 或 Bicep 基礎結構，您必須：

將 ADE 參數轉換為 ARM 可接受的參數
如果在部署中使用連結的範本，請解決連結的範本
使用具特殊許可權的受控識別來執行部署

在核心映像的進入點期間，針對目前環境設定的任何參數會儲存在變數 $ADE_OPERATION_PARAMETERS之下。若要將它們轉換成 ARM 可接受的參數，您可以使用 JQ 執行下列命令：

# format the parameters as arm parameters
deploymentParameters=$(echo "$ADE_OPERATION_PARAMETERS" | jq --compact-output '{ "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#", "contentVersion": "1.0.0.0", "parameters": (to_entries | if length == 0 then {} else (map( { (.key): { "value": .value } } ) | add) end) }' )

接下來，若要解析 ARM JSON 型範本內使用的任何連結範本，您可以分解主要範本檔案，以解析許多 Bicep 模組中使用的所有本機基礎結構檔案。然後，將這些模組重建回單一 ARM 範本，並將連結的範本內嵌至主要 ARM 範本作為巢狀範本。只有在部署作業期間，才需要此步驟。您可以在核心映像進入點期間使用 $ADE_TEMPLATE_FILE 集合來指定主要範本檔案，而且您應該使用重新編譯的範本檔案來重設此變數。請參閱下列範例：

if [[ $ADE_TEMPLATE_FILE == *.json ]]; then

    hasRelativePath=$( cat $ADE_TEMPLATE_FILE | jq '[.. | objects | select(has("templateLink") and (.templateLink | has("relativePath")))] | any' )

    if [ "$hasRelativePath" = "true" ]; then
        echo "Resolving linked ARM templates"

        bicepTemplate="${ADE_TEMPLATE_FILE/.json/.bicep}"
        generatedTemplate="${ADE_TEMPLATE_FILE/.json/.generated.json}"

        az bicep decompile --file "$ADE_TEMPLATE_FILE"
        az bicep build --file "$bicepTemplate" --outfile "$generatedTemplate"

        # Correctly reassign ADE_TEMPLATE_FILE without the $ prefix during assignment
        ADE_TEMPLATE_FILE="$generatedTemplate"
    fi
fi

若要提供部署所需的許可權，您必須在訂用帳戶內執行部署和刪除資源，請使用與 ADE 專案環境類型相關聯的特殊許可權受控識別。如果您的部署需要特殊許可權才能完成，例如特定角色，請將這些角色指派給專案環境類型的身分識別。有時候，輸入容器時，無法立即取得受控識別;您可以重試，直到登入成功為止。

echo "Signing into Azure using MSI"
while true; do
    # managed identity isn't available immediately
    # we need to do retry after a short nap
    az login --identity --allow-no-subscriptions --only-show-errors --output none && {
        echo "Successfully signed into Azure"
        break
    } || sleep 5
done

若要開始部署 ARM 或 Bicep 範本，請執行 az deployment group create 命令。在容器內執行此命令時，請選擇不會覆寫任何過去部署的部署名稱，並使用 --no-prompt true 和 --only-show-errors 旗標來確保部署不會在任何警告或等待使用者輸入時停滯不前，如下列範例所示：

deploymentName=$(date +"%Y-%m-%d-%H%M%S")
az deployment group create --subscription $ADE_SUBSCRIPTION_ID \
    --resource-group "$ADE_RESOURCE_GROUP_NAME" \
    --name "$deploymentName" \
    --no-prompt true --no-wait \
    --template-file "$ADE_TEMPLATE_FILE" \
    --parameters "$deploymentParameters" \
    --only-show-errors

若要刪除環境，請執行完整模式部署並提供空的 ARM 範本，以移除指定 ADE 資源群組內的所有資源，如下列範例所示：

deploymentName=$(date +"%Y-%m-%d-%H%M%S")
az deployment group create --resource-group "$ADE_RESOURCE_GROUP_NAME" \
    --name "$deploymentName" \
    --no-prompt true --no-wait --mode Complete \
    --only-show-errors \
    --template-file "$DIR/empty.json"

您可以執行下列命令來檢查布建狀態和詳細資料。 ADE 會使用一些特殊函式，根據布建詳細數據來讀取並提供更多內容，您可以在 [執行器-映射] 資料夾中找到。簡單的實作可能如下所示：

if [ $? -eq 0 ]; then # deployment successfully created
    while true; do

        sleep 1

        ProvisioningState=$(az deployment group show --resource-group "$ADE_RESOURCE_GROUP_NAME" --name "$deploymentName" --query "properties.provisioningState" -o tsv)
        ProvisioningDetails=$(az deployment operation group list --resource-group "$ADE_RESOURCE_GROUP_NAME" --name "$deploymentName")

        echo "$ProvisioningDetails"

        if [[ "CANCELED|FAILED|SUCCEEDED" == *"${ProvisioningState^^}"* ]]; then

            echo -e "\nDeployment $deploymentName: $ProvisioningState"

            if [[ "CANCELED|FAILED" == *"${ProvisioningState^^}"* ]]; then
                exit 11
            else
                break
            fi
        fi
    done
fi

最後，若要檢視部署的輸出，並將其傳遞至 ADE，使其可透過 Azure CLI 存取，您可以執行下列命令：

deploymentOutput=$(az deployment group show -g "$ADE_RESOURCE_GROUP_NAME" -n "$deploymentName" --query properties.outputs)
if [ -z "$deploymentOutput" ]; then
    deploymentOutput="{}"
fi
echo "{\"outputs\": $deploymentOutput}" > $ADE_OUTPUTS

讓 ADE 能夠存取自訂映像

您必須建置 Docker 映射，並將其推送至容器登錄，使其可用於 ADE。您可以使用 Docker CLI 或 ADE 提供的腳本來建置映像。

選取適當的索引標籤，以深入瞭解每個方法。

使用 Docker CLI 建置映像
使用腳本建置容器映像

在建置要推送至登錄的映像之前，請確定電腦上已安裝 Docker 引擎。然後，瀏覽至 Dockerfile 的目錄，並執行下列命令：

docker build . -t {YOUR_REGISTRY}.azurecr.io/{YOUR_REPOSITORY}:{YOUR_TAG}

例如，若您要將映像儲存在名為 customImage 之登錄內的存放庫下，並以標記版本 1.0.0 上傳，您會執行：

docker build . -t {YOUR_REGISTRY}.azurecr.io/customImage:1.0.0

將 Docker 映像推送至登錄

若要使用自訂映像，您必須設定可公開存取的映像登錄，並啟用匿名映像提取。如此一來，Azure 部署環境就可以存取您的自訂映像，以在我們的容器中執行。

Azure Container Registry 是儲存容器映像和類似成品的 Azure 供應項目。

若要建立登錄 (可透過 Azure CLI、Azure 入口網站、PowerShell 命令等方式完成)，請遵循其中一個快速入門。

若要設定登錄以啟用匿名映像提取，請在 Azure CLI 中執行下列命令：

az login
az acr login -n {YOUR_REGISTRY}
az acr update -n {YOUR_REGISTRY} --public-network-enabled true
az acr update -n {YOUR_REGISTRY} --anonymous-pull-enabled true

當您準備好將映像推送至登錄時，請執行下列命令：

docker push {YOUR_REGISTRY}.azurecr.io/{YOUR_IMAGE_LOCATION}:{YOUR_TAG}

Microsoft 提供快速入門腳本來協助您開始使用。文稿會建置您的映像，並將它推送至存放庫 ade 底下的指定 Azure Container Registry （ACR）和標籤 latest。

若要使用文稿，您必須：

建立 Dockerfile 和 scripts 資料夾以支援 ADE 擴充性模型。
提供自定義映像的登錄名稱和目錄。
在PATH變數中安裝 Azure CLI 和 Docker Desktop。
具有推送至指定登錄的許可權。

您可以在這裏檢視文稿。

您可以在 PowerShell 中使用下列命令來呼叫文稿：

.\quickstart-image-build.ps1 -Registry '{YOUR_REGISTRY}' -Directory '{DIRECTORY_TO_YOUR_IMAGE}'

此外，如果您想要推送至特定的存放庫和標籤名稱，您可以執行：

.\quickstart-image.build.ps1 -Registry '{YOUR_REGISTRY}' -Directory '{DIRECTORY_TO_YOUR_IMAGE}' -Repository '{YOUR_REPOSITORY}' -Tag '{YOUR_TAG}'

將映像連線到您的環境定義

製作環境定義以在部署中使用您的自訂映像時，請在資訊清單檔 (environment.yaml 或 manifest.yaml) 上編輯 runner 屬性。

runner: "{YOUR_REGISTRY}.azurecr.io/{YOUR_REPOSITORY}:{YOUR_TAG}"

若要深入瞭解如何建立使用 ADE 容器映像來部署 Azure 資源的環境定義，請參閱新增和設定環境定義。

存取作業記錄和錯誤詳細資料

ADE 會將失敗部署的錯誤詳細資料儲存在 容器內的 $ADE_ERROR_LOG 檔案中。

針對失敗的部署進行疑難排解：

登入開發人員入口網站。
識別無法部署的環境，然後選取 [查看詳細資料]。
檢閱 [錯誤詳細資料] 區段中的錯誤詳細資料。

此外，您可以使用 Azure CLI 以利用下列命令來檢視環境的錯誤詳細資料：

az devcenter dev environment show --environment-name {YOUR_ENVIRONMENT_NAME} --project {YOUR_PROJECT_NAME}

若要檢視環境部署或刪除的作業記錄，請使用 Azure CLI 擷取環境的最新作業，然後檢視該作業識別碼的記錄。

# Get list of operations on the environment, choose the latest operation
az devcenter dev environment list-operation --environment-name {YOUR_ENVIRONMENT_NAME} --project {YOUR_PROJECT_NAME}
# Using the latest operation ID, view the operation logs
az devcenter dev environment show-logs-by-operation --environment-name {YOUR_ENVIRONMENT_NAME} --project {YOUR_PROJECT_NAME} --operation-id {LATEST_OPERATION_ID}

ADE CLI 自訂執行器映像參考 (部分機器翻譯)
ADE CLI 變數參考

分享方式：

設定容器映像以使用ARM和 Bicep 執行部署

必要條件

搭配 ADE 使用容器映像

使用標準 Bicep 容器映像

建立自定義 Bicep 容器映像

使用 Docker 建立和自訂容器映像

使用 FROM 陳述式選取範例容器映像

在 Dockerfile 中安裝 Bicep

執行作業殼層指令碼

撰寫作業殼層腳本以部署ARM或 Bicep 範本

讓 ADE 能夠存取自訂映像

將 Docker 映像推送至登錄

將映像連線到您的環境定義

存取作業記錄和錯誤詳細資料

意見反映

意見反映

更多資源

分享方式：

設定容器映像以使用ARM和 Bicep 執行部署

必要條件

搭配 ADE 使用容器映像

使用標準 Bicep 容器映像

建立自定義 Bicep 容器映像

使用 Docker 建立和自訂容器映像

使用 FROM 陳述式選取範例容器映像

在 Dockerfile 中安裝 Bicep

執行作業殼層指令碼

撰寫作業殼層腳本以部署ARM或 Bicep 範本

讓 ADE 能夠存取自訂映像

將 Docker 映像推送至登錄

將映像連線到您的環境定義

存取作業記錄和錯誤詳細資料

相關內容

意見反映

意見反映

更多資源