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

A CLI do Desenvolvedor do Azure (azd) usa variáveis de ambiente para armazenar e gerenciar definições de configuração 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 dentro dos azd ambientes e fornece orientação sobre como gerenciá-las de forma eficaz.

Compreender as variáveis de ambiente

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

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

• Fluxos de trabalho de implantação de aplicativos
• 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 escopo para ambientes específicos dentro do seu projeto, fornecendo isolamento entre diferentes destinos de implantação.

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

• Isolamento do ambiente: mantenha as configurações para desenvolvimento, teste e produção separadas e distintas.
• Consistência de configuração: certifique-se de que todos os membros da equipe usem as mesmas configurações para um ambiente específico.
• Infraestrutura como código: defina a parametrização da infraestrutura por meio de variáveis em vez de valores codificados.
• Automação de implantação: permita que pipelines de CI/CD sejam implantados 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 a partir de um local central.

Cada azd ambiente tem seu próprio conjunto de variáveis, permitindo configurações específicas do ambiente enquanto usa 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 tu crias um ambiente usando azd env new <name>, uma estrutura de diretórios é criada.

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

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

KEY1=value1
KEY2=value2

Quando você executa comandos como azd up, azd carrega automaticamente variáveis do .env arquivo do ambiente selecionado.

Estas variáveis influenciam:

• Provisionamento de infraestrutura: variáveis como 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 por azd durante operações como azd init, azd provision e 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 é usando 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 .env variável no arquivo do ambiente selecionado no momento. Você também pode segmentar 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 Bíceps

Um recurso poderoso da azd é a sua capacidade de capturar automaticamente parâmetros de saída dos modelos de infraestrutura 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 ambiente .env.

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

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

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

Obter e usar variáveis de ambiente

Uma vez 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 por máquina (ú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 tags para localizar recursos no Azure para implantação e outras tarefas.

Considere o seguinte fluxo comum:

1. Durante azd init, azd configura 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 em main.parameters.json no diretório infra. 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 no 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 a estes parâmetros do Bíceps os valores substituídos em main.parameters.json.

4. Use os parâmetros para nomenclatura de recursos e tags 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, permite 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 estão 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 do 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 de seus 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 AZD vs OS

azd As variáveis de ambiente e as variáveis de ambiente do sistema operacional servem propósitos diferentes e funcionam de maneiras diferentes:

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

Leia azd as variáveis de ambiente e as variáveis de ambiente do SO:

# 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)"

azd

# 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:

Considerações sobre segredos e dados confidenciais

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

Evite armazenar segredos em arquivos .env

.env Os ficheiros são normalmente armazenados em texto simples e podem ser:

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

Alternativas para lidar com segredos

Para dados confidenciais, considere estas abordagens mais seguras:

• Referências do Azure Key Vault: armazene segredos no Azure Key Vault e faça referência a eles em seu .env arquivo:

  azd env set-secret <secret-value>
  

  Este comando cria um segredo do Cofre da Chave 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 rígidos aos ambientes de produção do que aos de desenvolvimento.

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

Próximos passos