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

Use uma imagem de contêiner de amostra

O ADE suporta ARM e Bicep sem exigir 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. O ADE então usa a imagem de contêiner ARM-Bicep de amostra 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 de amostra 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 de amostra:

    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 de exemplo do contêiner Bicep no repositório de exemplos 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.

Use uma imagem personalizada para configurar uma imagem do Terraform.

Use uma imagem de contêiner de amostra fornecida por 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.

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

Alternativamente, você pode criar um fork do repositório Aproveitando o Modelo de Extensibilidade do ADE com Terraform para criar e enviar a imagem do Terraform para um ACR fornecido.

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

1. Crie uma imagem personalizada com base em uma imagem de amostra.
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.

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

1. Crie uma imagem personalizada com base em uma imagem de amostra.
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.

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

1. Crie uma imagem personalizada com base em uma imagem de amostra.
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.

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

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

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

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

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:

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

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