Share via

Containerinstallatiekopieën configureren voor het uitvoeren van implementaties met ARM en Bicep

  • Artikel

In dit artikel leert u hoe u aangepaste Azure Resource Manager-installatiekopieën (ARM) en Bicep-containerinstallatiekopieën bouwt om uw omgevingsdefinities te implementeren in Azure Deployment Environments (ADE).

Een omgevingsdefinitie bestaat uit ten minste twee bestanden: een sjabloonbestand, zoals azuredeploy.json of main.bicep, en een manifestbestand met de naam environment.yaml. ADE maakt gebruik van containers voor het implementeren van omgevingsdefinities en biedt systeemeigen ondersteuning voor de ARM- en Bicep IaC-frameworks.

Met het ADE-uitbreidbaarheidsmodel kunt u aangepaste containerinstallatiekopieën maken voor gebruik met uw omgevingsdefinities. Met behulp van het uitbreidbaarheidsmodel kunt u uw eigen aangepaste containerinstallatiekopieën maken en opslaan in een containerregister, zoals DockerHub. U kunt vervolgens verwijzen naar deze installatiekopieën in uw omgevingsdefinities om uw omgevingen te implementeren.

Het ADE-team biedt een selectie van installatiekopieën om u op weg te helpen, waaronder een kerninstallatiekopieën en een Arm-/Bicep-installatiekopieën (Azure Resource Manager). U kunt deze voorbeeldafbeeldingen openen in de map Runner-Images .

De ADE CLI is een hulpprogramma waarmee u aangepaste installatiekopieën kunt maken met behulp van ADE-basisinstallatiekopieën. U kunt de ADE CLI gebruiken om uw implementaties en verwijderingen aan te passen aan uw werkstroom. De ADE CLI is vooraf geïnstalleerd op de voorbeeldafbeeldingen. Zie de referentie voor aangepaste Runner-installatiekopieën van CLI voor meer informatie over de ADE CLI.

Vereisten

Een Docker-installatiekopieën maken en bouwen

In dit voorbeeld leert u hoe u een Docker-installatiekopieën bouwt om ADE-implementaties te gebruiken en toegang te krijgen tot de ADE CLI, waarbij u uw installatiekopieën kunt baseren op een van de door ADE geschreven installatiekopieën.

Voer de volgende stappen uit om een installatiekopieën te bouwen die zijn geconfigureerd voor ADE:

  1. Baseer uw afbeelding op een voorbeeldafbeelding van ADE of de afbeelding van uw keuze met behulp van de FROM-instructie.
  2. Installeer alle benodigde pakketten voor uw installatiekopie met behulp van de RUN-instructie.
  3. Maak een map met scripts op hetzelfde niveau als uw Dockerfile, sla uw deploy.sh en delete.sh bestanden erin op en zorg ervoor dat deze scripts detecteerbaar en uitvoerbaar zijn in de gemaakte container. Deze stap is nodig om uw implementatie te laten werken met behulp van de ADE-kerninstallatiekopieën.
  4. Bouw en push uw installatiekopieën naar uw containerregister en zorg ervoor dat deze toegankelijk is voor ADE.
  5. Verwijs naar uw afbeelding in de runner eigenschap van uw omgevingsdefinitie.

Selecteer een voorbeeld van een containerinstallatiekopie met behulp van de FROM-instructie

Neem een FROM-instructie op in een gemaakte DockerFile voor uw nieuwe installatiekopie die verwijst naar een voorbeeldinstallatiekopie die wordt gehost op Microsoft-artefactregister.

Hier volgt een voorbeeld van een FROM-instructie, die verwijst naar de voorbeeldkernafbeelding:

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

Met deze instructie wordt de laatst gepubliceerde basisinstallatiekopie opgehaald en wordt deze een basis voor uw aangepaste installatiekopie.

Bicep installeren in een Dockerfile

U kunt het Bicep-pakket installeren met de Azure CLI met behulp van de RUN-instructie, zoals wordt weergegeven in het volgende voorbeeld:

RUN az bicep install

De ADE-voorbeeldinstallatiekopieën zijn gebaseerd op de Azure CLI-installatiekopieën en hebben de ADE CLI- en JQ-pakketten vooraf geïnstalleerd. Meer informatie over de Azure CLI en het JQ-pakket.

Als u meer pakketten wilt installeren die u nodig hebt in uw installatiekopie, gebruikt u de RUN-instructie.

Operation Shell-scripts uitvoeren

In de voorbeeldafbeeldingen worden bewerkingen bepaald en uitgevoerd op basis van de naam van de bewerking. Momenteel worden de twee ondersteunde bewerkingsnamen geïmplementeerd en verwijderd.

Als u uw aangepaste installatiekopieën wilt instellen om deze structuur te gebruiken, geeft u een map op het niveau van uw Dockerfile met de naam scripts op en geeft u twee bestanden op, deploy.sh en delete.sh. Het implementatieshell-script wordt uitgevoerd wanneer uw omgeving wordt gemaakt of opnieuw wordt geïmplementeerd en het shell-script verwijderen wordt uitgevoerd wanneer uw omgeving wordt verwijderd. U ziet voorbeelden van shellscripts in de opslagplaats onder de map Runner-Images voor de ARM-Bicep-installatiekopie .

Voeg de volgende regels toe aan uw Dockerfile om ervoor te zorgen dat deze shellscripts uitvoerbaar zijn:

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

Bewerkingsshellscripts ontwerpen voor het implementeren van ARM- of Bicep-sjablonen

Om ervoor te zorgen dat u de ARM- of Bicep-infrastructuur via ADE kunt implementeren, moet u het volgende doen:

  • ADE-parameters converteren naar ARM-acceptabele parameters
  • Gekoppelde sjablonen oplossen als ze worden gebruikt in de implementatie
  • Bevoegde beheerde identiteit gebruiken om de implementatie uit te voeren

Tijdens het ingangspunt van de kerninstallatiekopieën worden alle parameters die zijn ingesteld voor de huidige omgeving, opgeslagen onder de variabele $ADE_OPERATION_PARAMETERS. Als u ze wilt converteren naar ARM-acceptabele parameters, kunt u de volgende opdracht uitvoeren met behulp van 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) }' )

Als u vervolgens gekoppelde sjablonen wilt oplossen die worden gebruikt in een op ARM JSON gebaseerde sjabloon, kunt u het hoofdsjabloonbestand decompileren, waardoor alle lokale infrastructuurbestanden die in veel Bicep-modules worden gebruikt, worden omgezet. Bouw deze modules vervolgens opnieuw op in één ARM-sjabloon met de gekoppelde sjablonen die zijn ingesloten in de hoofd-ARM-sjabloon als geneste sjablonen. Deze stap is alleen nodig tijdens de implementatiebewerking. Het hoofdsjabloonbestand kan worden opgegeven met behulp van de $ADE_TEMPLATE_FILE set tijdens het invoerpunt van de kerninstallatiekopie en u moet deze variabele opnieuw instellen met het sjabloonbestand dat opnieuw is gecompileerd. Zie het volgende voorbeeld:

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

Gebruik de bevoegde beheerde identiteit die is gekoppeld aan het ADE-projectomgevingstype om de machtigingen op te geven die een implementatie vereist om de implementatie en het verwijderen van resources binnen het abonnement uit te voeren. Als uw implementatie speciale machtigingen nodig heeft om te voltooien, zoals bepaalde rollen, wijst u deze rollen toe aan de identiteit van het projectomgevingstype. Soms is de beheerde identiteit niet onmiddellijk beschikbaar bij het invoeren van de container; u kunt het opnieuw proberen totdat de aanmelding is geslaagd.

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

Voer de az deployment group create opdracht uit om de implementatie van de ARM- of Bicep-sjablonen te starten. Wanneer u deze opdracht uitvoert in de container, kiest u een implementatienaam die geen eerdere implementaties overschrijft en gebruikt u de --no-prompt true en --only-show-errors vlaggen om ervoor te zorgen dat de implementatie niet mislukt bij waarschuwingen of wacht op gebruikersinvoer, zoals wordt weergegeven in het volgende voorbeeld:

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

Als u een omgeving wilt verwijderen, voert u een implementatie in de volledige modus uit en geeft u een lege ARM-sjabloon op, waarmee alle resources in de opgegeven ADE-resourcegroep worden verwijderd, zoals wordt weergegeven in het volgende voorbeeld:

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"

