Caminhos de migração entre fornecedores Azure, AzureRM e AzAPI Terraform

Terraform permite a definição, visualização e implantação de infraestrutura em nuvem. Usando Terraform, você cria arquivos de configuração usando a sintaxe HCL. A sintaxe HCL permite especificar o provedor de nuvem - como o Azure - e os elementos que compõem sua infraestrutura de nuvem. Depois de criares os ficheiros de configuração, crias um plano de execução que te permite pré-visualizar as alterações da infraestrutura antes de serem implementadas. Depois de verificares as alterações, aplicas o plano de execução para implementar a infraestrutura.

Existem várias ferramentas e fluxos de trabalho para transitar entre a infraestrutura do Azure e o Terraform, ou entre os fornecedores AzureRM e AzAPI Terraform. O caminho certo depende do teu ponto de partida e objetivo.

As ferramentas principais incluem aztfexport (exporta recursos Azure existentes para configuração e estado do Terraform) e aztfmigrate (converte configurações do Terraform entre os fornecedores AzureRM e AzAPI).

Use a tabela seguinte para identificar qual a secção aplicável ao seu cenário:

Para orientação sobre qual fornecedor deve ser o principal para novos projetos, consulte Escolha entre fornecedores AzureRM e AzAPI Terraform.

Exportar recursos Azure existentes para Terraform

Azure Export for Terraform (aztfexport) coloca os recursos de Azure existentes sob gestão do Terraform ao gerar configuração HCL e estado do Terraform. Suporta tanto AzureRM como AzAPI como alvos de saída.

Use este caminho quando: Tem recursos de Azure existentes que ainda não são geridos pela Terraform e quer importá-los.

Métodos de exportação

Escolha o método de exportação que melhor se adapte ao seu fluxo de trabalho:

• CLI: Use o aztfexport binário diretamente. Consulte a visão geral do Azure Export para Terraform para a instalação e referência de comandos CLI.
• Extensão VS Code: Use a extensão Microsoft Terraform VS Code para uma experiência de exportação guiada com filtragem de recursos e seleção de fornecedores.
• Portal do Azure: Exportar recursos diretamente do Portal do Azure sem ferramentas locais. Consulte Exportar recursos no portal Azure.

Para inicios rápidos detalhados e cenários avançados, veja:

• Exporta os teus primeiros recursos
• Exportar recursos para código HCL
• Cenários avançados de exportação

Exportar recursos no portal Azure

A integração do portal Azure permite-lhe exportar recursos sem instalar ferramentas adicionais:

1. Navegue para ao recurso no portal do Azure.
2. Localiza a opção Exportar para Terraform (a localização exata depende do tipo de recurso).
3. Siga as instruções para selecionar o fornecedor de saída (AzureRM ou AzAPI) e exportar o âmbito.
4. Descarregue a configuração e o ficheiro de estado gerados no Terraform.
5. Reveja a saída e execute terraform plan para confirmar que não há desvio.

Para orientações passo a passo, consulte Exportar um recurso no portal Azure.

Autor de recursos AzAPI a partir do ARM JSON

Se tiver um template ARM, uma definição de recurso do portal Azure ou uma resposta bruta da API REST e quiser gerar um bloco correspondente azapi_resource, a extensão Microsoft Terraform VS Code pode convertê-lo automaticamente.

Use este caminho quando: Estiver a criar novos recursos AzAPI e tiver uma definição JSON existente (modelo ARM, exportação do portal, resposta da API) como ponto de partida.

A extensão converte as propriedades JSON para o body formato de atributos e infere o type e api-version. Para passos e exemplos detalhados, consulte Paste ARM JSON como configuração AzAPI no guia de extensão do VS Code.

Migre os recursos AzAPI para AzureRM com aztfmigrate

aztfmigrate migra blocos existentes azapi_resource numa configuração Terraform para os seus tipos de recursos equivalentes azurerm_*. Atualiza tanto os ficheiros HCL (HashiCorp Configuration Language) como o ficheiro de estado do Terraform sem recriar os recursos Azure subjacentes.

