Freigeben über

Konfigurieren eines Containerimages zum Ausführen von Bereitstellungen mit Terraform

  • Artikel

In diesem Artikel erfahren Sie, wie Sie benutzerdefinierte Terraform-Containerimages erstellen, um Ihre Umgebungsdefinitionen in Azure Deployment Environments (ADE) bereitzustellen. Sie erfahren, wie Sie ein benutzerdefiniertes Image für die Bereitstellung von Infrastruktur mithilfe des Terraform-IaC-Frameworks (Infrastructure-as-Code) konfigurieren.

Eine Umgebungsdefinition umfasst mindestens zwei Dateien: eine Vorlagendatei, z. B. main.tf und eine Manifestdatei namens environment.yaml. Sie verwenden einen Container, um die Umgebungsdefinition bereitzustellen, die Terraform verwendet.

Mit dem ADE-Erweiterbarkeitsmodell können Sie benutzerdefinierte Containerimages erstellen, die mit Ihren Umgebungsdefinitionen verwendet werden. Mithilfe dieses Erweiterbarkeitsmodells können Sie eigene benutzerdefinierte Containerimages erstellen und in einer Containerregistrierung wie DockerHub speichern. Anschließend können Sie in Ihren Umgebungsdefinitionen auf diese Images verweisen, um Ihre Umgebungen bereitzustellen.

Voraussetzungen

Erstellen Sie ein benutzerdefiniertes Terraform-Containerimage

Durch das Erstellen eines benutzerdefinierten Containerimage können Sie Ihre Bereitstellungen an Ihre Anforderungen anpassen.

Nachdem Sie die Imageanpassung abgeschlossen haben, müssen Sie das Image kompilieren und in die Containerregistrierung pushen.

Erstellen und Anpassen eines Containerimage mit Docker

In diesem Beispiel erfahren Sie, wie Sie ein Docker-Image erstellen, um ADE-Bereitstellungen zu nutzen und auf die ADE CLI zuzugreifen, indem Sie als Grundlage für Ihr Image eines der erstellten ADE-Images verwenden.

Die ADE CLI ist ein Tool, mit dem Sie benutzerdefinierte Images mithilfe von ADE-Basisimages erstellen können. Sie können die ADE CLI verwenden, um Ihre Bereitstellungen und Löschungen an Ihren Workflow anzupassen. Die ADE CLI ist auf den Beispielimages vorinstalliert. Weitere Informationen zur ADE CLI finden Sie in der Referenz zur CLI für benutzerdefinierte Runner-Images.

Führen Sie die folgenden Schritte aus, um ein für ADE konfiguriertes Image zu erstellen:

  1. Basieren Sie Ihr Image auf einem in ADE erstellten Beispielimage oder einem Image Ihrer Wahl, indem Sie die FROM-Anweisung verwenden.
  2. Installieren Sie mithilfe der RUN-Anweisung alle erforderlichen Pakete für Ihr Image.
  3. Erstellen Sie auf der Ebene, auf der sich Ihre Dockerfile-Datei befindet, einen Ordner namens scripts, speichern Sie Ihre Dateien deploy.sh und delete.sh darin, und stellen Sie sicher, dass diese Skripts in Ihrem erstellten Container auffindbar und ausführbar sind. Dieser Schritt ist erforderlich, damit Ihre Bereitstellung mit dem ADE-Kernimage funktioniert.

Auswählen eines Beispielcontainerimages mithilfe der FROM-Anweisung

Fügen Sie eine FROM-Anweisung in ein erstelltes Dockerfile für Ihr neues Image ein, die auf ein Beispielimage zeigt, das in der Microsoft-Artefaktregistrierung gehostet wird.

Hier ist eine FROM-Beispielanweisung, die auf das Beispielkernimage verweist:

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

Diese Anweisung ruft das zuletzt veröffentlichte Kernimage ab und macht es zur Grundlage für Ihr benutzerdefiniertes Image.

Installieren von Terraform in einem Dockerfile

Sie können die Terraform CLI an einem ausführbaren Speicherort installieren, damit sie in Ihren Bereitstellungs- und Löschskripts verwendet werden kann.

Das folgende Beispiel veranschaulicht diesen Prozess für die Installation von Version 1.7.5 der Terraform-CLI:

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

Tipp

Sie können die Download-URL für Ihre bevorzugte Version der Terraform-CLI von Hashicorp-Releases erhalten.

Die ADE-Beispielimages basieren auf dem Azure CLI-Image, in dem die ADE CLI- und JQ-Pakete bereits vorinstalliert sind. Erfahren Sie mehr über die Azure-Befehlszeilenschnittstelle und das JQ-Paket.

Verwenden Sie die RUN-Anweisung, um weitere Pakete zu installieren, die Sie in Ihrem Image benötigen.

Shellskripts für Ausführungsvorgänge

Innerhalb der Beispielimages werden Vorgänge basierend auf dem Vorgangsnamen bestimmt und ausgeführt. Derzeit werden die beiden Vorgangsnamen deploy und delete unterstützt.

Wenn Sie Ihr benutzerdefiniertes Image so einrichten möchten, dass diese Struktur verwendet wird, geben Sie einen Ordner auf der Ebene Ihres Dockerfiles scripts sowie die beiden Dateien deploy.sh und delete.sh an. Das Shellskript für die Bereitstellung wird ausgeführt, wenn Ihre Umgebung erstellt oder erneut bereitgestellt wird, während das Shellskript für die Löschung ausgeführt wird, wenn Ihre Umgebung gelöscht wird. Beispiele für Shellskripts finden Sie im Repository im Ordner Runner-Images für das ARM-Bicep-Image.

Um sicherzustellen, dass diese Shellskripts ausführbar sind, fügen Sie Ihrem Dockerfile die folgenden Zeilen hinzu:

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

Erstellen von Shellskripts für Vorgänge zum Verwenden der Terraform CLI

Die Bereitstellung der Infrastruktur über Terraform umfasst drei Schritte:

  1. terraform init initialisiert die Terraform CLI, um Aktionen im Arbeitsverzeichnis auszuführen.
  2. terraform plan entwickelt einen Plan basierend auf den eingehenden Terraform-Infrastrukturdateien und -variablen sowie vorhandenen Zustandsdateien und entwickelt die zum Erstellen oder Aktualisieren der in den TF-Dateien angegebenen Infrastruktur erforderlichen Schritte.
  3. terraform apply wendet den Plan an, um eine neue Infrastruktur in Azure zu erstellen oder eine vorhandene zu aktualisieren.

Während des Einstiegspunkts des Kernimages werden alle vorhandenen Zustandsdateien in den Container und das unter der Umgebungsvariable $ADE_STORAGE gespeicherte Verzeichnis gepullt. Darüber hinaus werden alle Parameter, die für die aktuelle Umgebung festgelegt wurden, in der Variable $ADE_OPERATION_PARAMETERS gespeichert. Um auf die vorhandene Zustandsdatei zuzugreifen und die Variablen in der Datei .tfvars.json festzulegen, führen Sie die folgenden Befehle aus:

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

echo "$ADE_OPERATION_PARAMETERS" > $EnvironmentVars

Darüber hinaus muss Ihr Skript, um die ADE-Berechtigungen zum Bereitstellen der Infrastruktur in Ihrem Abonnement zu nutzen, die verwaltete Dienstidentität (Managed Service Identity, MSI) beim Bereitstellen der Infrastruktur mithilfe des Terraform AzureRM-Anbieters verwenden. Wenn für den Abschluss Ihrer Bereitstellung spezielle Berechtigungen erforderlich sind (z. B. bestimmte Rollen), weisen Sie diese Berechtigungen der Identität des Projektumgebungstyps zu, der für die Bereitstellung Ihrer Umgebung verwendet wird. ADE legt die relevanten Umgebungsvariablen (z. B. Client-, Mandanten- und Abonnement-IDs) innerhalb des Einstiegspunkts des Kernimages fest. Führen Sie daher die folgenden Befehle aus, um sicherzustellen, dass der Anbieter die MSI von ADE verwendet:

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

Wenn Sie innerhalb Ihrer Vorlage auf andere Variablen verweisen möchten, die nicht in den Parametern Ihrer Umgebung angegeben sind, legen Sie Umgebungsvariablen mithilfe des Präfixes TF_VAR fest. Eine Liste der bereitgestellten ADE-Umgebungsvariablen finden Sie unter Referenz der CLI-Variablen von Azure Deployment Environments. Ein mögliches Beispiel für diese Befehle:

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

Nun können Sie die oben aufgeführten Schritte ausführen, um die Terraform CLI zu initialisieren, einen Plan für die Bereitstellung der Infrastruktur zu generieren und diesen in Ihrem Bereitstellungsskript anzuwenden:

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

