設定容器映像以使用 Terraform 執行部署

文章
05/31/2024

在本文中，您將瞭解如何建置自定義 Terraform 容器映射，以在 Azure 部署環境（ADE）中部署環境定義。您將瞭解如何設定自定義映像，以使用 Terraform 基礎結構即程式代碼（IaC）架構來布建基礎結構。

環境定義至少包含兩個檔案：範本檔案，例如 main.tf，以及名為 environment.yaml 的指令清單檔案。您可以使用容器來部署使用 Terraform 的環境定義。

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

必要條件

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

建立自定義 Terraform 容器映像

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

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

使用 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 中安裝 Terraform

您可以將 Terraform CLI 安裝到可執行檔位置，使其可用於部署和刪除腳本。

以下是該程式的範例，安裝 Terraform CLI 1.7.5 版：

RUN wget -O terraform.zip https://releases.hashicorp.com/terraform/1.7.5/terraform_1.7.5_linux_amd64.zip
RUN unzip terraform.zip && rm terraform.zip
RUN mv terraform /usr/bin/terraform

提示

您可以從 Hashicorp 版本取得慣用 Terraform CLI 版本的下載 URL。

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 {} \;

撰寫作業殼層腳本以使用 Terraform CLI

透過 Terraform 部署基礎結構有三個步驟：

terraform init - 初始化 Terraform CLI 以在工作目錄中執行動作
terraform plan- 根據傳入的 Terraform 基礎結構檔案和變數，以及任何現有的狀態檔案來開發計劃，並開發建立或更新 .tf 檔案中指定的基礎結構所需的步驟
terraform apply - 套用方案以在 Azure 中建立新的或更新現有的基礎結構

在核心映像的進入點期間，任何現有的狀態檔案都會提取到容器中，並將目錄儲存在環境變數 $ADE_STORAGE下。此外，針對儲存在變數 $ADE_OPERATION_PARAMETERS下之目前環境所設定的任何參數。若要存取現有的狀態檔案，並在.tfvars.json檔案中設定變數，請執行下列命令：

EnvironmentState="$ADE_STORAGE/environment.tfstate"
EnvironmentPlan="/environment.tfplan"
EnvironmentVars="/environment.tfvars.json"

echo "$ADE_OPERATION_PARAMETERS" > $EnvironmentVars

此外，若要利用 ADE 許可權在訂用帳戶內部署基礎結構，您的腳本在使用 Terraform AzureRM 提供者布建基礎結構時，必須使用受控服務識別（MSI）。若您的部署需要特殊權限才能完成部署，例如特定角色，請將這些權限指派給用於環境部署的專案環境類型身分識別。 ADE 會設定相關的環境變數，例如核心映射進入點內的用戶端、租使用者和訂用帳戶標識碼，因此請執行下列命令，以確保提供者使用 ADE MSI：

export ARM_USE_MSI=true
export ARM_CLIENT_ID=$ADE_CLIENT_ID
export ARM_TENANT_ID=$ADE_TENANT_ID
export ARM_SUBSCRIPTION_ID=$ADE_SUBSCRIPTION_ID

如果您有其他變數可在範本中參考，但未在環境參數中指定，請使用前置詞 TF_VAR設定環境變數。提供的 ADE 環境變數清單已提供 Azure 部署環境 CLI 變數參考。這些命令的範例可能是;

export TF_VAR_resource_group_name=$ADE_RESOURCE_GROUP_NAME
export TF_VAR_ade_env_name=$ADE_ENVIRONMENT_NAME
export TF_VAR_env_name=$ADE_ENVIRONMENT_NAME
export TF_VAR_ade_subscription=$ADE_SUBSCRIPTION_ID
export TF_VAR_ade_location=$ADE_ENVIRONMENT_LOCATION
export TF_VAR_ade_environment_type=$ADE_ENVIRONMENT_TYPE

現在，您可以執行先前列出的步驟來初始化 Terraform CLI、產生布建基礎結構的計劃，並在部署腳本期間套用計劃：

terraform init
terraform plan -no-color -compact-warnings -refresh=true -lock=true -state=$EnvironmentState -out=$EnvironmentPlan -var-file="$EnvironmentVars"
terraform apply -no-color -compact-warnings -auto-approve -lock=true -state=$EnvironmentState $EnvironmentPlan

在刪除文稿期間，您可以將旗標新增 destroy 至計劃產生以刪除現有的資源，如下列範例所示：

terraform init
terraform plan -no-color -compact-warnings -destroy -refresh=true -lock=true -state=$EnvironmentState -out=$EnvironmentPlan -var-file="$EnvironmentVars"
terraform apply -no-color -compact-warnings -auto-approve -lock=true -state=$EnvironmentState $EnvironmentPlan

最後，若要透過 Azure CLI 存取環境時上傳和存取部署的輸出，請透過 JQ 套件將輸出物件從 Terraform 轉換為 ADE 指定的格式。將值設定為 $ADE_OUTPUTS 環境變數，如下列範例所示：

tfOutputs=$(terraform output -state=$EnvironmentState -json)
# Convert Terraform output format to ADE format.
tfOutputs=$(jq 'walk(if type == "object" then 
            if .type == "bool" then .type = "boolean" 
            elif .type == "list" then .type = "array" 
            elif .type == "map" then .type = "object" 
            elif .type == "set" then .type = "array" 
            elif (.type | type) == "array" then 
                if .type[0] == "tuple" then .type = "array" 
                elif .type[0] == "object" then .type = "object" 
                elif .type[0] == "set" then .type = "array" 
                else . 
                end 
            else . 
            end 
        else . 
        end)' <<< "$tfOutputs")

echo "{\"outputs\": $tfOutputs}" > $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 會將失敗部署的錯誤詳細資料儲存在 容器內的 $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 變數參考

分享方式：

設定容器映像以使用 Terraform 執行部署

必要條件

建立自定義 Terraform 容器映像

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

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

在 Dockerfile 中安裝 Terraform

執行作業殼層指令碼

撰寫作業殼層腳本以使用 Terraform CLI

讓 ADE 能夠存取自訂映像

將 Docker 映像推送至登錄

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

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

意見反映

意見反映

更多資源

分享方式：

設定容器映像以使用 Terraform 執行部署

必要條件

建立自定義 Terraform 容器映像

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

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

在 Dockerfile 中安裝 Terraform

執行作業殼層指令碼

撰寫作業殼層腳本以使用 Terraform CLI

讓 ADE 能夠存取自訂映像

將 Docker 映像推送至登錄

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

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

相關內容

意見反映

意見反映

更多資源