Explorar e editar ficheiros modelo de CLI do Azure Developer

Um modelo de CLI para Desenvolvedores Azure (azd) é um repositório padrão com ativos de configuração e infraestrutura que permitem azd provisionar e implementar um projeto. Quer crie um novo modelo ou comece a partir de um já existente, continua responsável por rever e manter os seus ficheiros à medida que o projeto evolui.

Este artigo explica como inspecionar e editar os ficheiros principais do modelo. Para uma descrição conceptual da estrutura completa, veja Azure Developer CLI templates.

Este artigo utiliza o modelo hello-azd como exemplo padronizado para que possas ver o que cada ficheiro faz num projeto real. Os mesmos conceitos aplicam-se aos modelos que gera para as suas próprias aplicações. Para acompanhar, inicialize o modelo num diretório vazio:

azd init --template hello-azd

O hello-azd modelo implementa uma aplicação C# containerizada para Azure Container Apps e provisiona os recursos Azure de suporte através do Bicep. Utiliza uma estrutura de pastas como a seguinte, onde cada ativo principal corresponde a uma secção deste artigo:

.
├── azure.yaml                # Project configuration (Explore azure.yaml)
├── infra/                    # Infrastructure as code (Infrastructure files)
│   ├── main.bicep            # Deployment entry point
│   ├── main.parameters.json  # Parameter values that azd supplies
│   ├── abbreviations.json    # Resource name abbreviations
│   ├── app/                  # Application-specific modules
│   └── core/                 # Reusable resource modules
├── src/                      # Application source code (Source code)
│   └── Dockerfile            # Container image build for the app
├── .azure/                   # Environment configuration
└── README.md

A estrutura exata varia consoante o projeto e azure.yaml identifica os caminhos que azd utiliza. As secções seguintes descrevem como editar cada ativo.

Antes de fazer alterações substanciais, efetue um commit ou guarde por outro meio uma versão comprovadamente funcional do modelo. Revise todas as alterações quanto a credenciais incorporadas, recursos desnecessários, permissões excessivas, exposição da rede, níveis de serviço e valores específicos do ambiente.

Explorar azure.yaml

O azure.yaml ficheiro define o projeto e indica azd como provisionar a infraestrutura, empacotar o código da aplicação e implementar cada serviço. Pode definir serviços, definições de infraestrutura, ganchos, fluxos de trabalho e outros comportamentos do projeto.

O hello-azd modelo define um único serviço chamado aca:

name: azd-starter
metadata:
  template: hello-azd-dotnet
services:
  aca:
    project: ./src
    language: csharp
    host: containerapp
    docker:
      path: ./Dockerfile
      remoteBuild: true

Cada propriedade indica azd como gerir o serviço:

• aca é o nome do serviço. azdusa-o para associar o serviço ao recurso Azure que o hospeda. Para mais informações, consulte Configurar descoberta de serviço.
• project: ./src aponta para o código-fonte da aplicação que azd empacota e implementa.
• language: csharp identifica a linguagem da aplicação.
• host: containerapp indica a azd para implementar o serviço no Azure Container Apps.
• docker constrói a imagem do contentor a partir do Dockerfile no src diretório.
• remoteBuildindica azd para usar o Azure Container Registry (ACR) para construir a imagem do contentor.

Adicionar uma definição de serviço

Adicione uma entrada em services por cada aplicação adicional que azd deve implementar. Uma definição de serviço especifica o seu diretório de origem, linguagem e destino de alojamento do Azure. Por exemplo, para descrever um novo projeto API:

services:
  api:
    project: ./src/api
    language: csharp
    host: appservice

Quando mover código da aplicação, atualize o caminho correspondente project . Quando mudar a arquitetura do alojamento, atualize tanto a definição do serviço como a infraestrutura que fornece o host.

Para todas as propriedades e valores suportados disponíveis, consulte o azure.yaml esquema.

Código fonte

O código fonte da aplicação é opcional. Templates com aplicações deployáveis costumam organizar o código-fonte sob o src diretório, mas não precisa de usar um nome ou layout específico de pasta. A project propriedade de cada serviço em azure.yaml indica azd onde reside o seu código-fonte.

Em hello-azd, o serviço aca define project: ./src, pelo que azd empacota a aplicação C# no diretório src e implementa-a no Azure Container Apps. Como o serviço também define uma docker configuração, azd constrói a imagem do contentor a partir do Dockerfile no src diretório antes da implementação.

azdsuporta Node.js, Python, .NET, Java e Go em hosts Azure suportados. Um template também pode implementar contentores. Para combinações atuais de linguagem, framework e host, veja Linguagens e ambientes suportados.

Edita o código-fonte como farias em qualquer repositório de aplicações. Se adicionar um serviço ou mover o seu diretório de origem, atualize a definição do serviço azure.yaml . Se a aplicação precisar de um novo recurso Azure, atualize a infraestrutura e passe o endpoint ou nome de recurso necessário à aplicação através da configuração.

Alterar um diretório de origem de serviço

Por exemplo, se mover a aplicação hello-azd de src para src/app, atualize o valor de project do serviço aca:

services:
  aca:
    project: ./src/app
    language: csharp
    host: containerapp
    docker:
      path: ./Dockerfile
      remoteBuild: true

Ficheiros de infraestrutura

O infra diretório contém os ficheiros Bicep ou Terraform que definem os recursos Azure para o modelo. Em hello-azd, o infra diretório utiliza o Bicep e inclui os seguintes ativos-chave:

• main.bicep é o ponto de entrada padrão de implementação que azd executa para aprovisionar recursos.
• main.parameters.json fornece os valores dos parâmetros para main.bicep.
• app contém módulos específicos para a aplicação.
• core contém módulos reutilizáveis para recursos comuns, como armazenamento e alojamento.

Como main.bicep corre durante azd up

Ao executar azd up, a fase de aprovisionamento implementa infra/main.bicep. Em hello-azd, main.bicep direciona-se ao âmbito da subscrição, cria um grupo de recursos e depois chama módulos para provisionar os recursos que a aplicação necessita:

targetScope = 'subscription'

// Create a storage account
module storage './core/storage/storage-account.bicep' = {
  name: 'storage'
  scope: rg
  params: {
    name: !empty(storageAccountName) ? storageAccountName : '${abbrs.storageStorageAccounts}${resourceToken}'
    location: location
    tags: tags
    allowSharedKeyAccess: false
    containers: [ { name: 'attachments' } ]
    tables: [ { name: 'tickets' } ]
  }
}

// Container app for the 'aca' service
module web 'app/app.bicep' = {
  name: serviceName
  scope: rg
  params: {
    // ...
    serviceName: serviceName
  }
}

O main.bicep ficheiro prevê uma identidade gerida atribuída pelo utilizador, uma conta Armazenamento do Azure, um ambiente e registo Azure Container Apps, e a aplicação container que hospeda o aca serviço. Também atribui as funções que permitem à identidade gerida aceder ao armazenamento. Os módulos mantêm cada recurso no seu próprio ficheiro para que main.bicep se mantenha legível.

Adicionar um recurso a main.bicep

Adicione diretamente no infra/main.bicep as declarações de recursos para recursos simples ou pontuais. Incorpora recursos em módulos Bicep separados quando os reutilizares, quando um recurso precisar de vários recursos relacionados, ou quando quiseres manter main.bicep legível. Tal como hello-azd, muitos modelos agrupam módulos reutilizáveis em infra/core.

Para recursos comuns do Azure, prefira um Módulo Verificado do Azure a criar um módulo do zero. Os módulos verificados são mantidos pela Microsoft, seguem as melhores práticas de segurança e fiabilidade, e reduzem a quantidade de código de infraestrutura que mantém no modelo.

Para obter um guia passo a passo completo sobre como adicionar um novo recurso a hello-azd, consulte: Estender um modelo.

O ficheiro main.parameters.json mapeia os valores que o azd mantém nos parâmetros do Bicep. O hello-azd modelo utiliza os seguintes parâmetros:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "environmentName": { "value": "${AZURE_ENV_NAME}" },
    "location": { "value": "${AZURE_LOCATION}" },
    "principalId": { "value": "${AZURE_PRINCIPAL_ID}" },
    "principalType": { "value": "${AZURE_PRINCIPAL_TYPE=User}" }
  }
}

Cada entrada associa um parâmetro Bicep a um valor que azd mantém no ambiente, como o nome do ambiente, localização e o principal que executa a implementação. Use main.parameters.json para valores que variam consoante o ambiente ou implementação, como o nome do ambiente, localização ou nome de recursos que azd gera. Mantém os valores estáveis que não mudam de ambiente para ambiente como valores predefinidos dos parâmetros ou literais em main.bicep. Esta abordagem mantém o mesmo Bicep reutilizável entre diferentes ambientes, sem necessidade de o editar para cada implementação.

Quando adicionas ou editas infraestrutura:

• Mantenha a configuração dos recursos independente do ambiente. Use parâmetros e azd valores do ambiente em vez de incorporar IDs de subscrição, nomes de recursos, localizações ou credenciais.
• Use saídas seguras para valores sensíveis e não exponha segredos como saídas de implementação em texto simples.
• Aplique atribuições de funções de privilégio mínimo a identidades geridas.
• Mantenha as definições de serviço em azure.yaml alinhadas com os recursos a que se destinam.
• Reveja os efeitos dos níveis de serviço, limites de escala, redundância e definições de retenção no custo.

Para orientações sobre linguagem e módulos do Bicep, consulte a documentação do Bicep. Para templates baseados em Terraform, veja Usar Terraform com Azure Developer CLI.

Configurar a descoberta de serviço

Por defeito, azd deteta o recurso do Azure para um serviço localizando o recurso cuja etiqueta azd-service-name corresponde ao nome do serviço em azure.yaml. Se renomear um serviço, atualize a tag de recurso correspondente ou configure explicitamente o nome do recurso em azure.yaml.

Por exemplo, no hello-azd o nome do serviço aca corresponde ao identificador azd-service-name no recurso da aplicação de contentor. A azure.yaml definição do serviço define o nome:

services:
  aca:
    project: ./src
    language: csharp
    host: containerapp

O módulo de aplicação container em infra/app/app.bicep aplica a etiqueta correspondente:

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

Configurar um caminho de infraestrutura não padrão

A infra secção de azure.yaml identifica o fornecedor de infraestruturas e o ponto de entrada. Estes valores são opcionais quando se usa o layout padrão do Bicep, mas declará-los pode tornar um layout não padrão mais fácil de entender:

infra:
  provider: bicep
  path: infra
  module: main

Configuração do ambiente

O .azure diretório contém o estado do ambiente local e os valores que azd criam, como a subscrição selecionada, localização, nomes de recursos e saídas de implementação. Trate este diretório como estado local em vez de um ativo de modelo reutilizável. Não faça commit de ficheiros de configuração do ambiente que contenham segredos ou valores específicos do ambiente.

Adicionar outputs de infraestrutura

Quando se executa azd provision para implementar o Bicep, ele capta os resultados do ponto de entrada da infraestrutura como azd valores do ambiente. Adicione saídas para endpoints de recursos, nomes de recursos e IDs de clientes de identidade gerida que os serviços de aplicação ou hooks necessitem. Por exemplo, hello-azd apresenta o registo de contentores e os detalhes da identidade gerida a partir de main.bicep:

output AZURE_CONTAINER_REGISTRY_ENDPOINT string = containerAppsEnv.outputs.registryLoginServer
output AZURE_CONTAINER_REGISTRY_NAME string = containerAppsEnv.outputs.registryName
output AZURE_USER_ASSIGNED_IDENTITY_NAME string = identity.outputs.name

Não produza segredos quando uma identidade gerida ou uma referência do Key Vault pode fornecer acesso em vez disso. Após o provisionamento, inspecionar os valores capturados executando azd env get-values.

Para mais informações, consulte Gerir variáveis de ambiente.

Testa as tuas alterações

Execute azd up para provisionar a infraestrutura e implementar quaisquer serviços de aplicação:

azd up

Se pretende partilhar o modelo, inicialize-o num diretório limpo e implemente-o num novo ambiente. Este teste ajuda a identificar ficheiros locais, valores em cache ou pressupostos específicos do ambiente que não fazem parte do modelo.

Conteúdo relacionado

• Visão geral do desenvolvimento de modelos
• Comece com um novo modelo
• Comece a partir de um modelo existente
• Estenda um modelo
• Explore o azd up fluxo de trabalho

Pedir ajuda

Para informações sobre como registar um bug, pedir ajuda ou propor uma nova funcionalidade para a Azure Developer CLI, por favor visite a página troubleshooting and support.