Sie können wie im folgenden Beispiel gezeigt im Löschskript das Flag destroy für die Plangenerierung hinzufügen, um die vorhandenen Ressourcen zu löschen:

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

Um die Ausgaben Ihrer Bereitstellung hochzuladen und über die Azure-Befehlszeilenschnittstelle beim Zugriff auf Ihre Umgebung zugänglich zu machen, transformieren Sie das Ausgabeobjekt von Terraform über das JQ-Paket in das ADE-Format. Legen Sie den Wert auf die Umgebungsvariable „$ADE_OUTPUTS“ fest, wie im folgenden Beispiel gezeigt:

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

Machen Sie das benutzerdefinierte Image für ADE zugänglich

Sie müssen Ihr Docker-Image kompilieren und an Ihre Containerregistrierung pushen, um es für die Verwendung in ADE verfügbar zu machen. Sie können Ihr Image mithilfe der Docker-CLI oder mithilfe eines Skripts erstellen, das von ADE bereitgestellt wird.

Wählen Sie die entsprechende Registerkarte aus, um mehr über die einzelnen Ansätze zu erfahren.

Bevor Sie das Image erstellen, das an Ihre Registrierung gepusht werden soll, stellen Sie sicher, dass die Docker-Engine auf Ihrem Computer installiert ist. Navigieren Sie dann zum Verzeichnis Ihres Dockerfiles, und führen Sie den folgenden Befehl aus:

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

Wenn Sie Ihr Image beispielsweise in einem Repository in Ihrer Registrierung mit dem Namen customImage speichern und mit der Tagversion 1.0.0 hochladen möchten, führen Sie Folgendes aus:

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

Pushen des Docker-Images an eine Registrierung

Um benutzerdefinierte Images verwenden zu können, müssen Sie eine öffentlich zugängliche Imageregistrierung mit aktiviertem anonymem Pull für Images einrichten. Dadurch kann Azure Deployment Environments auf Ihr benutzerdefiniertes Image zugreifen, um es in Ihrem Container auszuführen.

Azure Container Registry ist ein Azure-Angebot zum Speichern von Containerimages und zugehöriger Artefakte.

Um eine Registrierung zu erstellen, befolgen Sie einen der Schnellstarts, für die Azure-Befehlszeilenschnittstelle, das Azure-Portal, PowerShell-Befehle usw.

Führen Sie die folgenden Befehle in der Azure-Befehlszeilenschnittstelle aus, um Ihre Registrierung so einzurichten, dass das anonyme Pullen von Images aktiviert ist:

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

Wenn Sie bereit sind, Ihr Image an Ihre Registrierung zu pushen, führen Sie den folgenden Befehl aus:

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

Verbinden des Images mit Ihrer Umgebungsdefinition

Wenn Sie Umgebungsdefinitionen erstellen, die Ihr benutzerdefiniertes Image in Ihrer Bereitstellung verwenden sollen, bearbeiten Sie die runner-Eigenschaft in der Manifestdatei („environment.yaml“ oder „manifest.yaml“).

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

Zugreifen auf Vorgangsprotokolle und Fehlerdetails

ADE speichert Fehlerdetails für eine fehlgeschlagene Bereitstellung in der Datei $ADE_ERROR_LOG im Container.

So beheben Sie Probleme mit einer fehlerhaften Bereitstellung

  1. Melden Sie sich beim Entwicklerportal an.

  2. Identifizieren Sie die Umgebung, die nicht bereitgestellt werden konnte, und wählen Sie Details anzeigen aus.

    Screenshot mit Details zu Bereitstellungsfehlern, insbesondere einem ungültigen Namen für ein Speicherkonto

  3. Überprüfen Sie die Fehlerdetails im Abschnitt Fehlerdetails.

    Screenshot der fehlerhaften Bereitstellung einer Umgebung mit der Schaltfläche „Details anzeigen“

Darüber hinaus können Sie den folgenden Befehl in der Azure-Befehlszeilenschnittstelle verwenden, um Fehlerdetails zu einer Umgebung anzuzeigen:

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

Um die Vorgangsprotokolle für eine Umgebungsbereitstellung oder -löschung anzuzeigen, rufen Sie mithilfe der Azure-Befehlszeilenschnittstelle den neuesten Vorgang für Ihre Umgebung ab und zeigen dann die Protokolle für diese Vorgangs-ID an.

# 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}

Zugehöriger Inhalt