Configurar imagem de contêiner para executar implantações com ARM e Bicep
Neste artigo, você aprenderá a criar imagens de contêiner personalizadas do Azure Resource Manager (ARM) e do Bicep para implantar suas definições de ambiente nos Ambientes de Implantação do Azure (ADE).
Uma definição de ambiente compreende pelo menos dois arquivos: um arquivo de modelo, como azuredeploy.json ou main.bicep, e um arquivo de manifesto chamado environment.yaml. O ADE usa contêineres para implantar definições de ambiente e suporta nativamente as estruturas ARM e Bicep IaC.
O modelo de extensibilidade ADE permite criar imagens de contêiner personalizadas para usar com suas definições de ambiente. Usando o modelo de extensibilidade, você pode criar suas próprias imagens de contêiner personalizadas e armazená-las em um registro de contêiner como o DockerHub. Em seguida, você pode fazer referência a essas imagens em suas definições de ambiente para implantar seus ambientes.
A equipe do ADE fornece uma seleção de imagens para você começar, incluindo uma imagem principal e uma imagem do Azure Resource Manager (ARM)/Bicep. Você pode acessar essas imagens de exemplo na pasta Runner-Images .
Pré-requisitos
- Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
- Ambientes de Implantação do Azure configurados em sua assinatura do Azure.
- Para configurar o ADE, siga o Guia de início rápido: configurar ambientes de implantação do Azure.
Usar imagens de contêiner com o ADE
Você pode adotar uma das seguintes abordagens para usar imagens de contêiner com o ADE:
- Use a imagem de contêiner padrão: para cenários simples, use a imagem de contêiner Bicep padrão fornecida pelo ADE.
- Criar uma imagem de contêiner personalizada: para cenários mais complexos, crie uma imagem de contêiner personalizada que atenda às suas necessidades específicas.
Independentemente da abordagem escolhida, você deve especificar a imagem de contêiner em sua definição de ambiente para implantar seus recursos do Azure.
Usar a imagem de contêiner padrão do Bíceps
O ADE dá suporte ao Bicep nativamente, portanto, você pode configurar uma definição de ambiente que implanta recursos do Azure para um ambiente de implantação adicionando os arquivos de modelo (azuredeploy.json e environment.yaml) ao seu catálogo. Em seguida, o ADE usa a imagem de contêiner padrão do Bicep para criar o ambiente de implantação.
No arquivo environment.yaml, a propriedade runner especifica o local da imagem de contêiner que você deseja usar. Para usar a imagem de exemplo publicada no Microsoft Artifact Registry, use o respetivo corredor de identificadores, conforme listado na tabela a seguir.
O exemplo a seguir mostra um corredor que faz referência à imagem de contêiner Bicep de exemplo:
name: WebApp
version: 1.0.0
summary: Azure Web App Environment
description: Deploys a web app in Azure without a datastore
runner: Bicep
templatePath: azuredeploy.json
Você pode ver a imagem do contêiner Bicep padrão no repositório de exemplo do ADE na pasta Runner-Images para a imagem ARM-Bicep .
Para obter mais informações sobre como criar definições de ambiente que usam as imagens de contêiner do ADE para implantar seus recursos do Azure, consulte Adicionar e configurar uma definição de ambiente.
Criar uma imagem de contêiner Bicep personalizada
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 de contêiner padrão do ADE.
Depois de concluir a personalização da imagem, você deve criar a imagem e enviá-la por push para o registro do contêiner.
Criar e personalizar uma imagem de contêiner com o Docker
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.
A CLI ADE é uma ferramenta que permite criar imagens personalizadas usando imagens base ADE. Você pode usar a CLI do ADE para personalizar suas implantações e exclusões para se adequar ao seu fluxo de trabalho. A CLI ADE está pré-instalada nas imagens de exemplo. Para saber mais sobre a CLI do ADE, consulte a referência CLI Custom Runner Image.
Para criar uma imagem configurada para o ADE, siga estes passos:
- Baseie sua imagem em uma imagem de amostra criada pelo ADE ou na imagem de sua escolha usando a instrução FROM.
- Instale todos os pacotes necessários para sua imagem usando a instrução RUN.
- Crie uma pasta de scripts no mesmo nível do seu Dockerfile, armazene seus arquivos deploy.sh e delete.sh dentro dela e certifique-se de que esses scripts sejam detetáveis e executáveis dentro do contêiner criado. Esta etapa é necessária para que sua implantação funcione usando a imagem principal do ADE.
Selecione uma imagem de contêiner de exemplo usando a instrução FROM
Inclua uma instrução FROM em um DockerFile criado para sua nova imagem apontando para uma imagem de exemplo hospedada no Microsoft Artifact Registry.
Aqui está um exemplo de instrução FROM, fazendo referência à imagem principal de exemplo:
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.
Instalar o Bicep em um Dockerfile
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 de exemplo 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.
Executar scripts de shell de operação
Nas imagens de exemplo, 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 {} \;
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:
- Converter parâmetros ADE em parâmetros aceitáveis por ARM
- Resolver modelos vinculados se eles forem usados na implantação
- 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
Tornar a imagem personalizada acessível ao ADE
Você deve criar sua imagem do Docker e enviá-la por push para o registro do contêiner para disponibilizá-la para uso no ADE. Você pode criar sua imagem usando a CLI do Docker ou usando um script fornecido pelo ADE.
Selecione a guia apropriada para saber mais sobre cada abordagem.
Antes de criar a imagem a ser enviada por push para o registro, verifique se o mecanismo do Docker está instalado no 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
Enviar a imagem do Docker para um registro
Para usar imagens personalizadas, você precisa configurar um registro de imagem acessível publicamente com o pull de imagem anônimo habilitado. Dessa forma, os Ambientes de Implantação do Azure podem acessar sua imagem personalizada para executar em nosso contêiner.
O Registro de Contêiner do Azure é uma oferta do Azure que armazena imagens de contêiner e artefatos semelhantes.
Para criar um registro, o que pode ser feito por meio da CLI do Azure, do portal do Azure, dos comandos do PowerShell e muito mais, siga um dos inícios rápidos.
Para configurar seu registro para ter o pull de imagem anônimo habilitado, execute os seguintes comandos na CLI do Azure:
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
Quando estiver pronto para enviar a imagem para o Registro, execute o seguinte comando:
docker push {YOUR_REGISTRY}.azurecr.io/{YOUR_IMAGE_LOCATION}:{YOUR_TAG}
Conecte a imagem à sua definição de ambiente
Ao criar definições de ambiente para usar sua imagem personalizada em sua implantação, edite a runner propriedade no arquivo de manifesto (environment.yaml ou manifest.yaml).
runner: "{YOUR_REGISTRY}.azurecr.io/{YOUR_REPOSITORY}:{YOUR_TAG}"
Para saber mais sobre como criar definições de ambiente que usam as imagens de contêiner do ADE para implantar seus recursos do Azure, consulte Adicionar e configurar uma definição de ambiente.
Acessar logs de operação e detalhes de erro
O ADE armazena detalhes de erro para uma implantação com falha no arquivo $ADE_ERROR_LOG dentro do contêiner.
Para solucionar problemas de uma implantação com falha:
Faça login no Portal do desenvolvedor.
Identifique o ambiente que falhou na implantação e selecione Ver detalhes.
Analise os detalhes do erro na seção Detalhes do erro.
Além disso, você pode usar a CLI do Azure para exibir os detalhes de erro de um ambiente usando o seguinte comando:
az devcenter dev environment show --environment-name {YOUR_ENVIRONMENT_NAME} --project {YOUR_PROJECT_NAME}
Para exibir os logs de operação para uma implantação ou exclusão de ambiente, use a CLI do Azure para recuperar a operação mais recente para seu ambiente e, em seguida, exiba os logs dessa ID de operação.
# 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}
Conteúdos relacionados
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários