Explorar e editar arquivos de modelo da CLI do Desenvolvedor Azure

Um modelo da CLI do Desenvolvedor Azure (azd) é um repositório padrão com ativos de configuração e infraestrutura que permitem azd provisionar e implantar um projeto. Se você criar um novo modelo ou começar a partir de um existente, continuará responsável por revisar e manter seus arquivos à medida que o projeto evolui.

Este artigo explica como inspecionar e editar os arquivos de modelo primário. Para obter uma descrição conceitual da estrutura completa, consulte modelos da CLI do Azure para Desenvolvedores.

Este artigo usa o modelo hello-azd como um exemplo padronizado para que você possa ver o que cada arquivo faz em um projeto real. Os mesmos conceitos se aplicam aos modelos gerados para seus próprios aplicativos. Para acompanhar, inicialize o modelo em um diretório vazio:

azd init --template hello-azd

O hello-azd modelo implanta um aplicativo C# em contêineres para Aplicativos de Contêiner do Azure e provisiona os recursos de suporte Azure por meio de Bicep. Ele usa uma estrutura de pastas como a seguinte, em que cada ativo primário é mapeado para uma seção neste 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 de acordo com o projeto e azure.yaml identifica os caminhos usados azd . As seções a seguir descrevem como editar cada ativo.

Antes de fazer alterações substanciais, faça um commit ou salve de outra forma uma versão comprovadamente funcional do modelo. Examine todas as alterações de credenciais inseridas, recursos desnecessários, permissões excessivas, exposição de rede, camadas de serviço e valores específicos do ambiente.

Explorar o azure.yaml

O azure.yaml arquivo define o projeto e informa azd como provisionar a infraestrutura, empacotar o código do aplicativo e implantar cada serviço. Ele pode definir serviços, configurações de infraestrutura, ganchos, fluxos de trabalho e outro comportamento de 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 informa azd como lidar com o serviço:

• aca é o nome do serviço. azd o usa para associar o serviço ao recurso do Azure que o hospeda. Para obter mais informações, consulte Configurar a descoberta de serviço.
• project: ./src aponta para o código-fonte do aplicativo que azd empacota e implanta.
• language: csharp identifica o idioma do aplicativo.
• host: containerapp instrui azd a implantar o serviço no Aplicativos de Contêiner do Azure.
• docker cria a imagem de contêiner a partir de Dockerfile no diretório src.
• remoteBuild instrui azd a usar o Registro de Contêiner do Azure (ACR) para criar a imagem de contêiner.

Adicionar uma definição de serviço

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

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

Ao mover o código do aplicativo, atualize o caminho correspondente project . Quando você alterar a arquitetura de hospedagem, atualize a definição de serviço e a infraestrutura que provisiona o host.

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

Código-fonte

A origem do aplicativo é opcional. Modelos com aplicativos implantáveis geralmente organizam o código-fonte no src diretório, mas você não precisa usar um nome ou layout de pasta específico. A propriedade project para cada serviço em azure.yaml informa ao azd onde está localizado o seu código-fonte.

Em hello-azd, o serviço aca define project: ./src, portanto azd empacota o aplicativo C# no diretório src e o implanta no Aplicativos de Contêiner do Azure. Como o serviço também define uma configuração docker, azd constrói a imagem do contêiner a partir de Dockerfile no diretório src antes da implantação.

azd dá suporte a Node.js, Python, .NET, Java e Go em hosts do Azure com suporte. Um modelo também pode implantar contêineres. Para obter combinações atuais de idioma, estrutura e host, consulte idiomas e ambientes com suporte.

Edite o código-fonte como faria em qualquer repositório de aplicativos. Se você adicionar um serviço ou mover seu diretório de origem, atualize sua azure.yaml definição de serviço. Se o aplicativo precisar de um novo recurso do Azure, atualize a infraestrutura e passe o endpoint ou o nome do recurso necessário para o aplicativo por meio das configurações.

Alterar um diretório de origem do serviço

Por exemplo, se você mover o aplicativo 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

Arquivos de infraestrutura

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

• main.bicep é o ponto de entrada padrão para implantação que azd executa para provisionar recursos.
• main.parameters.json fornece os valores de parâmetro para main.bicep.
• app contém módulos específicos para o aplicativo.
• core contém módulos reutilizáveis para recursos comuns, como armazenamento e hospedagem.

Como main.bicep é executado durante azd up

Quando você executa azd up, a fase de provisionamento implanta infra/main.bicep. Em main.bicep, hello-azd tem como destino o escopo da assinatura, cria um grupo de recursos e, em seguida, chama módulos para provisionar os recursos de que o aplicativo precisa:

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 arquivo provisiona uma identidade gerenciada atribuída pelo usuário, uma conta Armazenamento do Azure, um ambiente Aplicativos de Contêiner do Azure e registro e o aplicativo de contêiner que hospeda o aca serviço. Ele também atribui as funções que permitem que a identidade gerenciada acesse o armazenamento. Os módulos mantêm cada recurso em seu próprio arquivo para que main.bicep permaneça legível.

Adicionar um recurso a main.bicep

Adicione declarações de recurso diretamente em infra/main.bicep para recursos simples ou únicos. Divida os recursos em módulos Bicep separados quando for reutilizá-los, quando um recurso precisar de vários recursos relacionados ou quando você quiser manter main.bicep legível. Assim como hello-azd, muitos modelos agrupam módulos reutilizáveis em infra/core.

Para recursos comuns de Azure, prefira um módulo verificado Azure em vez de criar um módulo do zero. Os módulos verificados são mantidos Microsoft, seguem as práticas recomendadas de segurança e confiabilidade e reduzem a quantidade de código de infraestrutura que você mantém no modelo.

Para obter um passo a passo completo ao qual adicionar um novo recurso hello-azd, consulte Estender um modelo.

O arquivo main.parameters.json mapeia os valores que azd mantém para os parâmetros do Bicep. O hello-azd modelo usa 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, o local e a entidade que executa a implantação. Use main.parameters.json para valores que variam conforme o ambiente ou a implantação, como o nome do ambiente, a localização ou os nomes de recursos que azd gera. Mantenha valores estáveis que não mudam entre ambientes como valores padrão de parâmetros ou literais em main.bicep. Essa abordagem mantém o mesmo arquivo Bicep reutilizável em diferentes ambientes, sem precisar editá-lo para cada implantação.

Ao adicionar ou editar a infraestrutura:

• Mantenha o ambiente de configuração de recursos independente. Use parâmetros e azd valores de ambiente em vez de inserir IDs de assinatura, nomes de recursos, locais ou credenciais.
• Use saídas seguras para valores sensíveis e não exponha segredos como saídas de implantação em texto simples.
• Aplique atribuições de função com privilégios mínimos a identidades gerenciadas.
• Mantenha as definições de serviço azure.yaml alinhadas aos recursos aos quais se destinam.
• Examine os efeitos das camadas de serviço, limites de dimensionamento, redundância e configurações de retenção sobre o custo.

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

Configurar a descoberta de serviço

Por padrão, azd descobre o recurso Azure para um serviço localizando o recurso cuja azd-service-name marca corresponde ao nome do serviço.azure.yaml Se você renomear um serviço, atualize a marca de recurso correspondente ou configure explicitamente o nome do recurso em azure.yaml.

Por exemplo, em hello-azd, o nome do serviço aca corresponde à tag azd-service-name no recurso do aplicativo de contêiner. A azure.yaml definição do serviço define o nome:

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

O módulo do aplicativo de contêiner em infra/app/app.bicep aplica a tag correspondente:

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

Configurar um caminho de infraestrutura não padrão

A seção infra de azure.yaml identifica o provedor de infraestrutura e o ponto de entrada. Esses valores são opcionais quando você usa o layout de Bicep padrão, mas declará-los pode tornar um layout diferente do 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 assinatura selecionada, o local, os nomes de recursos e as saídas de implantação. 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.

Adicionar saídas de infraestrutura

Quando você executa azd provision para implantar o Bicep, ele captura as saídas do ponto de entrada da infraestrutura como valores de ambiente azd. Adicione saídas para pontos de extremidade de recurso, nomes de recursos e IDs de cliente de identidade gerenciada que os serviços de aplicativo ou ganchos precisam. Por exemplo, hello-azd gera o registro de contêiner e os detalhes da identidade gerenciada 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 exponha segredos se uma identidade gerenciada ou uma referência ao Key Vault puder conceder acesso. Após o provisionamento, inspecione os valores capturados executando azd env get-values.

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

Teste as suas mudanças

Execute azd up para provisionar a infraestrutura e implantar todos os serviços de aplicativo:

azd up

Se você pretende compartilhar o modelo, inicialize-o em um diretório limpo e implante-o com um novo ambiente. Esse teste ajuda a identificar arquivos locais, valores armazenados em cache ou suposições específicas do ambiente que não fazem parte do modelo.

Conteúdo relacionado

• Visão geral do desenvolvimento de modelos
• Começar com um novo modelo
• Iniciar a partir de um modelo existente
• Estender um modelo
• Explorar o azd up fluxo de trabalho

Solicitar ajuda

Para obter informações sobre como arquivar um bug, solicitar ajuda ou propor um novo recurso para a CLI do Desenvolvedor do Azure, visite a página troubleshooting e suporte.