Provisionamento em camadas

O Azure Developer CLI (azd) suporta provisionamento em camadas, que pode usar para definir múltiplas camadas de provisionamento no seu azure.yaml ficheiro. Cada camada aponta para o seu próprio conjunto de modelos de Infraestrutura como Código (IaC). A CLI aprovisiona as camadas uma de cada vez, pela ordem das dependências entre elas. Também pode provisionar ou desmontar camadas individuais de forma independente.

Esta funcionalidade resolve cenários complexos de dependência onde recursos de uma camada dependem de recursos de outra camada. Em vez de misturar IaC com scripts de hook imperativos, o provisionamento em camadas garante que tudo permaneça declarativo.

Observação

O provisionamento em camadas é atualmente uma funcionalidade beta. Saiba mais sobre a estratégia de versionamento.

Quando usar provisionamento em camadas

Use provisionamento em camadas quando uma única azd provision implementação não consegue resolver todas as suas necessidades de infraestrutura numa só etapa. Considere usar o provisionamento em camadas quando:

  • Dependências circulares: Alguns recursos precisam de referenciar outros recursos que devem ser criados primeiro, como uma rede virtual que deve existir antes de um endpoint privado poder ser configurado.
  • A infraestrutura fundamental difere da infraestrutura de aplicações: geres recursos partilhados de rede, segurança ou identidade separadamente dos recursos por aplicação.
  • É necessária uma gestão independente do ciclo de vida: atualiza e desmonta diferentes componentes da infraestrutura em diferentes momentos. Por exemplo, uma camada de rede pode ter longa duração, enquanto uma camada de aplicação é frequentemente reimplantada.
  • Projetos monorepo com grupos de infraestrutura distintos: Um único repositório contém múltiplos serviços independentes (como um Event Hub, uma Container App e uma Function App), cada um com os seus próprios modelos de infraestrutura.

Configurar camadas no azure.yaml

Defina camadas sob a infra secção do seu azure.yaml ficheiro. Cada camada requer um name e um path apontando para o diretório que contém os modelos IaC dessa camada.

name: my-app
infra:
  layers:
    - name: networking
      path: ./infra/networking
    - name: application
      path: ./infra/application
services:
  api:
    project: ./src/api
    language: js
    host: containerapp

Importante

Ordem do processamento das camadas:azd provision Processa camadas com base nas suas dependências. Para camadas Bicep e provedores personalizados ou de extensão, azd infere dependências ao analisar os ficheiros de parâmetros (*.bicepparam e *.parameters.json) à procura de referências a variáveis de ambiente e a saídas de camadas, e ordena as camadas em conformidade, em vez de seguir estritamente a ordem indicada em azure.yaml. As camadas que não têm dependências inferidas nem declaradas são executadas pela ordem em que são listadas. azd down segue a ordem inversa correspondente, pelo que as camadas dependentes são removidas antes das camadas das quais dependem. Usa a dependsOn propriedade para declarar uma ordem que azd não pode inferir.

Propriedades da camada

Cada camada suporta as seguintes propriedades:

Propriedade Obrigatório Description
name Yes Um nome único para a camada. Use este nome ao direcionar uma camada específica com comandos.
path Yes O caminho relativo para o diretório que contém os templates IaC para esta camada.
module Não O nome do módulo dentro do diretório da camada. O padrão é main.
provider Não O fornecedor IaC para esta camada (bicep ou terraform). Herda da raiz infra.provider caso não a especifique.
dependsOn Não Os nomes das outras camadas de que esta camada depende. Utilize esta propriedade quando a ordem é importante, mas azd não consegue inferir a dependência a partir das referências aos parâmetros.

Importante

Quando defines infra.layers, não podes declarar outras propriedades na infra secção (path, module, deploymentStacks) ao nível raiz. Deve especificar todas as configurações de infraestrutura dentro de cada camada.

Estrutura do diretório

Um projeto típico que utiliza provisionamento em camadas pode ter a seguinte estrutura de diretórios:

my-app/
├── azure.yaml
├── infra/
│   ├── networking/
│   │   └── main.bicep
│   └── application/
│       └── main.bicep
└── src/
    └── api/
        └── ...

Cada diretório de camadas contém o seu próprio conjunto completo de modelos IaC, da mesma forma que o diretório de um projeto padrão.

Camadas de provisão e gestão

Podes provisionar todas as camadas ao mesmo tempo ou direcionar uma camada específica pelo nome. As secções seguintes descrevem comandos comuns para provisionar, desmontar e atualizar o estado da camada.

Provisionar todas as camadas

Execute o comando azd provision sem argumentos para aprovisionar todas as camadas:

azd provision

azd processa cada camada de cada vez, garantindo que uma camada fica concluída antes de qualquer camada que dependa dela começar. Para camadas Bicep e provedores personalizados ou de extensão, azd infere dependências a partir de referências a variáveis de ambiente e a saídas de camadas nos ficheiros *.bicepparam e *.parameters.json, pelo que a ordem de execução pode diferir da ordem indicada em azure.yaml. As camadas sem dependências inferidas ou declaradas são executadas pela ordem indicada. Este processo garante que os recursos dependentes existem antes de serem implementadas as camadas que os referenciam.

Provisionar uma camada específica

Para provisionar apenas uma camada específica, passe o nome da camada como argumento:

azd provision networking

Este comando implementa apenas os recursos definidos na networking camada. Provisionar uma camada específica é útil quando:

  • Estás a trabalhar numa única camada durante o desenvolvimento.
  • Precisas de atualizar uma camada sem redistribuir outras.
  • Estás a montar uma nova camada sobre a infraestrutura existente.

Desmonta todas as camadas

Executar azd down sem argumentos para remover recursos de todas as camadas. Quando existem múltiplas camadas, processa-as azdao contrário da ordem de provisionamento, de modo que os recursos dependentes são removidos antes dos recursos fundamentais de que dependem:

azd down

Desmonta uma camada específica

Para desmontar apenas uma camada específica, passe o nome da camada como argumento:

azd down application

Este comando remove apenas os recursos utilizados pela application camada, deixando as outras camadas intactas.

Atualizar estado do ambiente

Pode atualizar o estado do ambiente a partir de uma camada específica usando a --layer flag com azd env refresh:

azd env refresh --layer networking

Este comando atualiza as variáveis de ambiente e os resultados com base na implementação mais recente da camada especificada.

Exemplo: Monorepo com múltiplos serviços

O exemplo seguinte demonstra o provisionamento em camadas para um monorepo que contém um Event Hub, uma Container App a correr vários containers e uma Azure Function App:

name: logging-app
infra:
  layers:
    - name: eventhub
      path: ./infra/eventhub
    - name: aca
      path: ./infra/aca
    - name: functionapp
      path: ./infra/functionapp
services:
  functionapp:
    resourceName: ${site_name}
    language: dotnet
    project: ./src/function/functionapp.csproj
    host: appservice
    resourceGroup: ${rg_name}

A estrutura de diretórios correspondente:

logging-app/
├── azure.yaml
├── infra/
│   ├── eventhub/
│   │   └── main.bicep
│   ├── aca/
│   │   └── main.bicep
│   └── functionapp/
│       └── main.bicep
└── src/
    └── function/
        └── functionapp.csproj

Com esta configuração, pode:

  1. Fornecer apenas a infraestrutura do Event Hub: azd provision eventhub
  2. Provisione apenas a infraestrutura da App de Contêiner: azd provision aca
  3. Disponham tudo de forma ordenada: azd provision
  4. Desmonte apenas a camada da Aplicação de Funções: azd down functionapp

Exemplo: Camadas de base e de aplicação

Um padrão comum separa a infraestrutura partilhada ou fundamental da infraestrutura por aplicação:

name: my-app
infra:
  layers:
    - name: base
      path: ./infra/base
    - name: app
      path: ./infra/app
services:
  web:
    project: ./src/web
    language: js
    host: containerapp

A base camada cria recursos partilhados como redes, identidade e monitorização. A app camada cria os recursos específicos da aplicação (como um ambiente Container App e aplicações container) que referenciam os recursos base.

Durante o desenvolvimento, podes provisionar a camada base uma vez e iterar na camada de aplicação:

azd provision base
azd provision app
azd provision app  # re-provision only the app layer after changes

Exemplo: Fornecedores mistos de IaC

Cada camada pode usar um fornecedor IaC diferente. Por exemplo, pode usar o Bicep para redes e o Terraform para a camada de aplicação:

name: my-app
infra:
  layers:
    - name: networking
      path: ./infra/networking
      provider: bicep
    - name: application
      path: ./infra/application
      provider: terraform

Os fornecedores incorporados que não são Bicep (Terraform, Pulumi, ARM e o fornecedor de testes) são opacos à inferência de dependências, porque azd não conseguem analisar as suas entradas em busca de referências a outras camadas. Use uma propriedade explícita dependsOn sempre que a ordem entre essas camadas, ou entre essas camadas e outras camadas, importe:

name: my-app
infra:
  layers:
    - name: networking
      path: ./infra/networking
      provider: bicep
    - name: application
      path: ./infra/application
      provider: terraform
      dependsOn:
        - networking

Considerações e limitações

  • Quando provisionas todas as camadas, azd processa-as uma de cada vez com base nas suas dependências. Para camadas Bicep e provedores personalizados ou de extensão, azd infere dependências a partir de referências a variáveis de ambiente e de referências à saída da camada nos ficheiros *.bicepparam e *.parameters.json. Camadas sem dependências inferidas ou declaradas correm na ordem que defines.
  • Os fornecedores incorporados que não são Bicep (Terraform, Pulumi, ARM e o fornecedor de testes) são opacos para inferência de dependências. Utilize uma propriedade explícita dependsOn quando a ordem dessas camadas for importante.
  • A especificação explícita dependsOn também é necessária quando a ordem é importante, mas azd não consegue inferir a dependência a partir de referências aos parâmetros. Por exemplo, use dependsOn quando o hook de uma camada postprovision gera um valor que outra camada consome, porque os valores gerados pelo hook não aparecem como referências de saída nos ficheiros *.bicepparam ou *.parameters.json.
  • Quando desmontas todas as camadas, azd processa-as ao contrário da ordem de provisionamento.
    • Se múltiplas camadas implementarem recursos no mesmo grupo de recursos Azure e usares o comportamento padrão de eliminação baseado em grupos de recursos, os recursos partilhados podem ser eliminados ao executar o azd.
    • Para permitir a monitorização e eliminação independentes da infraestrutura em camadas, ative as pilhas de implementação executando o comando azd config set alpha.deployment.stacks on.
  • Não podes usar o --preview flag ao provisionar várias camadas ao mesmo tempo. Especifique um <layer> nome para usar o modo de pré-visualização.
  • As camadas operam de forma independente em termos de IaC. Para referenciar as saídas de uma camada em outra camada, use variáveis de ambiente que azd são definidas após a implementação de cada camada. Referenciar essas variáveis de ambiente a partir de um *.bicepparam ficheiro ou *.parameters.json permite azd também inferir a ordem entre as camadas.
  • Todas as funcionalidades padrão azd de provisionamento (cache de estado de implantação, ganchos, parâmetros, Bicep ou Terraform) funcionam dentro de cada camada individual.
    • Ganchos ao nível de comando (por exemplo, preprovision, postprovision) são invocados uma vez por camada. Quando múltiplas camadas são definidas, os ganchos correm para cada camada na ordem em que as camadas são processadas.

Próximos passos

Azure.yaml Schema Reference

  • Última atualização a