Configurare l’immagine del contenitore per l’esecuzione di distribuzioni

Creare un'immagine del contenitore personalizzata usando uno script

La creazione di un'immagine del contenitore personalizzata consente di personalizzare le distribuzioni in base alle esigenze. È possibile creare immagini personalizzate basate sulle immagini standard DIE.

Dopo aver completato la personalizzazione dell'immagine, è possibile compilare l'immagine ed eseguirne il push nel registro contenitori usando uno script fornito da Microsoft per automatizzare il processo.

Le immagini personalizzate vengono compilate usando le immagini standard DIE come base con l'interfaccia della riga di comando di ADE, preinstallate nelle immagini standard. Per altri dettagli sull'interfaccia della riga di comando di ADE, vedere il Riferimento immagine strumento di esecuzione personalizzato interfaccia della riga di comando.

Questo esempio illustra come creare un'immagine Docker per usare le distribuzioni di Ambienti di distribuzione di Azure e accedere all'interfaccia della riga di comando di Ambienti di distribuzione di Azure, basando l'immagine su una delle immagini create da Ambienti di distribuzione di Azure.

Per creare un'immagine configurata per Ambienti di distribuzione di Azure, seguire questa procedura:

1. Creare un'immagine personalizzata basata su un'immagine standard.
2. Installare i pacchetti desiderati.
3. Configurare gli script della shell delle operazioni.
4. Creare script della shell delle operazioni per distribuire modelli di Azure Resource Manager o Bicep.

1. Creare un'immagine personalizzata basata su un'immagine standard

Creare un DockerFile che includa un'istruzione FROM che punta a un'immagine standard ospitata in Registro artefatti Microsoft.

Ecco un'istruzione FROM di esempio che fa riferimento all'immagine principale standard:

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

Questa istruzione esegue il pull dell’immagine principale più recente pubblicata, rendendola come base per l'immagine personalizzata.

2. Installare i pacchetti necessari

In questo passaggio si installano tutti i pacchetti necessari nell'immagine, incluso Bicep. È possibile installare il pacchetto Bicep con l'interfaccia della riga di comando di Azure usando l'istruzione RUN, come illustrato nell'esempio seguente:

RUN az bicep install

Le immagini standard DIE si basano sull'immagine dell'interfaccia della riga di comando di Azure e includono i pacchetti dell'interfaccia della riga di comando di Ade e JQ preinstallati. Altre informazioni su'interfaccia della riga di comando di Azure e sul pacchetto JQ.

Per installare eventuali altri pacchetti necessari all'interno dell'immagine, usare l'istruzione RUN.

3. Configurare gli script della shell delle operazioni

All'interno delle immagini standard, le operazioni vengono determinate ed eseguite in base al nome dell'operazione. Attualmente, i due nomi operazione supportati sono distribuire ed eliminare.

Per configurare l'immagine personalizzata e usare tale struttura, specificare una cartella a livello degli script denominati Dockerfile, e quindi specificare due file: deploy.sh e delete.sh. Lo script della shell di distribuzione viene eseguito quando l'ambiente viene creato o ridistribuito, e lo script della shell di eliminazione viene eseguito quando l'ambiente viene eliminato. È possibile visualizzare esempi di script della shell nel repository nella cartella Runner-Images per l'immagine ARM-Bicep.

Per accertare che gli script della shell siano eseguibili, aggiungere al Dockerfile le righe seguenti:

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

4. Creare script della shell delle operazioni per distribuire i modelli di Azure Resource Manager o Bicep

Per assicurarsi di poter distribuire correttamente l'infrastruttura ARM o Bicep tramite Ambienti di distribuzione di Azure, è necessario:

1. Convertire i parametri di Ambienti di distribuzione di Azure in parametri accettabili per ARM
2. Risolvere i modelli collegati se vengono usati nella distribuzione
3. Usare l'identità gestita con privilegi per eseguire la distribuzione

Nel punto di ingresso dell'immagine di base, i parametri impostati per l'ambiente corrente vengono archiviati nella variabile $ADE_OPERATION_PARAMETERS. Per convertirli in parametri accettabili per ARM, è possibile eseguire il comando seguente usando 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) }' )

Successivamente, per risolvere tutti i modelli collegati usati all'interno di un modello di ARM basato su JSON, è possibile decompilare il file modello principale, operazione che risolve tutti i file di infrastruttura locale usati in molti moduli Bicep. Ricompilare quindi questi moduli in un singolo modello di ARM con i modelli collegati incorporati nel modello di ARM di base come modelli annidati. Questo passaggio è necessario solo durante l'operazione di distribuzione. È possibile specificare il file modello di base usando $ADE_TEMPLATE_FILE impostato durante il punto di ingresso dell'immagine di base ed è necessario reimpostare questa variabile con il file modello ricompilato. Vedere l'esempio seguente:

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

Per fornire le autorizzazioni necessarie per la distribuzione e l'eliminazione delle risorse all'interno della sottoscrizione, usare l'identità gestita con privilegi associata al tipo di ambiente del progetto Ambienti di distribuzione di Azure. Se per completare la distribuzione sono necessarie autorizzazioni speciali, ad esempio ruoli specifici, assegnare tali ruoli all'identità del tipo di ambiente del progetto. In alcuni casi, l'identità gestita non è immediatamente disponibile quando si immette il contenitore; è possibile riprovare fino a quando l'accesso non riesce.

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

Per iniziare la distribuzione dei modelli ARM o Bicep, eseguire il comando az deployment group create. Quando si esegue questo comando all'interno del contenitore, scegliere un nome di distribuzione che non comporti la sostituzione delle distribuzioni precedenti e usare i flag --no-prompt true e --only-show-errors per assicurarsi che la distribuzione non fallisca in caso di avvisi e che non si blocchi in attesa dell'input dell'utente, come illustrato nell'esempio seguente:

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

Per eliminare un ambiente, eseguire una distribuzione in modalità completa e fornire un modello di ARM vuoto, che rimuove tutte le risorse all'interno del gruppo di risorse di Ambienti di distribuzione di Azure specificato, come illustrato nell'esempio seguente:

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"

È possibile controllare lo stato e i dettagli del provisioning eseguendo i comandi seguenti. Ambienti di distribuzione di Azure usa alcune funzioni speciali per leggere e fornire più contesto in base ai dettagli del provisioning, disponibili nella cartella Runner-Images. Un'implementazione semplice può essere la seguente:

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

Infine, per visualizzare gli output della distribuzione e passarli ad Ambienti di distribuzione di Azure per renderli accessibili tramite l'interfaccia della riga di comando di Azure, è possibile eseguire i comandi seguenti:

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

Compilare un'immagine del contenitore con uno script

Anziché creare l'immagine personalizzata ed eseguirne il push in un registro contenitori manualmente, è possibile usare uno script per crearla ed eseguirne il push in un registro contenitori specificato.

Microsoft fornisce uno script di avvio rapido che consente di creare l'immagine personalizzata ed eseguirne il push in un registro. Lo script compila l'immagine ed esegue il push dell'immagine in un Registro Azure Container nel repository ade e con il tag latest.

Per usare lo script, è necessario:

1. Creare un Dockerfile e una cartella per gli script per supportare il modello di estendibilità di Ambienti di distribuzione di Azure.
2. Specificare una directory e un nome del registro per l'immagine personalizzata.
3. Installare l'interfaccia della riga di comando di Azure e Docker Desktop nelle variabili PATH.
4. Assicurarsi che Docker Desktop sia in esecuzione.
5. Disporre delle autorizzazioni per eseguire il push nel registro specificato.

È possibile visualizzare lo script qui.

È possibile chiamare lo script usando il comando seguente in PowerShell:

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

Inoltre, se si vuole eseguire il push in un repository e un nome di tag specifici, è possibile eseguire:

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

Creare manualmente un'immagine del contenitore personalizzata

La creazione di un'immagine del contenitore personalizzata consente di personalizzare le distribuzioni in base alle esigenze. È possibile creare immagini personalizzate basate sulle immagini standard DIE.

Dopo aver completato la personalizzazione dell'immagine, è possibile compilare l'immagine ed eseguirne il push nel registro contenitori manualmente.

Le immagini personalizzate vengono compilate usando le immagini standard DIE come base con l'interfaccia della riga di comando di ADE, preinstallate nelle immagini standard. Per altri dettagli sull'interfaccia della riga di comando di ADE, vedere il Riferimento immagine strumento di esecuzione personalizzato interfaccia della riga di comando.

Questo esempio illustra come creare un'immagine Docker per usare le distribuzioni di Ambienti di distribuzione di Azure e accedere all'interfaccia della riga di comando di Ambienti di distribuzione di Azure, basando l'immagine su una delle immagini create da Ambienti di distribuzione di Azure.

Per creare un'immagine configurata per Ambienti di distribuzione di Azure, seguire questa procedura:

1. Creare un'immagine personalizzata basata su un'immagine standard.
2. Installare i pacchetti desiderati.
3. Configurare gli script della shell delle operazioni.
4. Creare script della shell delle operazioni per distribuire modelli di Azure Resource Manager o Bicep.

1. Creare un'immagine personalizzata basata su un'immagine standard

Creare un DockerFile che includa un'istruzione FROM che punta a un'immagine standard ospitata in Registro artefatti Microsoft.

Ecco un'istruzione FROM di esempio che fa riferimento all'immagine principale standard:

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

Questa istruzione esegue il pull dell’immagine principale più recente pubblicata, rendendola come base per l'immagine personalizzata.

2. Installare i pacchetti necessari

In questo passaggio si installano tutti i pacchetti necessari nell'immagine, incluso Bicep. È possibile installare il pacchetto Bicep con l'interfaccia della riga di comando di Azure usando l'istruzione RUN, come illustrato nell'esempio seguente:

RUN az bicep install

Le immagini standard DIE si basano sull'immagine dell'interfaccia della riga di comando di Azure e includono i pacchetti dell'interfaccia della riga di comando di Ade e JQ preinstallati. Altre informazioni su'interfaccia della riga di comando di Azure e sul pacchetto JQ.

Per installare eventuali altri pacchetti necessari all'interno dell'immagine, usare l'istruzione RUN.

3. Configurare gli script della shell delle operazioni

All'interno delle immagini standard, le operazioni vengono determinate ed eseguite in base al nome dell'operazione. Attualmente, i due nomi operazione supportati sono distribuire ed eliminare.

Per configurare l'immagine personalizzata e usare tale struttura, specificare una cartella a livello degli script denominati Dockerfile, e quindi specificare due file: deploy.sh e delete.sh. Lo script della shell di distribuzione viene eseguito quando l'ambiente viene creato o ridistribuito, e lo script della shell di eliminazione viene eseguito quando l'ambiente viene eliminato. È possibile visualizzare esempi di script della shell nel repository nella cartella Runner-Images per l'immagine ARM-Bicep.

Per accertare che gli script della shell siano eseguibili, aggiungere al Dockerfile le righe seguenti:

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

4. Creare script della shell delle operazioni per distribuire i modelli di Azure Resource Manager o Bicep

Per assicurarsi di poter distribuire correttamente l'infrastruttura ARM o Bicep tramite Ambienti di distribuzione di Azure, è necessario:

1. Convertire i parametri di Ambienti di distribuzione di Azure in parametri accettabili per ARM
2. Risolvere i modelli collegati se vengono usati nella distribuzione
3. Usare l'identità gestita con privilegi per eseguire la distribuzione

Nel punto di ingresso dell'immagine di base, i parametri impostati per l'ambiente corrente vengono archiviati nella variabile $ADE_OPERATION_PARAMETERS. Per convertirli in parametri accettabili per ARM, è possibile eseguire il comando seguente usando 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) }' )

Successivamente, per risolvere tutti i modelli collegati usati all'interno di un modello di ARM basato su JSON, è possibile decompilare il file modello principale, operazione che risolve tutti i file di infrastruttura locale usati in molti moduli Bicep. Ricompilare quindi questi moduli in un singolo modello di ARM con i modelli collegati incorporati nel modello di ARM di base come modelli annidati. Questo passaggio è necessario solo durante l'operazione di distribuzione. È possibile specificare il file modello di base usando $ADE_TEMPLATE_FILE impostato durante il punto di ingresso dell'immagine di base ed è necessario reimpostare questa variabile con il file modello ricompilato. Vedere l'esempio seguente:

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

Per fornire le autorizzazioni necessarie per la distribuzione e l'eliminazione delle risorse all'interno della sottoscrizione, usare l'identità gestita con privilegi associata al tipo di ambiente del progetto Ambienti di distribuzione di Azure. Se per completare la distribuzione sono necessarie autorizzazioni speciali, ad esempio ruoli specifici, assegnare tali ruoli all'identità del tipo di ambiente del progetto. In alcuni casi, l'identità gestita non è immediatamente disponibile quando si immette il contenitore; è possibile riprovare fino a quando l'accesso non riesce.

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

Per iniziare la distribuzione dei modelli ARM o Bicep, eseguire il comando az deployment group create. Quando si esegue questo comando all'interno del contenitore, scegliere un nome di distribuzione che non comporti la sostituzione delle distribuzioni precedenti e usare i flag --no-prompt true e --only-show-errors per assicurarsi che la distribuzione non fallisca in caso di avvisi e che non si blocchi in attesa dell'input dell'utente, come illustrato nell'esempio seguente:

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

Per eliminare un ambiente, eseguire una distribuzione in modalità completa e fornire un modello di ARM vuoto, che rimuove tutte le risorse all'interno del gruppo di risorse di Ambienti di distribuzione di Azure specificato, come illustrato nell'esempio seguente:

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"

È possibile controllare lo stato e i dettagli del provisioning eseguendo i comandi seguenti. Ambienti di distribuzione di Azure usa alcune funzioni speciali per leggere e fornire più contesto in base ai dettagli del provisioning, disponibili nella cartella Runner-Images. Un'implementazione semplice può essere la seguente:

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

Infine, per visualizzare gli output della distribuzione e passarli ad Ambienti di distribuzione di Azure per renderli accessibili tramite l'interfaccia della riga di comando di Azure, è possibile eseguire i comandi seguenti:

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

Compilare l'immagine personalizzata

È possibile creare l’immagine tramite l'interfaccia della riga di comando di Docker. Verificare che il motore Docker sia installato nel computer. Passare quindi alla directory del Dockerfile ed eseguire il comando seguente:

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

Ad esempio, se si vuole salvare l'immagine in un repository all'interno del registro denominato customImage e si desidera eseguire il caricamento con la versione tag di 1.0.0, si eseguirà:

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