Работа с переменными среды командной строки разработчика Azure

Azure Developer CLI (azd) использует переменные среды для хранения параметров конфигурации и управления ими для сред развертывания. Эти переменные управляют подготовкой, развертыванием и запуском приложения в Azure. В этой статье объясняется, как переменные среды работают в azd средах и предоставляют рекомендации по эффективному управлению ими.

Общие сведения о переменных среды

В контексте интерфейса командной строки разработчика Azure переменные среды — это пары "ключ-значение", привязанные к определенным именованным средам, таким как разработка, тестирование или prod. Каждая azd среда поддерживает собственный набор переменных среды, позволяя настраивать разные параметры для различных целевых объектов развертывания.

Переменные среды хранятся в файлах azd в папках среды в папке.env..azure Они служат входными данными:

• Рабочие процессы развертывания приложений
• Конфигурации для служб и подключений Azure
• Подготовка инфраструктуры через Bicep и Terraform

В отличие от традиционных переменных среды, которые существуют на уровне операционной системы, azd переменные среды относятся к определенным средам в проекте, обеспечивая изоляцию между разными целевыми объектами развертывания.

Переменные среды обеспечивают несколько ключевых преимуществ при работе с azd:

• Изоляция среды: сохраняйте конфигурации для разработки, тестирования и рабочей среды отдельно и отдельно.
• Согласованность конфигурации. Убедитесь, что все члены команды используют одни и те же параметры для определенной среды.
• Инфраструктура как код: определение параметризации инфраструктуры с помощью переменных вместо жестко закодированных значений.
• Автоматизация развертывания. Включение конвейеров CI/CD для развертывания в разных средах с использованием одной базы кода, но различных конфигураций.
• Упрощенное управление: легко обновлять параметры во всех службах в среде из центрального расположения.

Каждая azd среда имеет собственный набор переменных, что позволяет настраивать определенные среды при использовании одного кода приложения и шаблонов инфраструктуры.

Переменные среды и env-файлы

azd Переменные среды хранятся в файлах в .env каталогах конкретной среды проекта. При создании среды с помощью azd env new <name>создается структура каталогов:

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

В .env файле используется стандартный формат, в котором каждая строка представляет пару "ключ-значение":

KEY1=value1
KEY2=value2

При выполнении таких azd upazd команд автоматически загружает переменные из файла выбранной среды.env.

Эти переменные влияют:

• Подготовка инфраструктуры: такие переменные, как AZURE_LOCATION и определение того, где и AZURE_SUBSCRIPTION_ID как создаются ресурсы.
• Развертывание. Переменные, такие как конечные точки службы, управляют подключением приложения к службам Azure.
• Конфигурация приложения: переменные можно передать в конфигурацию приложения для управления его поведением.
• Именование ресурсов: такие переменные, как AZURE_RESOURCE_GROUP влияние шаблонов именования ресурсов.

Файл .env также обновляется автоматически azd во время таких операций, как azd init, azd provisionи azd deploy, записывая выходные данные из шаблонов инфраструктуры и сохраняя их для дальнейшего использования.

Настройка переменных среды

Для задания azd переменных среды можно использовать различные методы в зависимости от сценария.

Использование команд CLI

Рекомендуемый способ задать переменную среды использует azd env set команду, которая включает проверки, чтобы убедиться, что допустимые значения:

azd env set <key> <value>

Например, чтобы задать значение конфигурации для приложения:

azd env set API_TIMEOUT 5000

Команда добавляет или обновляет переменную в .env файле выбранной среды. Вы также можете настроить конкретную среду с помощью флага --environment :

azd env set API_TIMEOUT 5000 --environment prod

Чтобы убедиться, что переменная среды была задана правильно:

azd env get-value API_TIMEOUT

Выходные данные из Bicep

Мощная функция azd — это возможность автоматического отслеживания выходных параметров из шаблонов инфраструктуры Bicep в качестве переменных среды. Например, при определении выходного параметра в main.bicep файле:

output API_ENDPOINT string = apiService.outputs.SERVICE_ENDPOINT_URL

После выполнения azd provisionвыходные данные автоматически сохраняются в файле среды .env :

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

Такой подход гарантирует, что приложение всегда имеет доступ к наиболее актуальным сведениям о ресурсах, например:

