Konfigurieren eines Containerimages zum Ausführen von Bereitstellungen mit ARM und Bicep
In diesem Artikel erfahren Sie, wie Sie benutzerdefinierte Azure Resource Manager (ARM) und Bicep-Containerimages erstellen, um Ihre Umgebungsdefinitionen in Azure Deployment Environments (ADE) bereitzustellen.
Eine Umgebungsdefinition umfasst mindestens zwei Dateien: eine Vorlagendatei, z. B. azuredeploy.json oder main.bicep, und eine Manifestdatei namens environment.yaml. ADE verwenden Container zum Bereitstellen von Umgebungsdefinitionen und unterstützt systemeigene ARM- und Bicep-IaC-Frameworks.
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.
Das ADE-Team bietet eine Auswahl an Images für den Einstieg, einschließlich eines Kernimages und eines ARM- (Azure Resource Manager)/Bicep-Images. Sie können auf diese Beispielimages im Ordner Runner-Images zugreifen.
Voraussetzungen
- Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
- Azure Deployment Environments, die in Ihrem Azure-Abonnement eingerichtet sind.
- Befolgen Sie zum Einrichten von ADE die Schnellstartanleitung: Konfigurieren von Azure-Bereitstellungsumgebungen.
Verwenden von Containerimages mit ADE
Sie können einen der folgenden Ansätze verwenden, um Containerimages mit ADE zu verwenden:
- Standardcontainerimage verwenden: Verwenden Sie für einfache Szenarien das standardmäßige Bicep-Containerimage, das von ADE bereitgestellt wird.
- Ein benutzerdefiniertes Containerimage verwenden: Erstellen Sie für komplexere Szenarien ein benutzerdefiniertes Containerimage, das Ihren spezifischen Anforderungen entspricht.
Unabhängig davon, welchen Ansatz Sie auswählen, müssen Sie das Containerimage in Ihrer Umgebungsdefinition angeben, um Ihre Azure-Ressourcen bereitzustellen.
Verwenden des standardmäßigen Bicep-Containerimages
ADE unterstützt Bicep nativ, sodass Sie eine Umgebungsdefinition konfigurieren können, die Azure-Ressourcen für eine Bereitstellungsumgebung bereitstellt, indem Sie dem Katalog die Vorlagendateien (azuredeploy.json und environment.yaml) hinzufügen. ADE verwendet dann das standardmäßige Bicep-Containerimage, um die Bereitstellungsumgebung zu erstellen.
In der Datei „environment.yaml“ gibt die Runner-Eigenschaft die Position des Containerimages an, das Sie verwenden möchten. Um das Beispielimage zu verwenden, das in der Microsoft-Artefaktregistrierung veröffentlicht wurde, verwenden Sie die entsprechenden Bezeichner, wie in der folgenden Tabelle aufgeführt.
Das folgende Beispiel zeigt einen Runner, der auf das Beispiel-Bicep-Containerimage verweist:
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
Sie können das standardmäßige Bicep-Containerimage im ADE-Beispiel-Repository unter dem Ordner Runner-Images für das ARM-Bicep-Image anzeigen.
Weitere Informationen zum Erstellen von Umgebungsdefinitionen, die die ADE-Containerimages verwenden, um Ihre Azure-Ressourcen bereitzustellen, finden Sie unter Hinzufügen und Konfigurieren einer Umgebungsdefinition.
Erstellen eines benutzerdefinierten Bicep-Containerimages
Durch das Erstellen eines benutzerdefinierten Containerimages können Sie Ihre Bereitstellungen an Ihre Anforderungen anpassen. Sie können benutzerdefinierte Images basierend auf den ADE-Standardcontainerimages erstellen.
Nachdem Sie die Imageanpassung abgeschlossen haben, müssen Sie das Image erstellen und in die Containerregistrierung übertragen.
Erstellen und Anpassen eines Containerimages 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:
- Basieren Sie Ihr Image auf einem in ADE erstellten Beispielimage oder einem Image Ihrer Wahl, indem Sie die FROM-Anweisung verwenden.
- Installieren Sie mithilfe der RUN-Anweisung alle erforderlichen Pakete für Ihr Image.
- 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 Bicep in einem Dockerfile
Sie können das Bicep-Paket mit der Azure-Befehlszeilenschnittstelle mithilfe der RUN-Anweisung installieren, wie im folgenden Beispiel gezeigt:
RUN az bicep install
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 Bereitstellen von ARM- oder Bicep-Vorlagen
Um sicherzustellen, dass Sie eine ARM- oder Bicep-Infrastruktur über ADE erfolgreich bereitstellen können, ist Folgendes erforderlich:
- Konvertieren von ADE-Parametern in von ARM akzeptierte Parameter
- Auflösen verknüpfter Vorlagen, wenn diese in der Bereitstellung verwendet werden
- Verwenden einer verwalteten Identität mit erhöhten Rechten zum Ausführen der Bereitstellung
Während des Einstiegspunkts des Kernimages werden alle Parameter, die für die aktuelle Umgebung festgelegt wurden, in der Variable $ADE_OPERATION_PARAMETERS gespeichert. Um sie in von ARM akzeptierte Parameter zu konvertieren, können Sie den folgenden Befehl mit JQ ausführen:
# 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) }' )
Um alle verknüpften Vorlagen in einer ARM-JSON-Vorlage aufzulösen, können Sie als Nächstes die Hauptvorlagendatei dekompilieren. Damit werden alle lokalen Infrastrukturdateien aufgelöst, die in vielen Bicep-Modulen verwendet werden. Erstellen Sie diese Module dann erneut in einer einzelnen ARM-Vorlage mit den verknüpften Vorlagen, die in die ARM-Hauptvorlage als geschachtelte Vorlagen eingebettet sind. Dieser Schritt ist nur während des Bereitstellungsvorgangs erforderlich. Die Hauptvorlagendatei kann durch Festlegen von $ADE_TEMPLATE_FILE während des Einstiegspunkts des Kernimages angegeben werden. Sie sollten diese Variable mit der erneut kompilierten Vorlagendatei zurücksetzen. Siehe folgendes Beispiel:
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
Um die Berechtigungen bereitzustellen, die für eine Bereitstellung benötigt werden, um die Bereitstellung und Löschung von Ressourcen innerhalb des Abonnements auszuführen, verwenden Sie eine verwaltete Identität mit erhöhten Rechten, die dem Typ der ADE-Projektumgebung zugeordnet ist. Wenn für den Abschluss Ihrer Bereitstellung spezielle Berechtigungen erforderlich sind (z. B. bestimmte Rollen), weisen Sie diese Rollen der Identität des Projektumgebungstyps zu. Manchmal ist die verwaltete Identität nicht sofort beim Einstieg in den Container verfügbar. Sie können den Vorgang dann wiederholen, bis die Anmeldung erfolgreich ist.
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
Um mit der Bereitstellung der ARM- oder Bicep-Vorlagen zu beginnen, führen Sie den Befehl az deployment group create aus. Wenn Sie diesen Befehl innerhalb des Containers ausführen, wählen Sie einen Bereitstellungsnamen aus, der keine früheren Bereitstellungen überschreibt. Verwenden Sie außerdem die Flags --no-prompt true und --only-show-errors, um sicherzustellen, dass die Bereitstellung bei Warnungen oder beim Warten auf Benutzereingaben nicht zu Fehlern führt, wie im folgenden Beispiel gezeigt:
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
Führen Sie zum Löschen einer Umgebung eine Bereitstellung im Modus „Complete“ aus, und stellen Sie eine leere ARM-Vorlage bereit, die alle Ressourcen innerhalb der angegebenen ADE-Ressourcengruppe entfernt, wie im folgenden Beispiel gezeigt:
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"
Sie können den Bereitstellungsstatus und die Details überprüfen, indem Sie die folgenden Befehle ausführen. ADE verwendet einige spezielle Funktionen, um mehr Kontext basierend auf den Bereitstellungsdetails zu lesen und bereitzustellen, die Sie auch im Ordner Runner-Images finden. Eine einfache Implementierung könnte wie folgt aussehen:
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
Um zum Schluss die Ausgaben Ihrer Bereitstellung anzuzeigen und an ADE zu übergeben, damit sie über die Azure-Befehlszeilenschnittstelle zugänglich sind, können Sie die folgenden Befehle ausführen:
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
Erstellen des barrierefreien Benutzerdefinierten Bilds für ADE
Sie müssen Ihr Docker-Image erstellen und an Ihre Containerregistrierung senden, 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}"
Weitere Informationen zum Erstellen von Umgebungsdefinitionen, die die ADE-Containerimages zum Bereitstellen Ihrer Azure-Ressourcen verwenden, finden Sie unter Hinzufügen und Konfigurieren einer Umgebungsdefinition.
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
Melden Sie sich beim Entwicklerportal an.
Identifizieren Sie die Umgebung, die nicht bereitgestellt werden konnte, und wählen Sie Details anzeigen aus.
Überprüfen Sie die Fehlerdetails im Abschnitt Fehlerdetails.
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
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für