Use este caminho quando: A sua equipa gere recursos com AzAPI e um recurso que está a usar foi entretanto adicionado ao fornecedor AzureRM com total suporte, e quiser consolidar no AzureRM.

Pré-requisitos

• Uma configuração Terraform existente com azapi_resource blocos que queres migrar.
• O aztfmigrate binário instalado e no seu PATH. Descarregue a partir da página de lançamentos do aztfmigrate.

• Subscrição do Azure: Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.

Planear a migração

1. Navegue até ao diretório que contém a sua configuração do Terraform.

2. Autenticar no Azure:

   az login
   az account set --subscription <subscription_id>
   

3. Execute aztfmigrate plan para identificar quais recursos podem ser migrados para o AzureRM:

   aztfmigrate plan
   

   A saída lista cada azapi_resource bloco, indicando se corresponde a um tipo de recurso AzureRM suportado. Recursos que usam versões da API de pré-visualização ou tipos de recursos que ainda não estão no AzureRM são listados como não migráveis e permanecem como azapi_resource blocos.

4. Revise o resultado do plano e confirme que os mapeamentos estão corretos antes de prosseguir.

Executar a migração

1. Corra aztfmigrate migrate para aplicar as alterações:

   aztfmigrate migrate
   

   aztfmigrate:

   • Substitui azapi_resource blocos nos teus .tf ficheiros por blocos equivalentes azurerm_* .
   • Atualiza o ficheiro de estado para refletir os novos endereços de recursos e o esquema.

2. Inicialize o Terraform para descarregar quaisquer versões atualizadas do fornecedor:

   Execute terraform init para inicializar a implantação do Terraform. Este comando descarrega o fornecedor Azure necessário para gerir os seus recursos Azure.

   terraform init -upgrade
   

   Pontos principais:

   • O -upgrade parâmetro atualiza os plugins do fornecedor necessários para a versão mais recente que cumpra as restrições de versão da configuração.

3. Execute terraform plan para validar que a configuração e o estado estejam alinhados com a infraestrutura implementada:

   terraform plan
   

   O plano não deve apresentar alterações. Se surgirem diferenças, reveja o diferencial e ajuste a configuração migrada antes de aplicar.

Limpeza pós-migração

Depois de confirmar um plano sem falhas:

• Remova o fornecedor azapi de required_providers se não restarem blocos de recursos AzAPI.
• Atualize qualquer bloco output ou locals que faça referência a atributos específicos do AzAPI.
• Execute o comando terraform apply para aplicar qualquer desvio legítimo, tais como os padrões normalizados introduzidos pelo AzureRM.

Migre recursos AzureRM para AzAPI

Para converter uma configuração existente do AzureRM para usar AzAPI, use a extensão Microsoft Terraform VS Code, que inclui ferramentas para gerar equivalentes AzAPI para blocos de recursos azurerm_*.

Use este caminho quando: estiver a converter um módulo ou configuração Terraform do AzureRM para o AzAPI e precisar de ajuda do editor na conversão.

Para instruções passo a passo, ações de código e orientações de migração de estado, consulte o guia de extensão do VS Code.

Quando não migrar

Considere manter os recursos onde estão quando:

• O recurso está em pré-visualização ou usa uma versão da API de pré-visualização ainda não no AzureRM — mantenha-o no AzAPI.
• A sua equipa usa o AzAPI como fornecedor principal — adicione novos recursos exclusivos do AzureRM com o AzAPI em vez de introduzir um segundo fornecedor principal.
• A representação do AzureRM introduz um desvio indesejado em relação aos valores padrão normalizados — avalie o impacto antes da migração.
• A complexidade da migração de estados é elevada — para configurações grandes, avalie se o risco operacional da manipulação do estado supera o benefício de mudar de fornecedor.

Passos seguintes