Visão geral dos modelos do Azure Developer CLI

Um modelo do Azure Developer CLI (azd) é um repositório de código que segue as convenções de azd. Ele combina configuração de projeto, infraestrutura como código e fonte de aplicativo opcional para que você possa criar ambientes e implantações repetíveis Azure.

Os modelos podem dar suporte a diferentes tipos de projeto, incluindo:

• Um aplicativo completo com um ou mais serviços implantáveis.
• Uma solução somente de infraestrutura sem código de aplicativo.
• Um ponto de partida reutilizável que outro desenvolvedor pode inicializar e estender.
• Um projeto existente com o qual você se prepara para provisionamento e implantação.azd

Este artigo explica a estrutura de um modelo e como os azd comandos usam seus arquivos.

Por que usar um modelo?

Um modelo captura as decisões necessárias para executar um projeto no Azure. Dependendo do projeto, ele pode definir:

• Azure recursos e sua configuração.
• Serviços de aplicação implantáveis e instruções de empacotamento.
• Conexões entre serviços de aplicativos e recursos de Azure.
• Saídas e parâmetros específicos do ambiente.
• Desenvolvimento local, integração contínua e configuração de entrega contínua.

Como a configuração é armazenada com o projeto, as equipes podem examinar as alterações no controle do código-fonte e criar ambientes de desenvolvimento, teste e produção consistentes.

Como azd usa um modelo

Os arquivos em um modelo dão suporte a diferentes estágios do azd fluxo de trabalho:

• azd init inicializa o projeto e cria um azd ambiente. Ele também pode usar GitHub Copilot para gerar um modelo inicial ou copiar um modelo existente.
• azd provisionavalia as definições de infraestrutura e cria ou atualiza Azure recursos.
• azd package prepara serviços de aplicativo prontos para implantação de acordo com azure.yaml.
• azd deployassocia cada serviço ao host Azure e implanta o pacote de aplicativos.
• azd up executa os estágios de provisionamento, empacotamento e implantação como um fluxo de trabalho combinado.

Os arquivos de modelo permanecem arquivos de origem regulares durante todo esse processo. Você pode revisá-los, editá-los e versioná-los junto com o restante do projeto.

Explorar a estrutura de modelo da CLI do desenvolvedor do Azure

azd os modelos são repositórios de código padrão com ativos de configuração e infraestrutura extras. A maioria dos modelos usa a seguinte estrutura:

• azure.yaml arquivo - Define o projeto e mapeia diretórios de código-fonte implantáveis para recursos do Azure.
• infra pasta – Contém os arquivos de infraestrutura como código do Bicep ou do Terraform que criam os recursos de Azure.
• src pasta – geralmente contém o código-fonte do aplicativo implantável. Modelos somente de infraestrutura podem omitir a origem do aplicativo e os modelos de aplicativo podem usar outros nomes de diretório de origem.
• .azure pasta – Contém ambientes locais e valores criados por azd. Essa pasta é o estado do projeto local e normalmente não é compartilhada como parte de um modelo reutilizável.

Por exemplo, um modelo comum azd pode corresponder à seguinte estrutura de pastas:

contoso-project/
├── azure.yaml                 # azd project and service configuration
├── infra/
│   ├── main.bicep            # Infrastructure entry point
│   └── main.parameters.json  # Maps azd values to Bicep parameters
├── src/                      # Optional application source
│   ├── api/
│   └── web/
├── .github/workflows/        # Optional GitHub Actions pipelines
└── .azure/                   # Local environment state; don't distribute

Opcionalmente, os modelos do azd incluem uma ou mais destas pastas:

• .github pasta – Contém arquivos de fluxo de trabalho de CI/CD para GitHub Actions.
• .azdo pasta - Se você decidir usar o Azure Pipelines para CI/CD, defina os arquivos de configuração de fluxo de trabalho nesta pasta.
• .devcontainer pasta – Define um ambiente de contêiner de desenvolvimento para o projeto.

O diagrama a seguir mostra como os ativos de modelo primário funcionam juntos:

flowchart LR
AZ[azure.yaml] -->|Defines services| SRC[Application source]
AZ -->|Selects provider and path| INFRA[Infrastructure as code]
INFRA -->|Provisions| RES[Azure resources]
INFRA -->|Exports values| ENV[azd environment]
ENV -->|Configures| SRC
AZ -->|Maps services to| RES

Ativos obrigatórios e opcionais

A estrutura exata varia de acordo com o projeto, mas a maioria dos modelos usa os ativos a seguir.

azure.yaml

O azure.yaml arquivo é o arquivo de configuração de projeto primário. Ele define o nome do projeto e pode definir serviços implantáveis, provedores de infraestrutura, ganchos, fluxos de trabalho e outros comportamentos azd .

Para um serviço de aplicativo, azure.yaml geralmente identifica:

• O caminho para a origem do aplicativo.
• A linguagem de programação ou a estratégia de empacotamento.
• O serviço Azure que hospeda o aplicativo.
• Configurações de compilação, implantação, contêiner ou Kubernetes.

