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

Os Ambientes de Implantação do Azure (ADE) dão suporte a um modelo de extensibilidade que permite configurar sua definição de ambiente com sua estrutura de modelo IaC preferida. Você pode armazenar imagens personalizadas em um registro de contêiner como o Azure Container Registry (ACR) ou o Docker Hub e, em seguida, fazer referência a elas em suas definições de ambiente para implantar ambientes.

Neste artigo, você aprenderá a criar imagens de contêiner Bicep personalizadas para implantar suas definições de ambiente no ADE. Você aprende a usar uma imagem padrão fornecida pela Microsoft ou como configurar uma infraestrutura de provisionamento de imagem personalizada usando a estrutura Bicep Infrastructure-as-Code (IaC).

Neste artigo, você aprenderá a criar imagens de contêiner personalizadas do Terraform para criar ambientes de implantação com os Ambientes de Implantação do Azure (ADE). Você aprende a configurar uma imagem personalizada para provisionar a infraestrutura usando a estrutura Terraform Infrastructure-as-Code (IaC).

Neste artigo, você aprenderá a utilizar o Pulumi para implantações no ADE. Você aprende como usar uma imagem padrão fornecida pelo Pulumi ou como configurar uma imagem personalizada para provisionar a infraestrutura usando a estrutura Pulumi Infrastructure-as-Code (IaC).

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:

• Usar uma imagem de contêiner padrão Para cenários simples, use a imagem de contêiner ARM-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.

Usar uma imagem de contêiner padrão

O ADE dá suporte ao Azure Resource Manager (ARM) e ao Bicep sem exigir nenhuma configuração extra. Você pode criar uma definição de ambiente que implanta 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 runner propriedade especifica o local da imagem de contêiner que você deseja usar. Para usar a imagem padrão publicada no Microsoft Artifact Registry, use os respetivos identificadores runner.

O exemplo a seguir mostra um runner que faz referência à imagem de 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

Você pode ver a imagem do contêiner 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 contentor 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 criar uma imagem com base na imagem padrão do ADE e enviá-la por push para o registro do 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 cria uma imagem e a envia por push para o Azure Container Registry (ACR) especificado no repositório 'ade' e na tag 'mais recente'. Esse script requer seu nome do Registro e diretório para sua imagem personalizada, tenha a CLI do Azure e o Docker Desktop instalados e em suas variáveis PATH e requer 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 rapidamente essa imagem de exemplo para um Registro de Contêiner do Azure, você precisará:

• Transforme este repositório na 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 nome de tag, você pode 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 seu arquivo de manifesto Conecte a imagem à sua 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. 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

Usar imagens de contêiner com o 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.
• Crie uma imagem de contêiner personalizada aproveitando um fluxo de trabalho do GitHub: use o fluxo de trabalho publicado do GitHub a partir do repositório Aproveitando o modelo de extensibilidade do ADE com Terraform.
• Criar uma imagem de contêiner personalizada manualmente: Crie uma imagem personalizada específica do Terraform manualmente

Criar uma imagem de contentor 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 criar uma imagem com base na imagem padrão do ADE e enviá-la para o registro do contêiner usando um script de início rápido fornecido pela Microsoft. Você pode encontrar o script nos Ambientes de implantação com o repositório 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 rapidamente essa imagem de exemplo para um Registro de Contêiner do Azure, você precisará:

• Transforme este repositório na 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 cria uma imagem e a envia por push para o Azure Container Registry (ACR) especificado no repositório 'ade' e na tag 'mais recente'. Esse script requer seu nome do Registro e diretório para sua imagem personalizada, tenha a CLI do Azure e o Docker Desktop instalados e em suas variáveis PATH e requer 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 nome de tag, você pode 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 seu arquivo de manifesto Conecte a imagem à sua 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, você pode usar o fluxo de trabalho publicado do GitHub a partir do repositório Aproveitando o modelo de extensibilidade do ADE com Terraform.

Para usar o fluxo de trabalho, você precisará:

• Fork este repositório em sua conta pessoal
• Permita que as Ações do GitHub se conectem ao Azure por meio das credenciais federadas de um aplicativo Microsoft Entra ID por meio do OIDC. Pode encontrar mais documentação sobre este processo aqui
• Configure os Segredos do Repositório para o repositório que contém o ID do aplicativo Microsoft Entra ID definido como AZURE_CLIENT_ID, o ID da assinatura definido como AZURE_SUBSCRIPTION_ID e o ID do locatário definido como AZURE_TENANT_ID
• Configure Variáveis de Repositório para seu repositório contendo seu nome pessoal do Azure Container Registry (ACR) como REGISTRY_NAME, seu nome de repositório preferido como REPOSITORY_NAME e sua tag preferida como TAG para a imagem criada. Você pode modificar suas variáveis entre execuções de fluxo de trabalho para enviar a imagem gerada para diferentes registros, repositórios e tags.

Execute o fluxo de trabalho navegando até a guia Ações no repositório bifurcado e selecionando o fluxo de trabalho que 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 seu arquivo de manifesto Conecte a imagem à sua 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. Você pode criar imagens personalizadas com base nas imagens 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.

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 por push uma imagem para um Registro de Contêiner do Azure (ACR). Você pode fazer referência a um link de imagem ACR fornecido dentro de 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 estes passos:

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

1. Crie 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 shell scripts para implantar e excluir ambientes usando modelos Terraform IaC. Este código de exemplo ajuda você a criar sua própria imagem de contêiner.

2. Instale os pacotes necessários Nesta etapa, você instala todos os pacotes necessários em sua imagem, incluindo o Terraform. Você pode instalar a CLI do Terraform 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 1.7.5 da CLI 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

Gorjeta

Você pode obter o URL de download para sua versão preferida da CLI Terraform das versões Hashicorp.

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 de scripts para Terraform.

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 que usam a CLI do Terraform

Há três etapas para implantar a infraestrutura via Terraform:

1. terraform init - inicializa a CLI Terraform para executar ações dentro do diretório de trabalho
2. terraform plan- desenvolve um plano baseado nos arquivos e variáveis de infraestrutura Terraform recebidos, e quaisquer 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 nova infraestrutura ou atualizar a infraestrutura existente no Azure

Durante o ponto de entrada da imagem principal, todos os arquivos de estado existentes são puxados para o contêiner e o diretório salvo na variável $ADE_STORAGEde ambiente . Além disso, quaisquer parâmetros definidos para o ambiente atual armazenados sob a variável $ADE_OPERATION_PARAMETERS. Para acessar o arquivo de estado existente e definir suas variáveis dentro de 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 do ADE para implantar a infraestrutura dentro de sua assinatura, seu script precisa usar a Identidade de Serviço Gerenciado (MSI) ao provisionar a infraestrutura usando o provedor Terraform AzureRM. Se a implantação precisar de permissões especiais para concluir a implantação, como funções específicas, atribua essas permissões à identidade do tipo de ambiente do projeto que está sendo usado para a implantação do ambiente. O ADE define as variáveis de ambiente relevantes, como as IDs de cliente, locatário e assinatura no ponto de entrada da imagem principal, portanto, execute os seguintes comandos para garantir que o provedor use o ADE MSI:

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

Se você tiver outras variáveis para referência em seu modelo que não estejam especificadas nos parâmetros do seu ambiente, defina as variáveis de ambiente usando o prefixo TF_VAR. Uma lista de variáveis de ambiente ADE fornecidas é fornecida referência de variáveis CLI do Ambiente de Implantação do Azure. Um exemplo desses comandos poderia 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ê pode 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, você pode adicionar o sinalizador destroy à geração do plano para 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

Finalmente, 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 de 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 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

Use uma imagem de contêiner padrão fornecida pela Pulumi

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

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

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. Você pode criar imagens personalizadas com base nas imagens padrão Pulumi e personalizá-las para atender às suas necessidades. Depois de concluir a personalização da imagem, você deve criar a imagem e enviá-la por push para o registro do contêiner.

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 que usam a CLI do Pulumi.

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

Você pode instalar a CLI do 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 do 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 programas Pulumi, talvez seja necessário instalar um ou mais tempos de execução correspondentes. O tempo de execução do Python já está disponível na imagem base.

Aqui está um exemplo de instalação do Node.js e do 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 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.

Há quatro etapas para implantar a infraestrutura via Pulumi:

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

Durante o ponto de entrada da imagem principal, todos os arquivos de estado local existentes são puxados para o contêiner e o diretório salvo na variável $ADE_STORAGEde ambiente . 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 entrar 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 e ADE_ENVIRONMENT_LOCATIONADE_RESOURCE_GROUP_NAME respectivamente. Para definir sua configuração de pilha 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 os privilégios do ADE para implantar a infraestrutura dentro de sua assinatura, seu script precisa usar o ADE Managed Service Identity (MSI) ao provisionar a infraestrutura usando o provedor Pulumi Azure Native ou Azure Classic. Se a implantação precisar de permissões especiais para concluir a implantação, como funções específicas, atribua essas permissões à identidade do tipo de ambiente do projeto que está sendo usado para a implantação do ambiente. O ADE define as variáveis de ambiente relevantes, como as IDs de cliente, locatário e assinatura no ponto de entrada da imagem principal, portanto, execute os seguintes comandos para garantir que o provedor use o ADE MSI:

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 pulumi up comando para executar a implantação:

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

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

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

Finalmente, 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 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

Disponibilizar a imagem personalizada para o ADE

Para usar imagens personalizadas, você precisa armazená-las em um registro de contêiner. Você pode usar um registro de contêiner público ou um registro de contêiner privado. O Azure Container Registry (ACR) é altamente recomendado, devido à sua forte integração com o ADE, a imagem pode ser publicada sem permitir acesso pull anônimo público. Você deve criar sua imagem de contêiner personalizada e enviá-la por push 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.

Atenção

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

Para usar uma imagem personalizada armazenada no ACR, você precisa garantir que o ADE tenha as permissões apropriadas para acessar sua imagem. Quando você cria uma instância ACR, ela é segura por padrão e só permite que usuários autenticados obtenham acesso.

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

Selecione a guia apropriada para saber mais sobre cada abordagem.

Registo privado

Utilizar um registo privado com acesso seguro

Por padrão, o acesso para receber ou enviar conteúdo por push 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, dos comandos do PowerShell e muito mais, siga um dos inícios rápidos.

Limitar o acesso à rede

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

Para desativar o acesso de redes públicas:

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

2. No portal do Azure, vá para o ACR que você deseja configurar.

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

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

   

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

   

Atribuir a função AcrPull

A criação de ambientes usando imagens de contêiner usa a infraestrutura 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 de contêiner que define o ambiente a ser implantado. Para acessar as imagens dentro do seu 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, vá para o ACR que você deseja configurar.

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

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

4. Atribua a seguinte função. Para obter os passos detalhados, veja o artigo Atribuir funções do Azure com o portal do Azure.

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

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

   

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

Gorjeta

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

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}

Registo público

Usar um registro público com pull anônimo

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.

Conteúdos relacionados

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

• Repositório azure-deployment-environments da Pulumi