다음을 통해 공유

.NET Aspire Azure Key Vault 통합

  • 아티클

이 문서에서는 .NET AspireAzure Key Vault 통합을 사용하는 방법을 알아봅니다. Aspire.Azure.Key.Vault 통합 라이브러리는 SecretClient에 연결하기 위해 Azure Key Vault을 DI 컨테이너에 등록하는 데 사용됩니다. 또한 관련 건강 점검을 가능하게 하며, 로그 기록 및 원격 분석을 활성화합니다.

시작

.NET Aspire Azure Key Vault 통합을 시작하려면, 먼저 📦Aspire와Azure.Security.KeyVault NuGet 패키지를 설치해야 합니다. 이러한 설치는 Azure Key Vault 클라이언트를 사용하는 애플리케이션의 클라이언트 소비 프로젝트에서 수행됩니다.

dotnet add package Aspire.Azure.Security.KeyVault

자세한 내용은 dotnet add package 또는 .NET 애플리케이션에서 패키지 종속성을 관리하기.

예제 사용

다음 섹션에서는 다양한 예제 사용을 설명합니다.

구성에 비밀 추가

클라이언트가 사용하는 프로젝트의 Program.cs 파일에서 AddAzureKeyVaultSecrets 확장을 호출하여 Azure Key Vault 비밀 정보를 애플리케이션의 설정에 추가합니다. 메서드는 연결 이름 매개 변수를 사용합니다.

builder.Configuration.AddAzureKeyVaultSecrets("secrets");

그런 다음 일반 IConfiguration API를 통해 비밀을 검색할 수 있습니다. 예를 들어 서비스에서 비밀을 검색하려면 다음을 수행합니다.

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 호스팅 지원을 추가하려면, 📦 프로젝트에서 AspireAzure.Hosting..KeyVault. NuGet 패키지를 설치하십시오.

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 Aspire Azure Key Vault 통합은 프로젝트의 요구 사항 및 규칙에 따라 SecretClient 구성하는 여러 옵션을 제공합니다.

구성 공급자 사용

.NET Aspire Azure 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"));

조언

AddAzureKeyVaultSecrets API 이름으로 인해 약간의 혼란이 발생했습니다. 이 메서드는 비밀을 추가하지 않고 SecretClient를 구성하는 데 사용됩니다.

SecretClientOptions 메서드의 두 번째 매개 변수인 Action<IAzureClientBuilder<SecretClient, SecretClientOptions>> 대리자를 사용하여 AddAzureKeyVaultSecrets 설정할 수도 있습니다. 예를 들어 KeyClientOptions.DisableChallengeResourceVerification ID를 설정하여 클라이언트를 식별합니다.

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

구성 옵션

다음 구성 가능한 옵션은 AzureSecurityKeyVaultSettings 클래스를 통해 노출됩니다.

이름 묘사
VaultUri 클라이언트가 작동하는 보관소에 대한 URI입니다. Azure 포털에서 "DNS 이름"으로 나타납니다.
Credential Azure Key Vault인증하는 데 사용되는 자격 증명입니다.
DisableHealthChecks Key Vault 상태 검사가 비활성화되었는지 여부를 나타내는 부울 값입니다.
DisableTracing OpenTelemetry 추적이 비활성화되었는지를 나타내는 부울 값입니다.

Client 통합 시스템 상태 점검

기본적으로 .NET.NET Aspire클라이언트 통합에는 모든 서비스에 대해 상태 검사 사용하도록 설정될 있습니다. 마찬가지로, 많은 .NET.NET Aspire호스팅 통합도 상태 검사 엔드포인트를 제공할. 자세한 내용은 다음을 참조하세요.

.NET Aspire Azure Key Vault 통합에는 다음 상태 검사가 포함됩니다.

  • Key Vault에 연결하고 쿼리하는 AzureKeyVaultSecretsHealthCheck 상태 검사를 추가합니다.
  • /health HTTP 엔드포인트와 통합되어 있으며, 이는 등록된 모든 상태 검사를 통과해야 앱이 트래픽 수신 준비가 완료된 것으로 간주됨을 의미합니다.

관찰 가능성 및 원격 분석

.NET .NET Aspire 통합은 로깅, 추적 및 메트릭 구성을 자동으로 설정하며, 이를 관찰성의 핵심 요소라고도 이라고 일컫습니다. 통합 관찰 가능성 및 원격 분석에 대한 자세한 내용은 .NET.NET Aspire 통합 개요참조하세요. 지원 서비스에 따라 일부 통합은 이러한 기능 중 일부만 지원할 수 있습니다. 예를 들어 일부 통합은 로깅 및 추적을 지원하지만 메트릭은 지원하지 않습니다. 구성 섹션에 제시된 기술을 사용하여 원격 분석 기능을 사용하지 않도록 설정할 수도 있습니다.

로깅

.NET Aspire Azure Key Vault 통합은 다음 로그 범주를 사용합니다.

  • Azure.Core
  • Azure.Identity

추적

.NET Aspire Azure Key Vault 통합은 OpenTelemetry를 사용하여 다음과 같은 추적 활동을 발생시킵니다.

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

측정 지표

.NET Aspire Azure Key Vault 통합은 현재 Azure SDK의 제한 사항으로 인해 기본적으로 메트릭을 지원하지 않습니다.

참고: