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

интеграция .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.

Client контроль состояния интеграции

По умолчанию в интеграциях клиентов .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.

См. также