U kunt de inrichtingsstatus en details controleren door de onderstaande opdrachten uit te voeren. ADE gebruikt enkele speciale functies om meer context te lezen en te bieden op basis van de inrichtingsgegevens, die u kunt vinden in de map Runner-Images . Een eenvoudige implementatie kan als volgt zijn:

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

Ten slotte kunt u de volgende opdrachten uitvoeren om de uitvoer van uw implementatie weer te geven en door te geven aan ADE om ze toegankelijk te maken via de Azure CLI:

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

De installatiekopie bouwen

Voordat u de installatiekopieën bouwt die naar uw register moeten worden gepusht, moet u ervoor zorgen dat de Docker Engine op uw computer is geïnstalleerd . Navigeer vervolgens naar de map van uw Dockerfile en voer de volgende opdracht uit:

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

Als u bijvoorbeeld uw installatiekopieën wilt opslaan onder een opslagplaats in het register met de naam customImageen wilt uploaden met de tagversie, 1.0.0voert u het volgende uit:

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

De Docker-installatiekopieën naar een register pushen

Als u aangepaste installatiekopieën wilt gebruiken, moet u een openbaar toegankelijk installatiekopieregister instellen met anonieme pull-installatiekopie ingeschakeld. Op deze manier hebben Azure Deployment Environments toegang tot uw aangepaste installatiekopieën die in onze container kunnen worden uitgevoerd.

Azure Container Registry is een Azure-aanbieding waarin containerinstallatiekopieën en vergelijkbare artefacten worden opgeslagen.

Volg een van de quickstarts om een register te maken dat kan worden uitgevoerd via de Azure CLI, Azure Portal, PowerShell-opdrachten en meer.

Voer de volgende opdrachten uit in de Azure CLI om uw register in te stellen voor het ophalen van anonieme installatiekopieën:

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

Wanneer u klaar bent om uw installatiekopieën naar uw register te pushen, voert u de volgende opdracht uit:

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

Verbinding maken de installatiekopieën naar uw omgevingsdefinitie

Wanneer u omgevingsdefinities maakt voor het gebruik van uw aangepaste installatiekopieën in de implementatie, bewerkt u de runner eigenschap in het manifestbestand (environment.yaml of manifest.yaml).

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

Een containerinstallatiekopieën bouwen met een script

Microsoft biedt een snelstartscript om u te helpen aan de slag te gaan. Het script bouwt uw installatiekopieën en pusht deze naar een opgegeven Azure Container Registry (ACR) onder de opslagplaats ade en de tag latest.

Als u het script wilt gebruiken, moet u het volgende doen:

  1. Configureer een dockerfile- en scriptsmap ter ondersteuning van het ADE-uitbreidbaarheidsmodel.
  2. Geef een registernaam en map op voor uw aangepaste installatiekopieën.
  3. Laat de Azure CLI en Docker Desktop zijn geïnstalleerd en in uw PATH-variabelen.
  4. Machtigingen hebben om naar het opgegeven register te pushen.

U kunt het script hier uitvoeren.

U kunt het script aanroepen met behulp van de volgende opdracht in PowerShell:

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

Als u bovendien wilt pushen naar een specifieke opslagplaats en tagnaam, kunt u het volgende uitvoeren:

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

Toegang tot bewerkingslogboeken en foutdetails

ADE slaat foutdetails op voor een mislukte implementatie in het bestand $ADE_ERROR_LOG in de container.

Problemen met een mislukte implementatie oplossen:

  1. Meld u aan bij de ontwikkelaarsportal.

  2. Identificeer de omgeving die niet kan worden geïmplementeerd en selecteer Details weergeven.

    Schermopname van foutdetails van mislukte implementatie, met name een ongeldige naam voor een opslagaccount.

  3. Bekijk de foutdetails in de sectie Foutdetails .

    Schermopname van een mislukte implementatie van een omgeving met de knop Details weergeven weergegeven.

Daarnaast kunt u de Azure CLI gebruiken om de foutdetails van een omgeving weer te geven met behulp van de volgende opdracht:

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

Als u de bewerkingslogboeken voor een omgevingsimplementatie of verwijdering wilt weergeven, gebruikt u de Azure CLI om de meest recente bewerking voor uw omgeving op te halen en bekijkt u vervolgens de logboeken voor die bewerkings-id.

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

Gerelateerde inhoud