Modelos somente de infraestrutura podem omitir serviços de aplicativo. Para obter o modelo de configuração completo, consulte o azure.yaml esquema.

O exemplo a seguir define dois serviços de aplicativo. Os nomes de serviço, caminhos de origem, idiomas e destinos de hospedagem informam azd o que empacotar e onde implantá-lo:

name: store
services:
  api:
    project: ./src/api
    language: js
    host: containerapp
  web:
    project: ./src/web
    language: js
    host: staticwebapp

Infraestrutura como código

A maioria dos modelos contém um infra diretório com arquivos Bicep ou Terraform. Esses arquivos definem os recursos Azure, atribuições de função, rede, configurações de aplicativo e saídas de implantação exigidas pelo projeto.

Para o provedor padrão do Bicep, azd normalmente usa infra/main.bicep como ponto de entrada da implantação e infra/main.parameters.json para mapear valores de ambiente de azd para parâmetros do Bicep. Templates do Terraform geralmente usam infra/main.tf e arquivos Terraform relacionados.

Por exemplo, um arquivo de parâmetros do Bicep pode passar para a implantação da infraestrutura valores selecionados por azd:

{
  "parameters": {
    "environmentName": { "value": "${AZURE_ENV_NAME}" },
    "location": { "value": "${AZURE_LOCATION}" }
  }
}

Quando o provisionamento do Bicep é concluído, azd armazena as saídas do ponto de entrada como valores de ambiente. Os serviços e hooks do aplicativo podem usar esses valores para endpoints de recursos, nomes e outras configurações de tempo de execução.

output API_ENDPOINT string = api.outputs.uri

Fonte do aplicativo

A origem do aplicativo é opcional. Quando um modelo contém serviços implantáveis, cada definição de serviço aponta azure.yaml para seu diretório de origem. Um template pode organizar serviços sob src, usar diretórios em outras partes do repositório ou apontar um serviço para a raiz do repositório.

O nome da pasta em si não é significativo. O project valor em azure.yaml determina onde azd localiza cada serviço.

Configuração do ambiente

O .azure diretório contém o estado do ambiente local e os valores criados por azd. Ele pode conter valores de assinatura, localização, nome do recurso, ponto de extremidade e saída de implantação para vários ambientes.

Trate esse diretório como um estado local em vez de um ativo de modelo reutilizável. Não confirme arquivos de ambiente que contêm segredos ou valores específicos do ambiente.

Recursos de suporte

Os modelos também podem conter:

• GitHub Actions ou definições do Azure Pipelines.
• Dockerfiles e configuração de contêiner.
• Configuração do contêiner de desenvolvimento.
• Ganchos de serviço e comando.
• Testes, scripts e documentação do projeto.

Esses ativos são opcionais e devem ser incluídos somente quando dão suporte à experiência de modelo pretendida.

Associação de serviços e recursos

Para implantar um serviço de aplicativo, azd deve associar sua definição a azure.yaml um recurso de Azure provisionado. Por padrão, azd localiza um recurso cuja azd-service-name marca corresponde ao nome do serviço.

Por exemplo, um serviço chamado api é mapeado para um recurso marcado com azd-service-name: api. Em vez disso, você pode usar a propriedade de resourceName serviço para identificar explicitamente o destino de implantação.

A expressão Bicep a seguir adiciona a marca de descoberta às marcas existentes de um recurso:

tags: union(tags, {
  'azd-service-name': 'api'
})

Mantenha os nomes de serviço, as configurações de descoberta de recursos, as saídas de infraestrutura e as variáveis de ambiente do aplicativo alinhadas ao editar um modelo.

Criar ou adaptar um modelo

A experiência de criação recomendada é executar azd init e selecionar Configurar com o GitHub Copilot (pré-visualização). A sessão de agente do Copilot dedicada pode analisar arquivos existentes, ajudar a planejar um novo projeto, gerar ativos de modelo e validar o resultado. Para esse fluxo de trabalho e outros métodos de criação, consulte Iniciar com um novo modelo.

Os arquivos gerados não estão vinculados a Copilot. Você pode explorar e editar os arquivos de modelo diretamente após a inicialização. Você também pode criar os mesmos arquivos manualmente ou com outro agente de codificação de IA.

Se um modelo de Microsoft, sua organização ou a comunidade de desenvolvedores já fornecer uma arquitetura útil, comece com o modelo existente e adapte-o para seu projeto. Procure modelos disponíveis nas galerias de modelos.

Diretrizes de uso de modelo

Cada modelo é licenciado por seu proprietário sob o contrato que acompanha o modelo. Determine qual licença se aplica antes de usar ou distribuir um modelo.

A Microsoft não é responsável por modelos que não são da Microsoft e não os analisa quanto a questões de segurança, privacidade, compatibilidade ou desempenho. Modelos, incluindo os modelos fornecidos pela Microsoft, não são cobertos por nenhum programa ou serviço de suporte da Microsoft e são fornecidos no estado em que se encontram, sem garantia.

Examine todos os arquivos de modelo antes do provisionamento. Em particular, avalie atribuições de função, exposição de rede, métodos de autenticação, camadas de serviço, locais de recursos e custos esperados.

Próximas etapas