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

O ADE (Ambientes de Implantação do Azure) dá suporte a um modelo de extensibilidade que permite configurar sua definição de ambiente com sua estrutura de modelo de IaC preferida. É possível armazenar imagens personalizadas em um registro de contêiner, como o Registro de Contêiner do Azure (ACR) ou o Docker Hub e, em seguida, referenciá-las em suas definições de ambiente para implantar ambientes.

Nesse artigo, você aprenderá a criar imagens de contêiner Bicep personalizadas para implantar suas definições de ambiente no ADE. Você aprenderá a usar uma imagem padrão fornecida pela Microsoft ou como configurar uma infraestrutura de fornecimento de imagem personalizada usando a Infraestrutura como Código (IaC) Bicep.

Neste artigo, você aprenderá a criar imagens de contêiner Terraform personalizadas para criar ambientes de implantação com o ADE (Ambientes de Implantação Azure). Você aprenderá a configurar uma imagem personalizada para provisionar a infraestrutura usando a estrutura IaC (Infraestrutura como Código) do Terraform.

Neste artigo, você aprenderá a utilizar o Pulumi para implantações no ADE. Você aprenderá a usar uma imagem padrão fornecida pelo Pulumi ou como configurar uma imagem personalizada para provisionar a infraestrutura usando a Infraestrutura como Código (IaC) Pulumi.

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
• Os Ambientes de Implantação do Azure configurados na sua assinatura do Azure.
  • Para configurar o ADE, siga o Início rápido: configurar Ambientes de Implantação Azure.

Usar imagens de contêiner com a ADE

Você pode adotar uma das seguintes abordagens para usar imagens de contêiner com o ADE:

• Use uma imagem de contêiner padrão: Para cenários simples, use a imagem de contêiner ARM-Bicep padrão fornecida pelo ADE.
• Crie uma imagem de contêiner personalizada Para cenários mais complexos, crie uma imagem de contêiner personalizada que atenda aos seus requisitos específicos.

Usar uma imagem de contêiner padrão

O ADE dá suporte ao ARM (Azure Resource Manager) e ao Bicep sem a necessidade de nenhuma configuração extra. Você pode criar uma definição de ambiente que implante recursos do Azure para um ambiente de implantação adicionando os arquivos de modelo (como azuredeploy.json e environment.yaml) ao seu catálogo. Em seguida, o ADE usa a imagem de contêiner ARM-Bicep padrão para criar o ambiente de implantação.

No arquivo environment.yaml, a propriedade runner especifica o local da imagem do contêiner que você deseja usar. Para usar a imagem padrão publicada no Registro de Artefato da Microsoft, use os respectivos identificadores runner.

O exemplo a seguir mostra um runner que faz referência à imagem do contêiner ARM-Bicep padrão:

    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

Pode visualizar a imagem do contentor Bicep padrão no repositório padrão 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 personalizada

Criar uma imagem personalizada usando um script

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 e compilar uma imagem com base na imagem padrão do ADE e enviá-la por push para o registro de contêiner usando um script de início rápido fornecido pela Microsoft. Você pode encontrar o script no repositório Ambientes de Implantação. Para usar o script de início rápido, bifurque o repositório e execute o script localmente.

O script compila uma imagem e a envia por push para um ACR (Registro de Contêiner do Azure) especificado no repositório "ade" e na marca "latest". Esse script requer o nome e o diretório do registro da sua imagem personalizada, ter a CLI do Azure e o Docker Desktop instalados e em suas variáveis PATH e exigir que você tenha permissões para enviar por push para o registro especificado.

Para usar o script de início rápido para criar e enviar por push rapidamente essa imagem de exemplo para um Registro de Contêiner do Azure, você precisará:

• Bifurque esse repositório em sua conta pessoal.
• Verifique se a CLI do Azure e o aplicativo Docker Desktop estão instalados em seu computador e em suas variáveis PATH.
• Verifique se você tem permissões para enviar imagens por push para o Registro de Contêiner do Azure selecionado.

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 um nome de marca, poderá executar:

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

Para usar a imagem em suas implantações de ambiente, você precisa adicionar o local da imagem ao arquivo de manifesto, conectar a imagem à definição de ambiente e talvez seja necessário configurar permissões para que o ACR disponibilize a imagem personalizada para o ADE.

