Configurer une image conteneur pour exécuter des déploiements avec ARM et Bicep

Dans cet article, vous apprenez à créer des images conteneur personnalisées Azure Resource Manager (ARM) et Bicep pour déployer vos définitions d’environnement dans les Environnements de déploiement Azure (ADE).

Une définition d’environnement comprend au moins deux fichiers : un fichier de modèle, comme azuredeploy.json ou main.bicep, et un fichier manifeste nommé environment.yaml. ADE utilise des conteneurs pour déployer des définitions d’environnement et prend en charge en mode natif les frameworks IaC ARM et Bicep.

Le modèle d’extensibilité ADE vous permet de créer des images conteneur personnalisées pour les utiliser avec vos définitions d’environnement. En utilisant le modèle d’extensibilité, vous pouvez créer vos propres images conteneur personnalisées et les stocker dans un registre de conteneurs comme DockerHub. Vous pouvez ensuite référencer ces images dans vos définitions d’environnement pour déployer vos environnements.

L’équipe ADE fournit une sélection d’images pour vous aider à démarrer, notamment une image de base et une image Azure Resource Manager (ARM)/Bicep. Vous pouvez accéder à ces exemples d’image dans le dossier Runner-Images.

L’interface CLI ADE est un outil qui vous permet de créer des images personnalisées à partir d’images de base ADE. Vous pouvez utiliser l’interface CLI ADE pour personnaliser vos déploiements et vos suppressions en fonction de votre workflow. L’interface CLI ADE est préinstallée sur les exemples d’image. Pour en savoir plus sur l’interface CLI ADE, consultez les Informations de référence sur les images Runner personnalisées de l’interface CLI.

Prérequis

• Compte Azure avec un abonnement actif. Créez un compte gratuitement.
• Environnements de déploiement Azure configurés dans votre abonnement Azure.
  • Pour configurer ADE, suivez le Guide de démarrage rapide : Configurer des environnements de déploiement Azure.

Créer et générer une image Docker

Dans cet exemple, vous apprenez à créer une image Docker pour utiliser des déploiements ADE et accéder à l’interface CLI ADE, en basant votre image sur l’une des images créées par ADE.

Pour générer une image configurée pour ADE, suivez ces étapes :

1. Basez votre image sur un exemple d’image créé par ADE ou sur l’image de votre choix en utilisant l’instruction FROM.
2. Installez les packages nécessaires pour votre image avec l’instruction RUN.
3. Créez un dossier scripts au même niveau que votre fichier Dockerfile, stockez-y vos fichiers deploy.sh et delete.sh, et vérifiez que ces scripts sont découvrables et exécutables dans le conteneur que vous avez créé. Cette étape est nécessaire pour que votre déploiement fonctionne avec l’image de base ADE.
4. Générez et poussez votre image dans votre registre de conteneurs, et vérifiez qu’ADE peut y accéder.
5. Référencez votre image dans la propriété runner de votre définition d’environnement.

Sélectionner un exemple d’image conteneur avec l’instruction FROM

Ajoutez une instruction FROM dans un fichier DockerFile créé pour votre nouvelle image qui pointe vers un exemple d’image hébergé dans le Registre des artefacts Microsoft.

Voici un exemple d’instruction FROM, référençant l’exemple d’image de base :

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

Cette instruction extrait la dernière image de base publiée et en fait la base de votre image personnalisée.

Installer Bicep dans un Dockerfile

Vous pouvez installer le package Bicep avec Azure CLI en utilisant l’instruction RUN, comme illustré dans l’exemple suivant :

RUN az bicep install

Les exemples d’image ADE sont basés sur l’image Azure CLI, et ont les package de l’interface CLI ADE et JQ installés. Vous pouvez en savoir plus sur Azure CLI et le package JQ.

Pour installer les autres packages dont vous avez besoin dans votre image, utilisez l’instruction RUN.

Exécuter des scripts d’interpréteur de commandes d’opération

Dans les exemples d’image, les opérations sont déterminées et exécutées en fonction du nom de l’opération. Actuellement, les deux noms d’opération pris en charge sont deploy et delete.

Pour configurer votre image personnalisée afin qu’elle utilise cette structure, spécifiez un dossier au niveau de votre fichier Dockerfile nommé scripts, puis spécifiez deux fichiers, deploy.shet delete.sh. Le script d’interpréteur de commandes deploy s’exécute quand votre environnement est créé ou redéployé, et le script d’interpréteur de commandes delete s’exécute quand votre environnement est supprimé. Vous pouvez voir des exemples de scripts d’interpréteur de commandes dans le dépôt sous le dossier Runner-Images pour l’image ARM-BICEP.

Pour vérifier que ces scripts d’interpréteur de commandes sont exécutables, ajoutez les lignes suivantes à votre fichier Dockerfile :

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

Créer des scripts d’interpréteur de commandes d’opération pour déployer des modèles ARM ou Bicep

Pour vous assurer que vous pouvez correctement déployer l’infrastructure ARM ou Bicep via ADE, vous devez :

• Convertir les paramètres ADE en paramètres acceptables pour ARM
• Résoudre les modèles liés s’ils sont utilisés dans le déploiement
• Utiliser l’identité managée privilégiée pour effectuer le déploiement

Durant la phase entrypoint de l’image core, tous les paramètres définis pour l’environnement actuel sont stockés sous la variable $ADE_OPERATION_PARAMETERS. Pour les convertir en paramètres acceptables pour ARM, vous pouvez exécuter la commande suivante avec 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) }' )

Ensuite, pour résoudre tous les modèles liés utilisés dans un modèle ARM basé sur JSON, vous pouvez décompiler le fichier de modèle principal, qui résout tous les fichiers d’infrastructure locaux utilisés dans de nombreux modules Bicep. Ensuite, régénérez ces modules dans un modèle ARM unique en incorporant les modèles liés dans le modèle ARM principal en tant que modèles imbriqués. Cette étape est nécessaire uniquement pendant l’opération de déploiement. Le fichier de modèle principal peut être spécifié avec le $ADE_TEMPLATE_FILE défini durant la phase entrypoint de l’image core. Vous devez réinitialiser cette variable avec le fichier de modèle recompilé. Voir l’exemple suivant :

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

Pour fournir à un déploiement les autorisations nécessaires pour exécuter le déploiement et la suppression des ressources au sein de l’abonnement, utilisez l’identité managée privilégiée associée au type d’environnement de projet ADE. Si votre déploiement nécessite des autorisations spéciales, notamment des rôles particuliers, attribuez ces rôles à l’identité du type d’environnement de projet. Parfois, l’identité managée n’est pas immédiatement disponible quand vous entrez le conteneur. Vous pouvez réessayer jusqu’à ce que la connexion réussisse.

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

Pour commencer le déploiement des modèles ARM ou Bicep, exécutez la commande az deployment group create. Lors de l’exécution de cette commande à l’intérieur du conteneur, choisissez un nom de déploiement qui ne remplace pas les déploiements passés, et utilisez les indicateurs --no-prompt true et --only-show-errors pour vous assurer que le déploiement n’échoue pas en cas d’avertissement ou ne se bloque pas en attendant une entrée utilisateur, comme le montre l’exemple suivant :

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

Pour supprimer un environnement, effectuez un déploiement en mode Complete et fournissez un modèle ARM vide qui supprime toutes les ressources dans le groupe de ressources ADE spécifié, comme le montre l’exemple suivant :

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"

Vous pouvez consulter l’état et les détails de l’approvisionnement en exécutant les commandes ci-dessous. ADE utilise des fonctions spéciales pour lire et fournir plus de contexte en fonction des détails de provisionnement, disponibles dans le dossier Runner-Images. Voici un exemple d’implémentation simple :

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

Enfin, pour afficher les sorties de votre déploiement et les passer à ADE afin de les rendre accessibles via Azure CLI, vous pouvez exécuter les commandes suivantes :

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

Créer l’image

Avant de générer l’image à pousser dans votre registre, vérifiez que le moteur Docker est installé sur votre ordinateur. Ensuite, accédez au répertoire de votre fichier Dockerfile, puis exécutez la commande suivante :

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

Par exemple, si vous voulez enregistrer votre image sous un dépôt au sein de votre registre nommé customImage et le charger avec la version d’étiquette 1.0.0, vous exécutez :

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

Pousser l’image Docker dans un registre

Pour utiliser des images personnalisées, vous devez configurer un registre d’images accessible publiquement avec l’extraction d’image anonyme activée. De cette façon, le service Environnements de déploiement Azure peut accéder à votre image personnalisée pour l’exécuter dans notre conteneur.

Azure Container Registry est une offre Azure qui stocke des images conteneur et des artefacts similaires.

Pour créer un registre, ce que vous pouvez faire avec Azure CLI, le portail Azure, des commandes PowerShell, etc., suivez un des guides de démarrage rapide.

Pour configurer votre registre en activant l’extraction d’image anonyme, exécutez les commandes suivantes dans 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

Quand vous êtes prêt à pousser votre image dans votre registre, exécutez la commande suivante :

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

Connecter l’image à votre définition d’environnement

Quand vous créez les définitions d’environnement pour utiliser votre image personnalisée dans leur déploiement, modifiez la propriété runner dans le fichier manifeste (environment.yaml ou manifest.yaml).

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

Générer une image conteneur avec un script

Microsoft fournit un script de démarrage rapide pour vous aider à commencer. Le script génère votre image et la pousse dans une instance Azure Container Registry (ACR) spécifiée sous le dépôt ade et l’étiquette latest.

Pour utiliser le script, vous devez :

1. Configurer un fichier Dockerfile et un dossier scripts pour prendre en charge le modèle d’extensibilité ADE.
2. Fournir un nom de registre et un répertoire pour votre image personnalisée.
3. Avoir Azure CLI et Docker Desktop installés et ajoutés dans vos variables PATH.
4. Avoir l’autorisation de pousser dans le registre spécifié.

Vous pouvez exécuter le script ici.

Vous pouvez appeler le script avec la commande suivante dans PowerShell :

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

Par ailleurs, si vous voulez pousser l’image vers un dépôt et un nom d’étiquette spécifiques, vous pouvez exécuter :

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

Accéder aux journaux d’opérations et aux détails d’erreur

ADE stocke les détails d’erreur d’un déploiement ayant échoué dans le fichier $ADE_ERROR_LOG dans le conteneur.

Pour résoudre les problèmes d’échec de déploiement :

1. Connectez-vous au portail des développeurs.

2. Identifiez l’environnement qui n’a pas pu être déployé, puis sélectionnez Voir les détails.

   

3. Passez en revue les détails d’erreur dans la section Détails d’erreur.

   

Par ailleurs, vous pouvez utiliser Azure CLI pour voir les détails d’erreur d’un environnement avec la commande suivante :

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

Pour voir les journaux d’opérations d’un déploiement ou d’une suppression d’environnement, utilisez Azure CLI pour récupérer la dernière opération de votre environnement, puis consultez cet ID d’opération dans les journaux.

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

Contenu connexe

• Informations de référence sur les images Runner personnalisées de l’interface CLI ADE