• Конечные точки службы и URL-адреса
• Имена и идентификаторы ресурсов

Получение и использование переменных среды

После установки можно получить доступ к переменным среды в нескольких контекстах.

Команды CLI

Чтобы просмотреть все переменные среды для текущей среды:

azd env get-values

Чтобы просмотреть значение определенной переменной, выполните следующие действия.

azd env get-value API_ENDPOINT

Для выходных данных, доступных для машинного чтения (полезно в сценариях):

azd env get-values --output json

Использование переменных среды в файлах инфраструктуры

Переменные среды можно использовать для настройки шаблонов инфраструктуры. Это полезно для именования, тегов или настройки ресурсов на основе текущей среды. azd также использует теги для поиска ресурсов в Azure для развертывания и других задач.

Рассмотрим следующий распространенный поток:

1. azd init Во время azdзадает эти переменные среды на основе ответа пользователя на запросы:

   AZURE_ENV_NAME=myapp-dev
   AZURE_LOCATION=eastus2
   

2. Ссылка на эти переменные в main.parameters.json папке infra . azd заменяет значения во время подготовки и передает разрешенные параметры в 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. Определите соответствующие параметры в шаблоне 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 предоставляет эти параметры Bicep с замененными значениями в main.parameters.json.

4. Используйте параметры для именования ресурсов и тегов, чтобы позже определить, к какой среде принадлежит ресурс:

   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'
     }
   }
   

Этот шаблон обеспечивает гибкость шаблонов, позволяет настраивать среду без изменений кода и улучшает управление ресурсами (именование, добавление тегов и обнаружение).

Обработчики

azd Переменные среды автоматически загружаются и доступны в перехватчиках и пользовательских скриптах, определенных в azure.yaml файле, можно получить доступ к переменным среды с помощью следующего синтаксиса:

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

Вы можете определить перехватчики в azure.yaml файле для выполнения этих скриптов в определенных точках жизненного azd цикла:

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

Удаление или обновление переменных

Чтобы удалить переменную из среды, выполните приведенные действия.

azd env unset VARIABLE_NAME

Чтобы обновить существующую переменную, выполните приведенные действия.

azd env set VARIABLE_NAME "new-value"

Чтобы обновить переменные локальной среды из текущего состояния ресурсов Azure:

azd env refresh

Обновление среды полезно при следующих случаях:

• Вы хотите убедиться, что локальный .env файл отражает последние выходные данные инфраструктуры (например, строки подключения, конечные точки и т. д.).
• Необходимо синхронизировать переменные среды после обновления среды товарища по команде.

AZD и переменные среды ОС

azd переменные среды и переменные среды операционной системы служат различным целям и работают разными способами:

azd не выполняет автоматическое чтение или запись переменных среды ОС. Однако можно взаимодействовать с обоими типами переменных с помощью пользовательских скриптов.

Чтение azd переменных среды и переменных среды ОС:

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

Стандартные переменные среды

azd задает и использует несколько распространенных переменных среды во всех средах:

Рекомендации по секретам и конфиденциальным данным

Хотя переменные среды удобны для конфигурации, им требуется специальная обработка конфиденциальных данных:

Избегайте хранения секретов в ENV-файлах

.env Файлы обычно хранятся в виде обычного текста и могут быть легко:

• Случайно зафиксировано в системе управления версиями
• Общий или скопированный без надлежащей защиты
• Просмотр всех пользователей с доступом к файлам проекта
• Включенные в журналы или отчеты об ошибках

Альтернативные варианты обработки секретов

Для конфиденциальных данных рассмотрим следующие более безопасные подходы:

• Ссылки на Azure Key Vault: храните секреты в Azure Key Vault и ссылайтесь на них в файле .env :

  azd env set-secret <secret-value>
  

  Эта команда создает секрет Key Vault и сохраняет ссылку на него в .env файле, а не фактическое значение.

• Управляемые удостоверения: настройте службы Azure для использования управляемых удостоверений вместо строк подключения или ключей доступа.

• Безопасность для конкретной среды: применение более строгих элементов управления безопасностью к рабочим средам, чем к средам разработки.

• JIT-секреты: создание коротких учетных данных во время развертывания, а не хранение постоянных секретов.

Дальнейшие шаги