Criar uma imagem personalizada manualmente

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. É possível criar imagens personalizadas com base nas imagens padrão do ADE.

Após concluir a personalização da imagem, você poderá compilar a imagem e efetuá-la por push para o registro de contêiner manualmente.

Você cria imagens personalizadas usando as imagens padrão do ADE como base com o ADE CLI, que é pré-instalado nas imagens padrão. Para saber mais sobre a CLI do ADE, veja a referência da imagem do corredor personalizado da CLI.

Nesse exemplo, você aprende como 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 estas etapas:

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

1. Criar 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 Registro de Artefato da Microsoft.

Aqui está um exemplo de instrução FROM, referenciando a imagem principal padrão:

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

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

2. Instalar pacotes necessários

Nessa etapa, você instala todos os pacotes necessários na 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 da CLI do ADE e JQ pré-instalados. Você pode aprender mais sobre o CLI do Azure e o pacote JQ.

Para instalar mais pacotes necessários em sua imagem, use a instrução RUN.

3. Configurar scripts de shell de operação

Nas 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 implantação e excluir.

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

Para garantir que esses scripts de shell 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. Use identidade gerenciada privilegiada para realizar a implantação

Durante o ponto de entrada da imagem principal, quaisquer parâmetros definidos para o ambiente atual são armazenados na variável $ADE_OPERATION_PARAMETERS. Para convertê-los em parâmetros aceitáveis pelo 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 ARM baseado em JSON, você pode descompilar o arquivo de modelo principal, que resolve todos os arquivos de infraestrutura local usados em muitos módulos 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. Essa etapa só é necessária durante a operação de implantação. O arquivo de modelo principal pode ser especificado usando o $ADE_TEMPLATE_FILE definido durante o ponto de entrada da imagem principal, e você deve redefinir essa variável com o arquivo de modelo recompilado. Consulte 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 eliminação de recursos dentro da subscrição, utilize a identidade gerida privilegiada associada ao tipo de ambiente do projeto ADE. Se a 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á disponível imediatamente ao inserir o contêiner; você pode tentar novamente até que a entrada seja bem-sucedida.

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 comando az deployment group create. 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 sinalizadores --no-prompt true e --only-show-errors para garantir que a implantação não falhe em nenhum aviso ou pare ao aguardar a entrada do usuário, conforme mostrado em o seguinte exemplo:

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 em 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 e os detalhes do provisionamento 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 ver as saídas da sua implantação e passá-las para o ADE para torná-las acessíveis através do CLI do Azure, 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 o Docker CLI. Certifique-se de que o Docker Engine esteja 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 customImagee fazer upload com a tag version de1.0.0, você executaria:

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

Usar imagens de contêiner com a ADE

Você pode adotar uma das seguintes abordagens para usar imagens de contêiner com o ADE:

• Criar uma imagem de contêiner personalizada usando um script: use o script publicado para criar uma imagem específica do Terraform.
• Criar uma imagem de contêiner personalizada aproveitando um fluxo de trabalho do GitHub: use o fluxo de trabalho publicado do GitHub no repositório Usar o modelo de extensibilidade do ADE com o Terraform.
• Criar uma imagem de contêiner personalizada manualmente: crie uma imagem específica do Terraform personalizada manualmente

Criar uma imagem de contêiner personalizada

Criar uma imagem usando um script

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 compilar uma imagem com base na imagem padrão do ADE e enviá-la por push para o registro de contêiner usando um script de início rápido fornecido pela Microsoft. Você pode encontrar o script no repositório Ambientes de Implantação com o Terraform. Para usar o script de início rápido, bifurque o repositório e execute o script localmente.

Para usar o script de início rápido para criar e enviar por push rapidamente essa imagem de exemplo para um Registro de Contêiner do Azure, você precisará:

• Bifurque esse repositório em sua conta pessoal.
• Verifique se a CLI do Azure e o aplicativo Docker Desktop estão instalados em seu computador e em suas variáveis PATH.
• Verifique se você tem permissões para enviar imagens por push para o Registro de Contêiner do Azure selecionado.

O script compila uma imagem e a envia por push para um ACR (Registro de Contêiner do Azure) especificado no repositório "ade" e na marca "latest". Esse script requer o nome e o diretório do registro da sua imagem personalizada, ter a CLI do Azure e o Docker Desktop instalados e em suas variáveis PATH e exigir que você tenha permissões para enviar por push para o registro especificado. 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 um nome de marca, poderá executar:

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

Para usar a imagem em suas implantações de ambiente, você precisa adicionar o local da imagem ao arquivo de manifesto, conectar a imagem à definição de ambiente e talvez seja necessário configurar permissões para que o ACR disponibilize a imagem personalizada para o ADE.

Criar uma imagem usando um fluxo de trabalho do GitHub

Criar uma imagem de contêiner personalizada usando um fluxo de trabalho do GitHub

Para começar, use o fluxo de trabalho publicado do GitHub no repositório Usar o modelo de extensibilidade do ADE com o Terraform.

Para usar o fluxo de trabalho, você precisa:

• Bifurcar esse repositório em sua conta pessoal
• Permitir que o GitHub Actions se conecte ao Azure por meio das credenciais federadas de um aplicativo do Microsoft Entra ID por meio do OIDC. Você pode encontrar a documentação sobre esse processo aqui
• Configure os Segredos do Repositório do repositório que contém a ID do aplicativo do Microsoft Entra ID definida como AZURE_CLIENT_ID, a ID da assinatura definida como AZURE_SUBSCRIPTION_ID e a ID do locatário definida como AZURE_TENANT_ID
• Configure as Variáveis do Repositório do seu repositório que contém seu nome pessoal do ACR (Registro de Contêiner do Azure) como REGISTRY_NAME, seu nome de repositório preferencial como REPOSITORY_NAME e sua marca preferencial como TAG para a imagem criada. Você pode modificar suas variáveis entre execuções de fluxo de trabalho para enviar a imagem gerada por push para diferentes registros, repositórios e marcas.

Execute o fluxo de trabalho navegando até a guia Ações em seu repositório bifurcado e selecionando o fluxo de trabalho que você deseja executar. Em seguida, você pode selecionar o botão Executar fluxo de trabalho para iniciar o fluxo de trabalho.

Para usar a imagem em suas implantações de ambiente, você precisa adicionar o local da imagem ao arquivo de manifesto, conectar a imagem à definição de ambiente e talvez seja necessário configurar permissões para que o ACR disponibilize a imagem personalizada para o ADE.

Criar uma imagem manualmente

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. É possível criar imagens personalizadas com base nas imagens padrão do ADE.

Depois de concluir a personalização da imagem, você deve compilar a imagem e efetuá-la por push para o registro de contêiner.

Você pode criar e enviar a imagem manualmente ou usar um script fornecido pela Microsoft para automatizar o processo.

A Ação do GitHub publicada ajuda a criar e enviar uma imagem por push para um ACR (Registro de Contêiner do Azure). É possível referenciar um link de imagem do ACR fornecido em uma definição de ambiente no ADE para implantar ou excluir um ambiente com a imagem fornecida.

Para criar uma imagem configurada para o ADE, siga estas etapas:

1. Crie uma imagem personalizada com base em um fluxo de trabalho do GitHub.
2. Instale os pacotes desejados.
3. Configurar scripts de shell de operação.
4. Crie scripts de shell de operação que usem o Terraform CLI.

1. Criar uma imagem personalizada com base em um fluxo de trabalho do GitHub

Use o repositório publicado para aproveitar o fluxo de trabalho do GitHub. O repositório contém componentes de imagem de exemplo compatíveis com ADE, incluindo um Dockerfile e scripts de shell para implantar e excluir ambientes usando modelos IaC do Terraform. Este código de exemplo ajuda você a criar sua própria imagem de contêiner.

2. Instalar pacotes necessários: nessa etapa, você instala todos os pacotes necessários na sua imagem, incluindo o Terraform. Instale a CLI do Terraform em um local executável para que ela possa ser usada nos scripts de implantação e exclusão.

Este é um exemplo desse processo, com a instalação da versão 1.7.5 da CLI do Terraform:

RUN wget -O terraform.zip https://releases.hashicorp.com/terraform/1.7.5/terraform_1.7.5_linux_amd64.zip
RUN unzip terraform.zip && rm terraform.zip
RUN mv terraform /usr/bin/terraform

Dica

Obtenha a URL de download da sua versão preferida da CLI do Terraform em Lançamentos da Hashicorp.

3. Configurar scripts de shell de operação

Nas 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 implantação e excluir.

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

Para garantir que esses scripts de shell 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 que usem o Terraform CLI

Há três etapas para implantar a infraestrutura por meio do Terraform:

1. terraform init: inicializa a CLI do Terraform para executar ações no diretório de trabalho
2. terraform plan: desenvolve um plano com base nos arquivos e variáveis de infraestrutura do Terraform de entrada e em todos os arquivos de estado existentes e desenvolve as etapas necessárias para criar ou atualizar a infraestrutura especificada nos arquivos .tf
3. terraform apply – aplica o plano para criar uma infraestrutura nova ou atualizada existente no Azure

Durante o ponto de entrada da imagem principal, todos os arquivos de estado existentes são extraídos para o contêiner e o diretório salvo na variável de ambiente $ADE_STORAGE. Além disso, todos os parâmetros definidos para o ambiente atual são armazenados na variável $ADE_OPERATION_PARAMETERS. Para acessar o arquivo de estado existente e definir suas variáveis em um arquivo .tfvars.json, execute os seguintes comandos:

set -e #set script to exit on error
EnvironmentState="$ADE_STORAGE/environment.tfstate"
EnvironmentPlan="/environment.tfplan"
EnvironmentVars="/environment.tfvars.json"

echo "$ADE_OPERATION_PARAMETERS" > $EnvironmentVars

Além disso, para utilizar os privilégios ADE para implantar a infraestrutura dentro de sua assinatura, seu script precisa usar a MSI (Identidade de Serviço Gerenciado) ao provisionar a infraestrutura usando o provedor AzureRM do Terraform. Se a sua implantação precisar de permissões especiais para ser concluída, como funções específicas, atribua essas permissões à identidade do tipo de ambiente do projeto que está sendo usada para a implantação do ambiente. O ADE define as variáveis de ambiente relevantes, como o cliente, o locatário e as IDs de assinatura dentro do ponto de entrada da imagem principal, portanto, execute os seguintes comandos para garantir que o provedor use a MSI do ADE:

export ARM_USE_MSI=true
export ARM_CLIENT_ID=$ADE_CLIENT_ID
export ARM_TENANT_ID=$ADE_TENANT_ID
export ARM_SUBSCRIPTION_ID=$ADE_SUBSCRIPTION_ID

Caso tenha outras variáveis para fazer referência ao modelo que não estão especificadas nos parâmetros do ambiente, defina variáveis de ambiente usando o prefixo TF_VAR. É fornecida uma lista de variáveis de ambiente ADE fornecidas Referência de variáveis CLI do Ambiente de Implantação do Azure. Um exemplo desses comandos pode ser;

export TF_VAR_resource_group_name=$ADE_RESOURCE_GROUP_NAME
export TF_VAR_ade_env_name=$ADE_ENVIRONMENT_NAME
export TF_VAR_env_name=$ADE_ENVIRONMENT_NAME
export TF_VAR_ade_subscription=$ADE_SUBSCRIPTION_ID
export TF_VAR_ade_location=$ADE_ENVIRONMENT_LOCATION
export TF_VAR_ade_environment_type=$ADE_ENVIRONMENT_TYPE

Agora, você poderá executar as etapas listadas anteriormente para inicializar a CLI do Terraform, gerar um plano para a infraestrutura de provisionamento e aplicar um plano durante o script de implantação:

terraform init
terraform plan -no-color -compact-warnings -refresh=true -lock=true -state=$EnvironmentState -out=$EnvironmentPlan -var-file="$EnvironmentVars"
terraform apply -no-color -compact-warnings -auto-approve -lock=true -state=$EnvironmentState $EnvironmentPlan

Durante o script de exclusão, adicione o sinalizador destroy à geração do plano a fim de excluir os recursos existentes, conforme mostrado no exemplo a seguir:

terraform init
terraform plan -no-color -compact-warnings -destroy -refresh=true -lock=true -state=$EnvironmentState -out=$EnvironmentPlan -var-file="$EnvironmentVars"
terraform apply -no-color -compact-warnings -auto-approve -lock=true -state=$EnvironmentState $EnvironmentPlan

Por fim, para tornar as saídas da implantação carregadas e disponíveis ao acessar seu ambiente por meio da CLI do Azure, transforme o objeto de saída do Terraform para o formato especificado pelo ADE por meio do pacote JQ. Defina o valor como a variável de ambiente $ADE_OUTPUTS, conforme mostrado no exemplo a seguir:

tfOutputs=$(terraform output -state=$EnvironmentState -json)
# Convert Terraform output format to ADE format.
tfOutputs=$(jq 'walk(if type == "object" then 
            if .type == "bool" then .type = "boolean" 
            elif .type == "list" then .type = "array" 
            elif .type == "map" then .type = "object" 
            elif .type == "set" then .type = "array" 
            elif (.type | type) == "array" then 
                if .type[0] == "tuple" then .type = "array" 
                elif .type[0] == "object" then .type = "object" 
                elif .type[0] == "set" then .type = "array" 
                else . 
                end 
            else . 
            end 
        else . 
        end)' <<< "$tfOutputs")

echo "{\"outputs\": $tfOutputs}" > $ADE_OUTPUTS

Criar a imagem personalizada

Você pode criar sua imagem usando o Docker CLI. Certifique-se de que o Docker Engine esteja 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 customImagee fazer upload com a tag version de1.0.0, você executaria:

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

Usar uma imagem de contêiner padrão fornecida pelo Pulumi

A equipe Pulumi fornece uma imagem predefinida para você começar, o que você pode ver na pasta Runner-Image. Esta imagem está disponível publicamente no Docker Hub do Pulumi como pulumi/azure-deployment-environments, para que você possa usá-la diretamente nas definições de ambiente do ADE.

Aqui está um exemplo de arquivo environment.yaml que utiliza a imagem pré-criada:

name: SampleDefinition
version: 1.0.0
summary: First Pulumi-Enabled Environment
description: Deploys a Storage Account with Pulumi
runner: pulumi/azure-deployment-environments:0.1.0
templatePath: Pulumi.yaml

Você pode encontrar algumas definições de ambiente de exemplo na pasta Ambientes.

Criar uma imagem personalizada

A criação de uma imagem de contêiner personalizada permite que você personalize suas implantações para atender às suas necessidades. É possível criar imagens personalizadas com base nas imagens padrão do Pulumi e personalizá-las para atender às suas necessidades. Depois de concluir a personalização da imagem, você deve compilar a imagem e efetuá-la por push para o registro de contêiner.

Para criar uma imagem configurada para o ADE, siga estas etapas:

1. Crie uma imagem personalizada com base em uma imagem padrão.
2. Instale os pacotes desejados.
3. Configurar scripts de shell de operação.
4. Crie scripts de shell de operação que usem o Pulumi CLI.

1. Criar 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 Registro de Artefato da Microsoft.

Aqui está um exemplo de instrução FROM, referenciando a imagem principal padrão:

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

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

2. Instalar pacotes necessários

Você pode instalar a CLI Pulumi em um local executável para que ela possa ser usada em seus scripts de implantação e exclusão.

Aqui está um exemplo desse processo, instalando a versão mais recente da CLI Pulumi:

RUN apk add curl
RUN curl -fsSL https://get.pulumi.com | sh
ENV PATH="${PATH}:/root/.pulumi/bin"

Dependendo da linguagem de programação que você pretende usar para os programas Pulumi, pode ser necessário instalar um ou mais tempos de execução correspondentes. O runtime do Python já está disponível na imagem base.

Aqui está um exemplo de instalação Node.js e TypeScript:

# install node.js, npm, and typescript
RUN apk add nodejs npm
RUN npm install typescript -g

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

Para instalar mais pacotes necessários em sua imagem, use a instrução RUN.

Há quatro etapas para implantar a infraestrutura por meio do Pulumi:

1. pulumi login – conectar-se ao armazenamento de estado, no sistema de arquivos local ou no Pulumi Cloud
2. pulumi stack select – criar ou selecionar a pilha a ser usada para o ambiente específico
3. pulumi config set – passar parâmetros de implantação como valores de configuração do Pulumi
4. pulumi up – executar a implantação para criar uma infraestrutura nova ou atualizar a infraestrutura existente no Azure

Durante o ponto de entrada da imagem principal, todos os arquivos de estado local existentes são extraídos para o contêiner e o diretório salvo na variável de ambiente $ADE_STORAGE. Para acessar o arquivo de estado existente, execute os seguintes comandos:

mkdir -p $ADE_STORAGE
export PULUMI_CONFIG_PASSPHRASE=
pulumi login file://$ADE_STORAGE

