Используйте @akv() для подстановки секретов в Azure Key Vault в строителе API данных.

Построитель API данных (DAB) позволяет хранить секреты, такие как строки подключения к базе данных, вне файла конфигурации среды выполнения, заменив их во время загрузки. Первоначально это было сделано с @env() функцией для переменных среды. Начиная с версии 1.6 DAB добавляет поддержку Azure Key Vault через функцию @akv() .

Что @akv() делает

Вы можете ссылаться на секрет, хранящийся в Azure Key Vault, непосредственно в формате JSON конфигурации:

{
  "data-source": {
    "connection-string": "@akv('my-connection-secret')"
  }
}

Во время загрузки конфигурации DAB обрабатывает заполнитель, заменяя его значением секрета, аналогично тому, как работает @env('VAR_NAME'). Если не удается получить секрет, загрузка конфигурации завершается ошибкой. Ошибки включают отсутствие секретов или сбоев авторизации.

Структура конфигурации

azure-key-vault Добавьте раздел на корневом уровне конфигурации:

{
  "azure-key-vault": {
    "endpoint": "https://my-vault-name.vault.azure.net/",
    "retry-policy": {
      "mode": "exponential",
      "max-count": 5,
      "delay-seconds": 2,
      "max-delay-seconds": 30,
      "network-timeout-seconds": 45
    }
  }
}

Свойства

Недвижимость Обязательно Тип Description
endpoint Да , если используется Key Vault струна Полный URL-адрес конечной точки Key Vault
retry-policy нет объект Переопределяет поведение повторных попыток доступа при вызове Key Vault

Объект политики повтора

Поле По умолчанию Примечания.
mode exponential Допустимые значения: fixed или exponential
max-count 3 Должно быть больше 0
delay-seconds 1 Должно быть больше 0
max-delay-seconds 60 Должно быть больше 0, потолок для экспоненциального отката
network-timeout-seconds 60 Должно быть больше 0

Режимы политики повторных попыток

Mode Поведение
fixed Поддерживает постоянный интервал delay-seconds между попытками до тех пор, пока max-count
exponential Удвоит задержку до достижения max-delay-seconds или max-count

Локальная разработка: AKV-файлы

Для разработки без Azure Key Vault используйте .akv файл для имитации секретов. Формат равен строке name=value :

my-connection-secret=Server=.;Database=AppDb;User Id=app;Password=local-dev;
api-key=dev-api-key-123

Замечание

Если вы предоставляете локальный .akv файл для разработки, его записи используются для разрешения поиска «secret-name», не вызывая сетевой вызов в Azure Key Vault.

Руководящие принципы:

  • Не добавляйте .akv в систему управления версиями
  • Имена секретов должны соответствовать именам, используемым в @akv('name')

Добавление параметров Azure Key Vault с помощью CLI

Параметры Key Vault можно настроить с помощью интерфейса командной строки:

dab configure \
  --azure-key-vault.endpoint "https://my-vault.vault.azure.net/" \
  --azure-key-vault.retry-policy.mode exponential \
  --azure-key-vault.retry-policy.max-count 5 \
  --azure-key-vault.retry-policy.delay-seconds 2 \
  --azure-key-vault.retry-policy.max-delay-seconds 30 \
  --azure-key-vault.retry-policy.network-timeout-seconds 45 \
  --config dab-config.json

Ратификация:

  • Поля политики повторных попыток без конечной точки вызывают сбой проверки
  • Необязательные параметры повторных попыток должны быть положительными целыми числами

Использование @akv() в конфигурации

Базовая подстановка

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@akv('primary-sql-connection')"
  }
}

Смешано с @env()

{
  "data-source": {
    "database-type": "@env('DB_TYPE')",
    "connection-string": "@akv('sql-connection')"
  },
  "runtime": {
    "rest": { "enabled": true }
  }
}

Замечание

При запуске @env() подстановки происходят перед @akv() подстановками.

Параметры хранимой процедуры

{
  "entities": {
    "RunJob": {
      "source": {
        "object": "dbo.RunJob",
        "type": "stored-procedure",
        "parameters": {
          "apiKey": "@akv('job-runner-apikey')"
        }
      },
      "permissions": [
        { "role": "anonymous", "actions": [ "execute" ] }
      ]
    }
  }
}

Устранение неполадок

Симптом Этапы
Секрет не найден Проверьте имя, наличие в хранилище и идентификационные разрешения
Недопустимое значение повторных попыток Используйте положительное целое число или удалите для использования значений по умолчанию
Обновление конфигурации завершается сбоем Проверка журналов ошибок проверки
@akv() не заменено Подтвердите конечную точку, имя секрета и что разрешение секрета включено
401/403 из Key Vault Проверка назначения учётных записей и прав доступа

Полный пример конфигурации

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@akv('primary-sql-connection')"
  },
  "azure-key-vault": {
    "endpoint": "https://my-vault.vault.azure.net/",
    "retry-policy": {
      "mode": "exponential",
      "max-count": 5,
      "delay-seconds": 2,
      "max-delay-seconds": 30,
      "network-timeout-seconds": 45
    }
  },
  "runtime": {
    "rest": { "enabled": true }
  },
  "entities": {
    "Books": {
      "source": "dbo.Books",
      "permissions": [
        { "role": "anonymous", "actions": [ "read" ] }
      ]
    }
  }
}

Пример файла .akv:

primary-sql-connection=Server=localhost;Database=BooksDb;User Id=app;Password=password;

Это важно

Не фиксируйте .akv файлы, содержащие секреты. |

Краткий справочник

Item Сводка
Синтаксис @akv('secret-name')
Требуется конечная точка Да
Файл моделирования .akvс линиями name=value
Сочетание с @env() Supported.

Отзыв

Используйте @akv() для разрешения секретов из Azure Key Vault. Настройте политики повторных попыток для надежности и используйте .akv файлы для имитации секретов в разработке. Это позволяет избегать попадания конфиденциальных значений в файлы конфигурации, поддерживая согласованные рабочие процессы разработки и производственной среды.

  • Last updated on