Поделиться через

интеграция .NET AspireAzure Key Vault

  • Статья

Из этой статьи вы узнаете, как использовать интеграцию .NET AspireAzure Key Vault. Библиотека интеграции Aspire.Azure.Key.Vault используется для регистрации SecretClient в контейнере DI для подключения к Azure Key Vault. Он также включает соответствующие проверки работоспособности, ведение журнала и телеметрию.

Начало работы

Чтобы приступить к интеграции .NET AspireAzure Key Vault, установите пакет NuGet 📦Aspire.Azure.Security.KeyVault в проект клиента, то есть в проект приложения, которое использует клиента Azure Key Vault.

dotnet add package Aspire.Azure.Security.KeyVault

Дополнительные сведения см. в dotnet add package или Управление зависимостями пакетов в приложениях .NET.

Пример использования

В следующих разделах описаны различные примеры использования.

Добавление секретов в конфигурацию

В файле Program.cs вашего проекта, использующего клиент, вызовите расширение AddAzureKeyVaultSecrets, чтобы добавить секреты из Azure Key Vault в конфигурацию приложения. Метод принимает параметр имени подключения.

builder.Configuration.AddAzureKeyVaultSecrets("secrets");

Затем можно получить секрет с помощью обычных API-интерфейсов IConfiguration. Например, чтобы получить секрет из службы, выполните приведенные ниже действия.

public class ExampleService(IConfiguration configuration)
{
    string secretValue = configuration["secretKey"];
    // Use secretValue ...
}

Используйте SecretClient

Кроме того, можно использовать SecretClient для получения секретов по запросу. В файле Program.cs проекта, используюющего клиент, вызовите расширение AddAzureKeyVaultClient, чтобы зарегистрировать SecretClient для использования с помощью контейнера внедрения зависимостей.

builder.AddAzureKeyVaultClient("secrets");

Затем можно получить экземпляр SecretClient с помощью внедрения зависимостей. Например, чтобы получить клиента из службы.

public class ExampleService(SecretClient client)
{
    // Use client...
}

Использование узла приложения

Чтобы добавить поддержку размещения Azure Key Vault в IDistributedApplicationBuilder, установите пакет NuGet 📦Aspire.Hosting.Azure.KeyVault в проекте хоста приложения .

dotnet add package Aspire.Hosting.Azure.KeyVault

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

var builder = DistributedApplication.CreateBuilder(args);

var secrets = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureKeyVault("secrets")
    : builder.AddConnectionString("secrets");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(secrets)

Предыдущий код условно добавляет ресурс Azure Key Vault в проект на основе контекста выполнения. Если узел приложения выполняется в режиме публикации, ресурс добавляется; в противном случае добавляется строка подключения к существующему ресурсу.

Конфигурация

Интеграция .NET AspireAzure Key Vault предоставляет несколько вариантов настройки SecretClient на основе требований и соглашений проекта.

Использование поставщиков конфигураций

Интеграция .NET AspireAzure Key Vault поддерживает Microsoft.Extensions.Configuration. Он загружает AzureSecurityKeyVaultSettings из appsettings.json или других файлов конфигурации с помощью ключа Aspire:Azure:Security:KeyVault.

{
  "Aspire": {
    "Azure": {
      "Security": {
        "KeyVault": {
          "VaultUri": "YOUR_VAULT_URI",
          "DisableHealthChecks": false,
          "DisableTracing": true,
          "ClientOptions": {
            "DisableChallengeResourceVerification": true
          }
        }
      }
    }
  }
}

Если вы настроили конфигурации в разделе Aspire:Azure:Security:KeyVault файла appsettings.json, можно просто вызвать метод AddAzureKeyVaultSecrets без передачи параметров.

Использование встроенных делегатов

Вы также можете передать делегат Action<AzureSecurityKeyVaultSettings> для настройки некоторых или всех встроенных параметров, например, чтобы задать VaultUri:

builder.AddAzureKeyVaultSecrets(
    "secrets",
    static settings => settings.VaultUri = new Uri("YOUR_VAULTURI"));

Совет

Имя API AddAzureKeyVaultSecrets вызвало немного путаницы. Метод используется для настройки SecretClient, а не для добавления секретов в конфигурацию.

Вы также можете настроить SecretClientOptions с помощью делегата Action<IAzureClientBuilder<SecretClient, SecretClientOptions>>, второго параметра метода AddAzureKeyVaultSecrets. Например, чтобы задать идентификатор KeyClientOptions.DisableChallengeResourceVerification для идентификации клиента:

builder.AddAzureKeyVaultSecrets(
    "secrets",
    static clientBuilder =>
        clientBuilder.ConfigureOptions(
            static options => options.DisableChallengeResourceVerification = true))

Параметры конфигурации

Следующие настраиваемые параметры предоставляются через класс AzureSecurityKeyVaultSettings:

Имя Описание
VaultUri Универсальный код ресурса (URI) в хранилище, в котором работает клиент. Отображается как DNS-имя на портале Azure.
Credential Учетные данные, используемые для аутентификации в Azure Key Vault.
DisableHealthChecks Логическое значение, указывающее, отключена ли проверка работоспособности Key Vault.
DisableTracing Логическое значение, указывающее, отключена ли трассировка OpenTelemetry.

Проверки здоровья

По умолчанию .NET.NET Aspire интеграции включают проверки работоспособности для всех сервисов. Дополнительные сведения см. в обзоре интеграции .NET.NET Aspire.

Интеграция .NET AspireAzure Key Vault включает следующие проверки работоспособности:

  • Добавляет проверку работоспособности AzureKeyVaultSecretsHealthCheck, которая пытается подключиться к Key Vault и выполнить его запрос.
  • Интегрируется с конечной точкой HTTP /health, которая указывает, что все зарегистрированные проверки работоспособности должны пройти, чтобы приложение считалось готовым к приему трафика.

Наблюдаемость и телеметрия

.NET .NET Aspire интеграции автоматически настраивают конфигурации ведения журналов, трассировки и метрики, которые иногда называются основами наблюдаемости. Дополнительные сведения об наблюдаемости интеграции и телеметрии см. в .NET.NET Aspire обзоре интеграции. В зависимости от резервной службы некоторые интеграции могут поддерживать только некоторые из этих функций. Например, некоторые интеграции поддерживают ведение журнала и трассировку, но не метрики. Функции телеметрии также можно отключить с помощью методов, представленных в разделе конфигурации .

Лесозаготовка

Интеграция .NET AspireAzure Key Vault использует следующие категории журналов:

  • Azure.Core
  • Azure.Identity

Отслеживание

Интеграция .NET AspireAzure Key Vault будет выполнять следующие операции трассировки с помощью OpenTelemetry:

  • "Azure.Security.KeyVault.Secrets.SecretClient"

Метрика

Интеграция .NET AspireAzure Key Vault в настоящее время не поддерживает метрики по умолчанию из-за ограничений пакета SDK Azure.

См. также