Para fazer login no Pulumi Cloud, defina seu token de acesso Pulumi como uma variável de ambiente e execute os seguintes comandos:

export PULUMI_ACCESS_TOKEN=YOUR_PULUMI_ACCESS_TOKEN
pulumi login

Todos os parâmetros definidos para o ambiente atual são armazenados na variável $ADE_OPERATION_PARAMETERS. Além disso, a região do Azure selecionada e o nome do grupo de recursos são passados em ADE_ENVIRONMENT_LOCATION e ADE_RESOURCE_GROUP_NAME, respectivamente. Para definir a configuração da pilha do Pulumi, execute os seguintes comandos:

# Create or select the stack for the current environment
pulumi stack select $ADE_ENVIRONMENT_NAME --create

# Store configuration values in durable storage
export PULUMI_CONFIG_FILE=$ADE_STORAGE/Pulumi.$ADE_ENVIRONMENT_NAME.yaml

# Set the Pulumi stack config
pulumi config set azure-native:location $ADE_ENVIRONMENT_LOCATION --config-file $PULUMI_CONFIG_FILE
pulumi config set resource-group-name $ADE_RESOURCE_GROUP_NAME --config-file $PULUMI_CONFIG_FILE
echo "$ADE_OPERATION_PARAMETERS" | jq -r 'to_entries|.[]|[.key, .value] | @tsv' |
  while IFS=$'\t' read -r key value; do
    pulumi config set $key $value --config-file $PULUMI_CONFIG_FILE
  done

Além disso, para utilizar privilégios do ADE para implantar a infraestrutura dentro de sua assinatura, seu script precisa usar a Identidade de Serviço Gerenciado (MSI) do ADE ao provisionar a infraestrutura usando o provedor Pulumi Azure Native ou Azure Classic. Se a sua implantação precisar de permissões especiais para ser concluída, como funções específicas, atribua essas permissões à identidade do tipo de ambiente do projeto que está sendo usada para a implantação do ambiente. O ADE define as variáveis de ambiente relevantes, como o cliente, o locatário e as IDs de assinatura dentro do ponto de entrada da imagem principal; portanto, execute os seguintes comandos para garantir que o provedor use a MSI do ADE:

export ARM_USE_MSI=true
export ARM_CLIENT_ID=$ADE_CLIENT_ID
export ARM_TENANT_ID=$ADE_TENANT_ID
export ARM_SUBSCRIPTION_ID=$ADE_SUBSCRIPTION_ID

Agora, você pode executar o comando pulumi up para executar a implantação:

pulumi up --refresh --yes --config-file $PULUMI_CONFIG_FILE

Durante o script de exclusão, você pode executar o comando destroy, conforme mostrado no exemplo a seguir:

pulumi destroy --refresh --yes --config-file $PULUMI_CONFIG_FILE

Por fim, para tornar as saídas de sua implantação carregadas e acessíveis ao acessar seu ambiente por meio da CLI do Azure, transforme o objeto de saída do Pulumi para o formato especificado pelo ADE por meio do pacote JQ. Defina o valor como a variável de ambiente $ADE_OUTPUTS, conforme mostrado no exemplo a seguir:

stackout=$(pulumi stack output --json | jq -r 'to_entries|.[]|{(.key): {type: "string", value: (.value)}}')
echo "{\"outputs\": ${stackout:-{\}}}" > $ADE_OUTPUTS

Criar a imagem personalizada

Você pode criar sua imagem usando o Docker CLI. Certifique-se de que o Docker Engine esteja 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 customImagee fazer upload com a tag version de1.0.0, você executaria:

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

Disponibilizar a imagem personalizada para o ADE

Para usar imagens personalizadas, é necessário armazená-las em um registro de contêiner. Você pode usar um registro de contêineres público ou um registro de contêineres privado. O Registro de Contêiner do Azure (ACR) é altamente recomendado, pois, devido à sua forte integração com o ADE, a imagem pode ser publicada sem permitir acesso público anônimo. Você deve criar sua imagem de contêiner personalizada e enviá-la para um registro de contêiner para disponibilizá-la para uso no ADE.

Também é possível armazenar a imagem em um registro de contêiner diferente, como o Docker Hub, mas, nesse caso, ela precisa ser acessível publicamente.

