Freigeben über

Konfigurieren von ADE zum Ausführen von Bereitstellungen mit Pulumi

  • Artikel

In diesem Artikel erfahren Sie, wie Sie Pulumi für Bereitstellungen in Azure Deployment Environments (ADE) verwenden. Sie erfahren, wie Sie ein Standardimage verwenden, das von Pulumi bereitgestellt wird, oder wie Sie ein benutzerdefiniertes Image für die Bereitstellung einer Infrastruktur mithilfe des Pulumi Infrastructure-as-Code (IaC)-Frameworks konfigurieren.

ADE unterstützt ein Erweiterbarkeitsmodell, mit dem Sie benutzerdefinierte Images erstellen können, die Sie in Ihren Umgebungsdefinitionen verwenden können. Um dieses Erweiterbarkeitsmodell zu nutzen, können Sie eigene benutzerdefinierte Images erstellen und in einer öffentlichen Containerregistrierung speichern. Anschließend können Sie in Ihren Umgebungsdefinitionen auf diese Images verweisen, um Ihre Umgebungen bereitzustellen.

Eine Umgebungsdefinition umfasst mindestens zwei Dateien: eine Pulumi-Projektdatei, Pulumi.yaml und eine Manifestdatei namens environment.yaml. Sie kann auch ein Benutzerprogramm enthalten, das in Ihrer bevorzugten Programmiersprache geschrieben wurde: C#, TypeScript, Python usw. ADE verwendet Container zum Bereitstellen von Umgebungsdefinitionen.

Voraussetzungen

Verwenden eines standardmäßigen Docker-Images, das von Pulumi bereitgestellt wird

Das Pulumi-Team bietet ein vorgefertigtes Bild für die ersten Schritte, das Sie im Ordner Runner-Image sehen können. Dieses Image ist im Docker Hub von Pulumi öffentlich verfügbar als pulumi/azure-deployment-environments, sodass Sie es direkt aus Ihren ADE-Umgebungsdefinitionen verwenden können.

Hier ist eine Beispieldatei environment.yaml, die das vorgefertigte Bild verwendet:

name: SampleDefinition
version: 1.0.0
summary: First Pulumi-Enabled Environment
description: Deploys a Storage Account with Pulumi
runner: pulumi/azure-deployment-environments:0.1.0
templatePath: Pulumi.yaml

Im Ordner Umgebungen finden Sie einige Beispielumgebungsdefinitionen.

Erstellen und Verwenden eines benutzerdefinierten Docker-Images

Sie können benutzerdefinierte Images basierend auf den ADE-Beispielimages erstellen, indem Sie das ADE CLI-Tool verwenden. Benutzen Sie die ADE CLI, 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.

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.

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.

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.

Installieren von Pulumi in einer Dockerfile-Datei

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

Hier ist ein Beispiel für diesen Prozess, der die neueste Version der Pulumi CLI installiert:

RUN apk add curl
RUN curl -fsSL https://get.pulumi.com | sh
ENV PATH="${PATH}:/root/.pulumi/bin"

Je nachdem, welche Programmiersprache Sie für Pulumi-Programme verwenden möchten, müssen Sie möglicherweise eine oder mehrere entsprechende Laufzeiten installieren. Die Python-Laufzeit ist bereits im Basisimage verfügbar.

Hier ist ein Beispiel für die Installation von Node.js und TypeScript:

# install node.js, npm, and typescript
RUN apk add nodejs npm
RUN npm install typescript -g

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/Scripts.

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 Pulumi CLI

Es gibt vier Schritte zur Bereitstellung der Infrastruktur über Pulumi:

  1. pulumi login – Herstellen einer Verbindung mit dem Zustandsspeicher, entweder im lokalen Dateisystem oder in Pulumi Cloud
  2. pulumi stack select – Erstellen oder Auswählen des Stapels, der für die jeweilige Umgebung verwendet werden soll
  3. pulumi config set – Übergeben von Bereitstellungsparametern als Pulumi-Konfigurationswerte
  4. pulumi up – Anwendung der Bereitstellung, um eine neue Infrastruktur in Azure zu erstellen oder eine vorhandene zu aktualisieren

