Trabalhar com variáveis de ambiente da CLI do Desenvolvedor do Azure

A CLI do Desenvolvedor do Azure (azd) usa variáveis de ambiente para armazenar e gerenciar configurações para ambientes de implantação. Essas variáveis controlam como seu aplicativo é provisionado, implantado e executado no Azure. Este artigo explica como as variáveis de ambiente funcionam em azd ambientes e fornece diretrizes sobre como gerenciá-las com eficiência.

Entender variáveis de ambiente

No contexto da CLI do Desenvolvedor do Azure, as variáveis de ambiente são pares chave-valor que estão vinculados a ambientes nomeados específicos, como desenvolvimento, teste ou prod. Cada azd ambiente mantém seu próprio conjunto de variáveis de ambiente, permitindo que você defina configurações diferentes para destinos de implantação diferentes.

As variáveis de ambiente são azd armazenadas em arquivos dentro .env de suas pastas de ambiente na .azure pasta. Eles servem como entradas para:

• Fluxos de trabalho de implantação de aplicativo
• Configurações para serviços e conexões do Azure
• Provisionamento de infraestrutura via Bicep e Terraform

Ao contrário das variáveis de ambiente tradicionais que existem no nível do sistema operacional, azd as variáveis de ambiente têm como escopo ambientes específicos em seu projeto, fornecendo isolamento entre diferentes destinos de implantação.

As variáveis de ambiente fornecem vários benefícios importantes ao trabalhar com azd:

• Isolamento de ambiente: mantenha as configurações para desenvolvimento, teste e produção separadas e distintas.
• Consistência de configuração: verifique se todos os membros da equipe usam as mesmas configurações para um ambiente específico.
• Infraestrutura como Código: defina a parametrização de infraestrutura por meio de variáveis em vez de valores embutidos em código.
• Automação de implantação: habilite pipelines de CI/CD para implantar em ambientes diferentes usando a mesma base de código, mas configurações diferentes.
• Gerenciamento simplificado: atualize facilmente as configurações em todos os serviços em um ambiente de um local central.

Cada azd ambiente tem seu próprio conjunto de variáveis, permitindo configurações específicas do ambiente ao usar o mesmo código de aplicativo e modelos de infraestrutura.

Variáveis de ambiente e arquivos .env

As azd variáveis de ambiente são armazenadas em .env arquivos dentro dos diretórios específicos do ambiente do seu projeto. Quando você cria um ambiente usando azd env new <name>, uma estrutura de diretório é criada:

.azure/
├── <environment-name>/
│   ├── .env                   # Environment variables for this environment

O .env arquivo usa um formato padrão em que cada linha representa um par chave-valor:

KEY1=value1
KEY2=value2

Quando você executa comandos como azd up, azd carrega automaticamente variáveis do arquivo do .env ambiente de seleção.

Essas variáveis influenciam:

• Provisionamento de infraestrutura: variáveis gostam AZURE_LOCATION e AZURE_SUBSCRIPTION_ID determinam onde e como os recursos são criados.
• Implantação: variáveis como pontos de extremidade de serviço controlam como seu aplicativo se conecta aos serviços do Azure.
• Configuração do aplicativo: as variáveis podem ser passadas para a configuração do aplicativo para controlar seu comportamento.
• Nomenclatura de recursos: variáveis como AZURE_RESOURCE_GROUP influenciar padrões de nomenclatura de recursos.

O .env arquivo também é atualizado automaticamente azd durante operações como azd init, azd provisione azd deploy, capturando saídas de seus modelos de infraestrutura e armazenando-as para uso futuro.

Definir variáveis de ambiente

Você pode usar métodos diferentes para definir azd variáveis de ambiente, dependendo do cenário.

Usar comandos da CLI

A maneira recomendada de definir uma variável de ambiente é usar o azd env set comando, que inclui verificações para garantir valores válidos:

azd env set <key> <value>

Por exemplo, para definir um valor de configuração para seu aplicativo:

azd env set API_TIMEOUT 5000

O comando adiciona ou atualiza a variável no .env arquivo do ambiente selecionado no momento. Você também pode direcionar um ambiente específico usando o --environment sinalizador:

azd env set API_TIMEOUT 5000 --environment prod

Para verificar se a variável de ambiente foi definida corretamente:

azd env get-value API_TIMEOUT

Saída do Bicep

Um recurso poderoso é a capacidade de azd capturar automaticamente parâmetros de saída de seus modelos de infraestrutura do Bicep como variáveis de ambiente. Por exemplo, quando você define um parâmetro de saída em seu main.bicep arquivo:

output API_ENDPOINT string = apiService.outputs.SERVICE_ENDPOINT_URL

Após a execução azd provision, essa saída é salva automaticamente no arquivo do .env ambiente:

API_ENDPOINT=https://api-dev-123456.azurewebsites.net

Essa abordagem garante que seu aplicativo sempre tenha acesso às informações de recurso mais atuais, como:

• Pontos de extremidade de serviço e URLs
• Nomes e identificadores de recursos

Obter e usar variáveis de ambiente

Depois de definido, você pode acessar variáveis de ambiente em vários contextos.

Comandos da CLI

Para exibir todas as variáveis de ambiente para o ambiente atual:

azd env get-values

Para exibir o valor de uma variável específica:

azd env get-value API_ENDPOINT

Para saída legível pelo computador (útil em scripts):

azd env get-values --output json

Usar variáveis de ambiente em arquivos de infraestrutura

Você pode usar variáveis de ambiente para personalizar seus modelos de infraestrutura. Isso é útil para nomear, marcar ou configurar recursos com base no ambiente atual. azd também usa marcas para localizar recursos no Azure para implantação e outras tarefas.

Considere o seguinte fluxo comum:

1. Durante azd init, azd define essas variáveis de ambiente com base na resposta do usuário aos prompts:

   AZURE_ENV_NAME=myapp-dev
   AZURE_LOCATION=eastus2
   

2. Faça referência a essas variáveis na main.parameters.jsoninfra pasta. azd substitui os valores durante o provisionamento e passa os parâmetros resolvidos para o Bicep:

   {
     "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
     "contentVersion": "1.0.0.0",
     "parameters": {
       "name": {
         "value": "${AZURE_ENV_NAME}"
       },
       "location": {
         "value": "${AZURE_LOCATION}"
       }
     }
   }
   

3. Defina parâmetros correspondentes em seu modelo Bicep:

   @description('Name of the environment used to derive resource names and tags.')
   param name string
   
   @minLength(1)
   @description('Primary Azure region for all resources.')
   param location string
   

   azd fornece esses parâmetros Bicep com os valores substituídos em main.parameters.json.

4. Use os parâmetros para nomenclatura de recursos e marcas para identificar posteriormente a qual ambiente um recurso pertence:

   var resourceToken = toLower(uniqueString(resourceGroup().id, name, location))
   
   resource storageAccount 'Microsoft.Storage/storageAccounts@2022-09-01' = {
     name: 'st${resourceToken}'
     location: location
     sku: {
       name: 'Standard_LRS'
     }
     kind: 'StorageV2'
     tags: {
       Environment: name
       Project: 'myproject'
     }
   }
   

Esse padrão mantém seus modelos flexíveis, habilita a personalização por ambiente sem alterações de código e melhora a governança de recursos (nomenclatura, marcação e descoberta).

Ganchos

azd as variáveis de ambiente são automaticamente pré-carregadas e disponíveis em ganchos e scripts personalizados definidos em seu azure.yaml arquivo, você pode acessar variáveis de ambiente usando a seguinte sintaxe:

# Use the variables in your script
echo "API endpoint: $API_ENDPOINT"
echo "Deploying to: $AZURE_LOCATION"

# Use the variables in your script
Write-Host "API endpoint: $API_ENDPOINT"
Write-Host "Deploying to: $AZURE_LOCATION"

Você pode definir ganchos em seu azure.yaml arquivo para executar esses scripts em pontos específicos no azd ciclo de vida:

hooks:
  postprovision:
    windows:
      shell: pwsh
      run: ./scripts/load-env-vars.ps1
      interactive: false
    posix:
      shell: sh
      run: ./scripts/load-env-vars.sh
      interactive: false

Remover ou atualizar variáveis

Para remover uma variável do seu ambiente:

azd env unset VARIABLE_NAME

Para atualizar uma variável existente:

azd env set VARIABLE_NAME "new-value"

Para atualizar suas variáveis de ambiente local do estado atual dos recursos do Azure:

azd env refresh

Atualizar seu ambiente é útil quando:

• Você deseja garantir que seu arquivo local .env reflita as saídas mais recentes de sua infraestrutura (como cadeias de conexão, pontos de extremidade etc.).
• Você precisa sincronizar variáveis de ambiente depois que um colega de equipe atualizou o ambiente.

Variáveis de ambiente do AZD vs OS

azd variáveis de ambiente e variáveis de ambiente do sistema operacional atendem a diferentes finalidades e funcionam de maneiras diferentes:

azd não lê ou grava automaticamente variáveis de ambiente do sistema operacional. No entanto, você pode interagir com ambos os tipos de variáveis usando scripts personalizados.

Ler azd variáveis de ambiente e variáveis de ambiente do sistema operacional:

# Access OS environment variable
echo "OS variable: $PATH"

# Access azd environment variable
echo "AZD variable: $(azd env get-value MY_VARIABLE)"

# Access OS environment variable
Write-Host "OS variable: $env:PATH"

# Access azd environment variable
Write-Host "AZD variable: $(azd env get-value MY_VARIABLE)"

Escreva azd variáveis de ambiente em variáveis de ambiente do sistema operacional ou da estrutura:

# Load all azd environment variables into the current shell session
while IFS='=' read -r key value; do
    value=$(echo "$value" | sed 's/^"//' | sed 's/"$//')
    export "$key=$value"
done <<EOF
$(azd env get-values)
EOF

# Load all azd environment variables into the current PowerShell session
foreach ($line in (& azd env get-values)) {
    if ($line -match "([^=]+)=(.*)") {
        $key = $matches[1]
        $value = $matches[2] -replace '^"|"$'
        $env:$key = $value
    }
}

Variáveis de ambiente padrão

azd define e usa várias variáveis de ambiente comuns em todos os ambientes:

Segredos e considerações de dados confidenciais

Embora as variáveis de ambiente sejam convenientes para a configuração, elas exigem tratamento especial para dados confidenciais:

Evite armazenar segredos em arquivos .env

.env os arquivos normalmente são armazenados em texto sem formatação e podem ser facilmente:

• Acidentalmente confirmado no controle do código-fonte
• Compartilhado ou copiado sem proteções adequadas
• Exibido por qualquer pessoa com acesso aos arquivos do projeto
• Incluído em logs ou relatórios de erro

Alternativas para lidar com segredos

Para dados confidenciais, considere estas abordagens mais seguras:

• Referências do Azure Key Vault: armazenar segredos no Azure Key Vault e referenciá-los em seu .env arquivo:

  azd env set-secret <secret-value>
  

  Esse comando cria um segredo do Key Vault e armazena uma referência a ele em seu .env arquivo em vez do valor real.

• Identidades gerenciadas: configure seus serviços do Azure para usar identidades gerenciadas em vez de cadeias de conexão ou chaves de acesso.

• Segurança específica do ambiente: aplique controles de segurança mais rigorosos a ambientes de produção do que os de desenvolvimento.

• Segredos just-in-time: gere credenciais de curta duração durante a implantação em vez de armazenar segredos persistentes.

Próximas etapas