Cuidado

Armazenar sua imagem de contêiner em um registro com acesso de pull anônimo (não autenticado) torna-a publicamente acessível. Não faça isso se a imagem contiver informações confidenciais. Em vez disso, armazena-a no Registro de Contêiner do Azure (ACR) com acesso de pull anônimo desabilitado.

Para usar uma imagem personalizada armazenada no ACR, é necessário garantir que o ADE tenha as permissões adequadas para acessar a imagem. Ao criar uma instância do ACR, ela é segura por padrão e só permite o acesso de usuários autenticados.

Você pode usar o Pulumi para criar um Registro de Contêiner do Azure e publicar sua imagem nele. Confira o exemplo de Provisionamento/imagem personalizada para um projeto Pulumi autocontido que cria todos os recursos necessários em sua conta do Azure.

Selecione a guia apropriada para saber mais sobre cada abordagem.

Registro de privado

Use um registro privado com acesso seguro

Por padrão, o acesso para efetuar pull ou push de conteúdo de um Registro de Contêiner do Azure só está disponível para usuários autenticados. Você pode proteger ainda mais o acesso ao ACR, limitando o acesso de determinadas redes e atribuindo funções específicas.

Para criar uma instância do ACR, o que pode ser feito por meio da CLI do Azure, do portal do Azure, de comandos do PowerShell e outros, siga um dos inícios rápidos.

Limitar o acesso à rede

Para proteger o acesso à rede do ACR, você pode limitar o acesso às suas próprias redes ou desabilitar totalmente o acesso à rede pública. Se você limitar o acesso à rede, deverá habilitar a exceção de firewall Permitir que serviços Microsoft confiáveis acessem esse registro de contêiner.

Para desabilitar o acesso de redes públicas:

1. Crie uma instância do ACR ou use uma existente.

2. No portal do Azure, acesse o ACR que você quer configurar.

3. No menu à esquerda, em Configurações, selecione Rede.

4. Na página Rede, na guia Acesso público, em Acesso público à rede, selecione Desabilitado.

   

5. Em Exceção de firewall, verifique se a opção Permitir que serviços Microsoft confiáveis acessem esse registro de contêiner está selecionada e, em seguida, selecione Salvar.

   

Atribuir a função AcrPull

A criação de ambientes por meio de imagens de contêiner usa a infraestrutura do ADE, incluindo projetos e tipos de ambiente. Cada projeto tem um ou mais tipos de ambiente de projeto, que precisam de acesso de leitura à imagem do contêiner que define o ambiente a ser implantado. Para acessar as imagens no ACR com segurança, atribua a função AcrPull a cada tipo de ambiente de projeto.

Para atribuir a função AcrPull ao tipo de ambiente do projeto:

1. No portal do Azure, acesse o ACR que você quer configurar.

2. No menu à esquerda, selecione Controle de Acesso (IAM).

3. Selecione Adicionar>Adicionar atribuição de função.

4. Atribua a função a seguir. Para ver as etapas detalhadas, confira Atribuir funções do Azure usando o portal do Azure.

   Configuração	Valor
   Função	Selecione AcrPull.
   Atribuir acesso a	Selecione Usuário, grupo ou entidade de serviço.
   Membros	Insira o nome do tipo de ambiente de projeto que precisa acessar a imagem no contêiner.

   O tipo de ambiente do projeto é exibido como no exemplo a seguir:

   

Nessa configuração, o ADE usa a Identidade Gerenciada para o PET, seja o sistema atribuído ou o usuário atribuído.

Dica

Essa atribuição de função deve ser feita para cada tipo de ambiente de projeto. Ela pode ser automatizado por meio da CLI do Azure.

Quando estiver pronto para enviar sua imagem para o registro, execute o seguinte comando:

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

Registro público

Usar um registro público com pull anônimo

Para configurar o seu registo para ter a extração de imagem anónima ativada, execute os seguintes comandos no 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 sua imagem para o registro, execute o seguinte comando:

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

Conecte a imagem à definição do seu ambiente

Ao criar definições de ambiente para usar sua imagem personalizada em sua implantação, edite a propriedade runner 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.

Conteúdo relacionado

• Referência de imagem do corredor personalizado ADE CLI
• Referência de variáveis da CLI do ADE

• Repositório azure-deployment-environments do Pulumi