Configurar imagem de contêiner para executar implantações

Criar uma imagem de contêiner personalizada usando um script

A criação de uma imagem de contêiner personalizada permite que você personalize suas implantações para atender às suas necessidades. Você pode criar imagens personalizadas com base nas imagens padrão do ADE.

Depois de concluir a personalização da imagem, você pode criar a imagem e enviá-la por push para o registro do contêiner usando um script fornecido pela Microsoft para automatizar o processo.

Você cria imagens personalizadas usando as imagens padrão do ADE como base com a CLI do ADE, que é pré-instalada nas imagens padrão. Para saber mais sobre a CLI do ADE, consulte a referência CLI Custom Runner Image.

Neste exemplo, você aprenderá a criar uma imagem do Docker para utilizar implantações do ADE e acessar a CLI do ADE, baseando sua imagem em uma das imagens criadas pelo ADE.

Para criar uma imagem configurada para o ADE, siga estes passos:

1. Crie uma imagem personalizada com base em uma imagem padrão.
2. Instale os pacotes desejados.
3. Configure scripts de shell de operação.
4. Crie scripts de shell de operação para implantar modelos ARM ou Bicep.

1. Crie uma imagem personalizada com base em uma imagem padrão

Crie um DockerFile que inclua uma instrução FROM apontando para uma imagem padrão hospedada no Microsoft Artifact Registry.

Aqui está um exemplo de instrução FROM, fazendo referência à imagem principal padrão:

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

Esta declaração extrai a imagem principal publicada mais recentemente e torna-a uma base para a sua imagem personalizada.

2. Instale os pacotes necessários

Nesta etapa, você instala todos os pacotes necessários em sua imagem, incluindo o Bicep. Você pode instalar o pacote Bicep com a CLI do Azure usando a instrução RUN, conforme mostrado no exemplo a seguir:

RUN az bicep install

As imagens padrão do ADE são baseadas na imagem da CLI do Azure e têm os pacotes ADE CLI e JQ pré-instalados. Você pode saber mais sobre a CLI do Azure e o pacote JQ.

Para instalar mais pacotes que você precisa em sua imagem, use a instrução RUN.

3. Configurar scripts de shell de operação

Dentro das imagens padrão, as operações são determinadas e executadas com base no nome da operação. Atualmente, os dois nomes de operação suportados são deploy e delete.

Para configurar sua imagem personalizada para utilizar essa estrutura, especifique uma pasta no nível dos scripts nomeados do Dockerfile e especifique dois arquivos, deploy.sh e delete.sh. O script de shell de implantação é executado quando seu ambiente é criado ou reimplantado e o script de shell de exclusão é executado quando seu ambiente é excluído. Você pode ver exemplos de shell scripts no repositório na pasta Runner-Images para a imagem ARM-Bicep .

Para garantir que esses shell scripts sejam executáveis, adicione as seguintes linhas ao seu Dockerfile:

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

4. Crie scripts de shell de operação para implantar modelos ARM ou Bicep

Para garantir que você possa implantar com êxito a infraestrutura ARM ou Bicep por meio do ADE, você deve:

1. Converter parâmetros ADE em parâmetros aceitáveis por ARM
2. Resolver modelos vinculados se eles forem usados na implantação
3. Usar identidade gerenciada privilegiada para executar a implantação

Durante o ponto de entrada da imagem principal, todos os parâmetros definidos para o ambiente atual são armazenados na variável $ADE_OPERATION_PARAMETERS. Para convertê-los em parâmetros aceitáveis para ARM, você pode executar o seguinte comando 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) }' )

Em seguida, para resolver quaisquer modelos vinculados usados em um modelo baseado em ARM JSON, você pode descompilar o arquivo de modelo principal, que resolve todos os arquivos de infraestrutura local usados em muitos módulos do Bicep. Em seguida, reconstrua esses módulos novamente em um único modelo ARM com os modelos vinculados incorporados ao modelo ARM principal como modelos aninhados. Esta etapa só é necessária durante a operação de implantação. O arquivo de modelo principal pode ser especificado usando o $ADE_TEMPLATE_FILE conjunto durante o ponto de entrada da imagem principal, e você deve redefinir essa variável com o arquivo de modelo recompilado. Veja o seguinte exemplo:

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

Para fornecer as permissões que uma implantação requer para executar a implantação e a exclusão de recursos dentro da assinatura, use a identidade gerenciada privilegiada associada ao tipo de ambiente de projeto ADE. Se sua implantação precisar de permissões especiais para ser concluída, como funções específicas, atribua essas funções à identidade do tipo de ambiente do projeto. Às vezes, a identidade gerenciada não está imediatamente disponível ao entrar no contêiner; Você pode tentar novamente até que o login seja bem-sucedido.

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

Para iniciar a implantação dos modelos ARM ou Bicep, execute o az deployment group create comando. Ao executar esse comando dentro do contêiner, escolha um nome de implantação que não substitua nenhuma implantação anterior e use os --no-prompt true sinalizadores e --only-show-errors para garantir que a implantação não falhe em nenhum aviso ou pare na espera pela entrada do usuário, conforme mostrado no exemplo a seguir:

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

Para excluir um ambiente, execute uma implantação de modo Completo e forneça um modelo ARM vazio, que remove todos os recursos dentro do grupo de recursos ADE especificado, conforme mostrado no exemplo a seguir:

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"

Você pode verificar o estado de provisionamento e os detalhes executando os comandos abaixo. O ADE usa algumas funções especiais para ler e fornecer mais contexto com base nos detalhes de provisionamento, que você pode encontrar na pasta Runner-Images . Uma implementação simples poderia ser a seguinte:

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

Finalmente, para exibir as saídas de sua implantação e passá-las para o ADE para torná-las acessíveis por meio da CLI do Azure, você pode executar os seguintes comandos:

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

Criar uma imagem de contêiner com um script

Em vez de criar sua imagem personalizada e enviá-la por conta própria para um registro de contêiner, você pode usar um script para compilá-la e enviá-la por push para um registro de contêiner especificado.

A Microsoft fornece um script de início rápido para ajudá-lo a criar sua imagem personalizada e enviá-la por push para um registro. O script cria sua imagem e a envia por push para um Registro de Contêiner do Azure (ACR) especificado no repositório ade e na tag latest.

Para usar o script, você deve:

1. Crie uma pasta Dockerfile e scripts para dar suporte ao modelo de extensibilidade do ADE.
2. Forneça um nome de registro e um diretório para sua imagem personalizada.
3. Tenha a CLI do Azure e o Docker Desktop instalados e em suas variáveis PATH.
4. Ter o Docker Desktop em execução.
5. Ter permissões para enviar por push para o registro especificado.

Você pode ver o script aqui.

Você pode chamar o script usando o seguinte comando no PowerShell:

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

Além disso, se você quiser enviar por push para um repositório específico e nome de tag, você pode executar:

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

Criar uma imagem de contêiner personalizada manualmente

A criação de uma imagem de contêiner personalizada permite que você personalize suas implantações para atender às suas necessidades. Você pode criar imagens personalizadas com base nas imagens padrão do ADE.

Depois de concluir a personalização da imagem, você pode criar a imagem e enviá-la manualmente para o registro do contêiner.

Você cria imagens personalizadas usando as imagens padrão do ADE como base com a CLI do ADE, que é pré-instalada nas imagens padrão. Para saber mais sobre a CLI do ADE, consulte a referência CLI Custom Runner Image.

Neste exemplo, você aprenderá a criar uma imagem do Docker para utilizar implantações do ADE e acessar a CLI do ADE, baseando sua imagem em uma das imagens criadas pelo ADE.

Para criar uma imagem configurada para o ADE, siga estes passos:

1. Crie uma imagem personalizada com base em uma imagem padrão.
2. Instale os pacotes desejados.
3. Configure scripts de shell de operação.
4. Crie scripts de shell de operação para implantar modelos ARM ou Bicep.

1. Crie uma imagem personalizada com base em uma imagem padrão

Crie um DockerFile que inclua uma instrução FROM apontando para uma imagem padrão hospedada no Microsoft Artifact Registry.

Aqui está um exemplo de instrução FROM, fazendo referência à imagem principal padrão:

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

Esta declaração extrai a imagem principal publicada mais recentemente e torna-a uma base para a sua imagem personalizada.

2. Instale os pacotes necessários

Nesta etapa, você instala todos os pacotes necessários em sua imagem, incluindo o Bicep. Você pode instalar o pacote Bicep com a CLI do Azure usando a instrução RUN, conforme mostrado no exemplo a seguir:

RUN az bicep install

As imagens padrão do ADE são baseadas na imagem da CLI do Azure e têm os pacotes ADE CLI e JQ pré-instalados. Você pode saber mais sobre a CLI do Azure e o pacote JQ.

Para instalar mais pacotes que você precisa em sua imagem, use a instrução RUN.

3. Configurar scripts de shell de operação

Dentro das imagens padrão, as operações são determinadas e executadas com base no nome da operação. Atualmente, os dois nomes de operação suportados são deploy e delete.

Para configurar sua imagem personalizada para utilizar essa estrutura, especifique uma pasta no nível dos scripts nomeados do Dockerfile e especifique dois arquivos, deploy.sh e delete.sh. O script de shell de implantação é executado quando seu ambiente é criado ou reimplantado e o script de shell de exclusão é executado quando seu ambiente é excluído. Você pode ver exemplos de shell scripts no repositório na pasta Runner-Images para a imagem ARM-Bicep .

Para garantir que esses shell scripts sejam executáveis, adicione as seguintes linhas ao seu Dockerfile:

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

4. Crie scripts de shell de operação para implantar modelos ARM ou Bicep

Para garantir que você possa implantar com êxito a infraestrutura ARM ou Bicep por meio do ADE, você deve:

1. Converter parâmetros ADE em parâmetros aceitáveis por ARM
2. Resolver modelos vinculados se eles forem usados na implantação
3. Usar identidade gerenciada privilegiada para executar a implantação

Durante o ponto de entrada da imagem principal, todos os parâmetros definidos para o ambiente atual são armazenados na variável $ADE_OPERATION_PARAMETERS. Para convertê-los em parâmetros aceitáveis para ARM, você pode executar o seguinte comando 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) }' )

Em seguida, para resolver quaisquer modelos vinculados usados em um modelo baseado em ARM JSON, você pode descompilar o arquivo de modelo principal, que resolve todos os arquivos de infraestrutura local usados em muitos módulos do Bicep. Em seguida, reconstrua esses módulos novamente em um único modelo ARM com os modelos vinculados incorporados ao modelo ARM principal como modelos aninhados. Esta etapa só é necessária durante a operação de implantação. O arquivo de modelo principal pode ser especificado usando o $ADE_TEMPLATE_FILE conjunto durante o ponto de entrada da imagem principal, e você deve redefinir essa variável com o arquivo de modelo recompilado. Veja o seguinte exemplo:

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

Para fornecer as permissões que uma implantação requer para executar a implantação e a exclusão de recursos dentro da assinatura, use a identidade gerenciada privilegiada associada ao tipo de ambiente de projeto ADE. Se sua implantação precisar de permissões especiais para ser concluída, como funções específicas, atribua essas funções à identidade do tipo de ambiente do projeto. Às vezes, a identidade gerenciada não está imediatamente disponível ao entrar no contêiner; Você pode tentar novamente até que o login seja bem-sucedido.

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

Para iniciar a implantação dos modelos ARM ou Bicep, execute o az deployment group create comando. Ao executar esse comando dentro do contêiner, escolha um nome de implantação que não substitua nenhuma implantação anterior e use os --no-prompt true sinalizadores e --only-show-errors para garantir que a implantação não falhe em nenhum aviso ou pare na espera pela entrada do usuário, conforme mostrado no exemplo a seguir:

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

Para excluir um ambiente, execute uma implantação de modo Completo e forneça um modelo ARM vazio, que remove todos os recursos dentro do grupo de recursos ADE especificado, conforme mostrado no exemplo a seguir:

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"

Você pode verificar o estado de provisionamento e os detalhes executando os comandos abaixo. O ADE usa algumas funções especiais para ler e fornecer mais contexto com base nos detalhes de provisionamento, que você pode encontrar na pasta Runner-Images . Uma implementação simples poderia ser a seguinte:

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

Finalmente, para exibir as saídas de sua implantação e passá-las para o ADE para torná-las acessíveis por meio da CLI do Azure, você pode executar os seguintes comandos:

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

Criar a imagem personalizada

Você pode criar sua imagem usando a CLI do Docker. Verifique se o Docker Engine está instalado no seu computador. Em seguida, navegue até o diretório do seu Dockerfile e execute o seguinte comando:

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

Por exemplo, se você quiser salvar sua imagem em um repositório dentro do seu registro chamado customImage, e carregar com a versão da tag do 1.0.0, você deve executar:

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