Während des Einstiegspunkts des Kernimages werden alle vorhandenen lokalen Zustandsdateien in den Container und das unter der Umgebungsvariable $ADE_STORAGE gespeicherte Verzeichnis gepullt. Um auf die vorhandene Statusdatei zuzugreifen, führen Sie die folgenden Befehle aus:

mkdir -p $ADE_STORAGE
export PULUMI_CONFIG_PASSPHRASE=
pulumi login file://$ADE_STORAGE

Wenn Sie sich stattdessen bei Pulumi Cloud anmelden möchten, legen Sie Ihr Pulumi-Zugriffstoken als Umgebungsvariable fest, und führen Sie die folgenden Befehle aus:

export PULUMI_ACCESS_TOKEN=YOUR_PULUMI_ACCESS_TOKEN
pulumi login

Alle Parameter, die für die aktuelle Umgebung festgelegt wurden, werden in der Variable $ADE_OPERATION_PARAMETERS gespeichert. Darüber hinaus werden der ausgewählte Azure-Region- und Ressourcengruppenname in ADE_ENVIRONMENT_LOCATION bzw ADE_RESOURCE_GROUP_NAME übergeben. Führen Sie zum Festlegen der Pulumi-Stapelkonfiguration die folgenden Befehle aus:

# Create or select the stack for the current environment
pulumi stack select $ADE_ENVIRONMENT_NAME --create

# Store configuration values in durable storage
export PULUMI_CONFIG_FILE=$ADE_STORAGE/Pulumi.$ADE_ENVIRONMENT_NAME.yaml

# Set the Pulumi stack config
pulumi config set azure-native:location $ADE_ENVIRONMENT_LOCATION --config-file $PULUMI_CONFIG_FILE
pulumi config set resource-group-name $ADE_RESOURCE_GROUP_NAME --config-file $PULUMI_CONFIG_FILE
echo "$ADE_OPERATION_PARAMETERS" | jq -r 'to_entries|.[]|[.key, .value] | @tsv' |
  while IFS=$'\t' read -r key value; do
    pulumi config set $key $value --config-file $PULUMI_CONFIG_FILE
  done

Darüber hinaus muss Ihr Skript, um die ADE-Berechtigungen zum Bereitstellen der Infrastruktur in Ihrem Abonnement zu nutzen, die ADI verwaltete Dienstidentität (Managed Service Identity, MSI) beim Bereitstellen der Infrastruktur mithilfe des Pulumi Azure Native oder Azure Classic-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

Jetzt können Sie den pulumi up Befehl ausführen, um die Bereitstellung auszuführen:

pulumi up --refresh --yes --config-file $PULUMI_CONFIG_FILE

Während des Löschskripts können Sie stattdessen den destroy Befehl ausführen, wie im folgenden Beispiel gezeigt:

pulumi destroy --refresh --yes --config-file $PULUMI_CONFIG_FILE

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

stackout=$(pulumi stack output --json | jq -r 'to_entries|.[]|{(.key): {type: "string", value: (.value)}}')
echo "{\"outputs\": ${stackout:-{\}}}" > $ADE_OUTPUTS

Erstellen des Image

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.

Erstellen einer Azure Container Registry und Veröffentlichen Ihres Images mit Pulumi

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

Sie können Pulumi verwenden, um eine Azure Container Registry zu erstellen und Ihr Image darin zu veröffentlichen. Verweisen Sie auf das Bereitstellungs-/benutzerdefinierte Image für ein eigenständiges Pulumi-Projekt, das alle erforderlichen Ressourcen in Ihrem Azure-Konto erstellt.

Erstellen Sie eine Azure Container Registry, und veröffentlichen Sie Ihr Image manuell über CLI

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 fehlerhafte Bereitstellungen in der Datei $ADE_ERROR_LOG.

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