Configurar uma imagem de contêiner para executar implantações com o Terraform
Neste artigo, você aprenderá a criar imagens de contêiner personalizadas do Terraform para implantar suas definições de ambiente nos 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).
Uma definição de ambiente compreende pelo menos dois arquivos: um arquivo de modelo, como main.tf, e um arquivo de manifesto chamado environment.yaml. Você usa um contêiner para implantar a definição de ambiente que usa o Terraform.
O modelo de extensibilidade ADE permite criar imagens de contêiner personalizadas para usar com suas definições de ambiente. Usando o modelo de extensibilidade, você pode criar suas próprias imagens de contêiner personalizadas e armazená-las em um registro de contêiner como o DockerHub. Em seguida, você pode fazer referência a essas imagens em suas definições de ambiente para implantar seus ambientes.
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.
Criar uma imagem de contêiner Terraform personalizada
A criação de uma imagem de contêiner personalizada permite que você personalize suas implantações 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.
Criar e personalizar uma imagem de contêiner com o Docker
Neste exemplo, você aprenderá a criar uma imagem do Docker para utilizar implantações do ADE e acessar a CLI do ADE, baseando sua imagem em uma das imagens criadas pelo ADE.
A CLI ADE é uma ferramenta que permite criar imagens personalizadas usando imagens base ADE. Você pode usar a CLI do ADE para personalizar suas implantações e exclusões para se adequar ao seu fluxo de trabalho. A CLI ADE está pré-instalada nas imagens de exemplo. Para saber mais sobre a CLI do ADE, consulte a referência CLI Custom Runner Image.
Para criar uma imagem configurada para o ADE, siga estes passos:
- Baseie sua imagem em uma imagem de amostra criada pelo ADE ou na imagem de sua escolha usando a instrução FROM.
- Instale todos os pacotes necessários para sua imagem usando a instrução RUN.
- Crie uma pasta de scripts no mesmo nível do seu Dockerfile, armazene seus arquivos deploy.sh e delete.sh dentro dela e certifique-se de que esses scripts sejam detetáveis e executáveis dentro do contêiner criado. Esta etapa é necessária para que sua implantação funcione usando a imagem principal do ADE.
Selecione uma imagem de contêiner de exemplo usando a instrução FROM
Inclua uma instrução FROM em um DockerFile criado para sua nova imagem apontando para uma imagem de exemplo hospedada no Microsoft Artifact Registry.
Aqui está um exemplo de instrução FROM, fazendo referência à imagem principal de exemplo:
FROM mcr.microsoft.com/deployment-environments/runners/core:latest
Esta declaração extrai a imagem principal publicada mais recentemente e torna-a uma base para a sua imagem personalizada.
Instalar o Terraform em um Dockerfile
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.
As imagens de exemplo do ADE são baseadas na imagem da CLI do Azure e têm os pacotes ADE CLI e JQ pré-instalados. Você pode saber mais sobre a CLI do Azure e o pacote JQ.
Para instalar mais pacotes que você precisa em sua imagem, use a instrução RUN.
Executar scripts de shell de operação
Nas imagens de exemplo, as operações são determinadas e executadas com base no nome da operação. Atualmente, os dois nomes de operação suportados são deploy e delete.
Para configurar sua imagem personalizada para utilizar essa estrutura, especifique uma pasta no nível dos scripts nomeados do Dockerfile e especifique dois arquivos, deploy.sh e delete.sh. O script de shell de implantação é executado quando seu ambiente é criado ou reimplantado e o script de shell de exclusão é executado quando seu ambiente é excluído. Você pode ver exemplos de shell scripts no repositório na pasta Runner-Images para a imagem ARM-Bicep .
Para garantir que esses shell scripts sejam executáveis, adicione as seguintes linhas ao seu Dockerfile:
COPY scripts/* /scripts/
RUN find /scripts/ -type f -iname "*.sh" -exec dos2unix '{}' '+'
RUN find /scripts/ -type f -iname "*.sh" -exec chmod +x {} \;
Crie scripts de shell de operação para usar a CLI do Terraform
Há três etapas para implantar a infraestrutura via Terraform:
terraform init- inicializa a CLI Terraform para executar ações dentro do diretório de trabalhoterraform 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 .tfterraform 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:
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
Tornar a imagem personalizada acessível ao ADE
Você deve criar sua imagem do Docker e enviá-la por push para o registro do contêiner para disponibilizá-la para uso no ADE. Você pode criar sua imagem usando a CLI do Docker ou usando um script fornecido pelo ADE.
Selecione a guia apropriada para saber mais sobre cada abordagem.
Antes de criar a imagem a ser enviada por push para o registro, verifique se o mecanismo do Docker está instalado no computador. Em seguida, navegue até o diretório do seu Dockerfile e execute o seguinte comando:
docker build . -t {YOUR_REGISTRY}.azurecr.io/{YOUR_REPOSITORY}:{YOUR_TAG}
Por exemplo, se você quiser salvar sua imagem em um repositório dentro do seu registro chamado customImage, e carregar com a versão da tag do 1.0.0, você deve executar:
docker build . -t {YOUR_REGISTRY}.azurecr.io/customImage:1.0.0
Enviar a imagem do Docker para um registro
Para usar imagens personalizadas, você precisa configurar um registro de imagem acessível publicamente com o pull de imagem anônimo habilitado. Dessa forma, os Ambientes de Implantação do Azure podem acessar sua imagem personalizada para executar em nosso contêiner.
O Registro de Contêiner do Azure é uma oferta do Azure que armazena imagens de contêiner e artefatos semelhantes.
Para criar um registro, o que pode ser feito por meio da CLI do Azure, do portal do Azure, dos comandos do PowerShell e muito mais, siga um dos inícios rápidos.
Para configurar seu registro para ter o pull de imagem anônimo habilitado, execute os seguintes comandos na CLI do Azure:
az login
az acr login -n {YOUR_REGISTRY}
az acr update -n {YOUR_REGISTRY} --public-network-enabled true
az acr update -n {YOUR_REGISTRY} --anonymous-pull-enabled true
Quando estiver pronto para enviar a imagem para o Registro, execute o seguinte comando:
docker push {YOUR_REGISTRY}.azurecr.io/{YOUR_IMAGE_LOCATION}:{YOUR_TAG}
Conecte a imagem à sua definição de ambiente
Ao criar definições de ambiente para usar sua imagem personalizada em sua implantação, edite a runner propriedade no arquivo de manifesto (environment.yaml ou manifest.yaml).
runner: "{YOUR_REGISTRY}.azurecr.io/{YOUR_REPOSITORY}:{YOUR_TAG}"
Acessar logs de operação e detalhes de erro
O ADE armazena detalhes de erro para uma implantação com falha no arquivo $ADE_ERROR_LOG dentro do contêiner.
Para solucionar problemas de uma implantação com falha:
Faça login no Portal do desenvolvedor.
Identifique o ambiente que falhou na implantação e selecione Ver detalhes.
Analise os detalhes do erro na seção Detalhes do erro.
Além disso, você pode usar a CLI do Azure para exibir os detalhes de erro de um ambiente usando o seguinte comando:
az devcenter dev environment show --environment-name {YOUR_ENVIRONMENT_NAME} --project {YOUR_PROJECT_NAME}
Para exibir os logs de operação para uma implantação ou exclusão de ambiente, use a CLI do Azure para recuperar a operação mais recente para seu ambiente e, em seguida, exiba os logs dessa ID de operação.
# Get list of operations on the environment, choose the latest operation
az devcenter dev environment list-operation --environment-name {YOUR_ENVIRONMENT_NAME} --project {YOUR_PROJECT_NAME}
# Using the latest operation ID, view the operation logs
az devcenter dev environment show-logs-by-operation --environment-name {YOUR_ENVIRONMENT_NAME} --project {YOUR_PROJECT_NAME} --operation-id {LATEST_OPERATION_ID}
Conteúdos relacionados
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários