.NET Aspire Azure Key Vault 통합

아티클
2025-04-17

포함: 호스팅 통합 -&— Client 통합

Azure Key Vault 비밀을 안전하게 저장하고 액세스하기 위한 클라우드 서비스입니다. .NET Aspire Azure Key Vault 통합을 사용하면 Azure Key Vault 애플리케이션에서 .NET 인스턴스에 연결할 수 있습니다.

호스팅 통합

Azure Key Vault 호스팅 통합은 Key Vault 리소스를 AzureKeyVaultResource 형식으로 모델화합니다. 앱 호스트 프로젝트 내에서 이 형식과 API를 표현하기 위해, 📦Aspire호스팅.Azure.KeyVault NuGet 패키지를 설치하십시오.

.NET CLI
패키지 참조

dotnet add package Aspire.Hosting.Azure.KeyVault

<PackageReference Include="Aspire.Hosting.Azure.KeyVault"
                  Version="*" />

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

Azure Key Vault 리소스 추가

앱 호스트 프로젝트에서 작성기 인스턴스에서 AddAzureKeyVault 호출하여 Azure Key Vault 리소스를 추가합니다.

var builder = DistributedApplication.CreateBuilder(args);

var keyVault = builder.AddAzureKeyVault("key-vault");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(keyVault);

// After adding all resources, run the app...

WithReference 메서드는 ExampleProject 중에서 "key-vault"라는 연결을 구성합니다.

중요합니다

기본적으로 AddAzureKeyVault은(는) 기본 제공 Key Vault 관리자 역할을(를) 구성합니다.

조언

AddAzureKeyVault호출할 때 암시적으로 AddAzureProvisioning호출합니다. 그러면 앱 시작 중에 동적으로 Azure 리소스 생성에 대한 지원이 추가됩니다. 앱은 적절한 구독 및 위치를 구성해야 합니다. 자세한 내용은 로컬 프로비저닝: 구성참조하세요.

프로비저닝에 의해 생성된 Bicep

Bicep 에 대해 처음 접하신다면, 이는 Azure 리소스를 정의하기 위한 도메인별 언어입니다. .NET .NET Aspire사용하면 Bicep을 직접 작성할 필요가 없으며 프로비전 API는 Bicep을 생성합니다. 앱을 게시하면 생성된 Bicep이 매니페스트 파일과 함께 출력됩니다. Azure Key Vault 리소스를 추가할 때, 다음의 Bicep 코드가 생성됩니다.

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

resource key_vault 'Microsoft.KeyVault/vaults@2023-07-01' = {
  name: take('keyvault-${uniqueString(resourceGroup().id)}', 24)
  location: location
  properties: {
    tenantId: tenant().tenantId
    sku: {
      family: 'A'
      name: 'standard'
    }
    enableRbacAuthorization: true
  }
  tags: {
    'aspire-resource-name': 'key-vault'
  }
}

output vaultUri string = key_vault.properties.vaultUri

output name string = key_vault.name

위의 Bicep은 리소스를 프로비전하는 모듈입니다 Azure Key Vault . 또한 별도의 모듈에서 리소스에 Azure 대한 역할 할당을 만듭니다.

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param key_vault_outputs_name string

param principalType string

param principalId string

resource key_vault 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
  name: key_vault_outputs_name
}

resource key_vault_KeyVaultSecretsUser 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(key_vault.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6')
    principalType: principalType
  }
  scope: key_vault
}

생성된 Bicep은 시작 지점이며 C#의 프로비저닝 인프라 변경의 영향을 받습니다. Bicep 파일에 대한 사용자 지정은 직접 덮어쓰여지므로 C# 프로비저닝 API를 통해 변경하여 생성된 파일에 반영되도록 합니다.

프로비저닝 인프라 사용자 지정

모든 .NET AspireAzure 리소스는 AzureProvisioningResource 형식의 하위 클래스입니다. 이 형식을 사용하면 Azure API를 사용하여 ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) 리소스를 구성하는 흐름 API를 제공하여 생성된 Bicep을 사용자 지정할 수 있습니다. 예를 들어 sku, RBAC, tags등을 구성할 수 있습니다. 다음 예제에서는 Azure Key Vault 리소스를 사용자 지정하는 방법을 보여 줍니다.

builder.AddAzureKeyVault("key-vault")
    .ConfigureInfrastructure(infra =>
    {
        var keyVault = infra.GetProvisionableResources()
                            .OfType<KeyVaultService>()
                            .Single();

        keyVault.Properties.Sku = new()
        {
            Family = KeyVaultSkuFamily.A,
            Name = KeyVaultSkuName.Premium,
        };
        keyVault.Properties.EnableRbacAuthorization = true;
        keyVault.Tags.Add("ExampleKey", "Example value");
    });

앞의 코드는 다음과 같습니다.

ConfigureInfrastructure API에 대한 호출을 연결합니다.
- infra 매개 변수는 AzureResourceInfrastructure 형식의 인스턴스입니다.
- 프로비전 가능한 리소스는 GetProvisionableResources() 메서드를 호출하여 검색됩니다.
- 단일 KeyVaultService 리소스가 검색됩니다.
- Sku 속성은 새 KeyVaultSku 인스턴스로 설정됩니다.
- KeyVaultProperties.EnableRbacAuthorization 속성은 true로 설정됩니다.
- 태그는 ExampleKey 키와 Example value값을 사용하여 리소스에 추가됩니다.

Key Vault 리소스를 사용자 지정하는 데 사용할 수 있는 더 많은 구성 옵션이 있습니다. 자세한 내용은 Azure.Provisioning.KeyVault 및 Azure를 참조하세요. 프로비저닝 사용자 지정.

기존 Azure Key Vault 인스턴스에 연결

연결하려는 기존 Azure Key Vault 인스턴스가 있을 수 있습니다. 새 Azure Key Vault 리소스를 나타내는 대신 앱 호스트에 연결 문자열을 추가할 수 있습니다. 기존 Azure Key Vault 리소스에 대한 연결을 추가하려면 AddConnectionString 메서드를 호출합니다.

var builder = DistributedApplication.CreateBuilder(args);

var keyVault = builder.AddConnectionString("key-vault");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(keyVault);

// After adding all resources, run the app...

메모

연결 문자열은 데이터베이스 연결, 메시지 브로커, 엔드포인트 URI 및 기타 서비스를 비롯한 광범위한 연결 정보를 나타내는 데 사용됩니다. .NET .NET Aspire 명명법에서 "연결 문자열"이라는 용어는 모든 종류의 연결 정보를 나타내는 데 사용됩니다.

연결 문자열은 앱 호스트의 구성에서 구성되며, 일반적으로 섹션의 ConnectionStrings아래에 구성됩니다. 앱 호스트는 이 연결 문자열을 환경 변수로 모든 종속 리소스에 삽입합니다. 예를 들면 다음과 같습니다.

{
  "ConnectionStrings": {
    "key-vault": "https://{account_name}.vault.azure.net/"
  }
}

종속 리소스는 GetConnectionString 메서드를 호출하고 연결 이름을 매개 변수로 전달하여 삽입된 연결 문자열에 액세스할 수 있습니다. 이 경우 "key-vault". GetConnectionString API는 IConfiguration.GetSection("ConnectionStrings")[name]의 줄임말입니다.

Client 통합

.NET Aspire Azure Key Vault 클라이언트 통합을 시작하려면 📦Aspire및Azure.Security.KeyVault NuGet 패키지를 설치하십시오. 이는 Azure Key Vault 클라이언트를 사용하는 애플리케이션의 프로젝트, 즉 클라이언트 사용 프로젝트에 해당합니다.

.NET CLI
패키지 참조

dotnet add package Aspire.Azure.Security.KeyVault

<PackageReference Include="Aspire.Azure.Security.KeyVault"
                  Version="*" />

클라이언트 통합은 Azure Key Vault비밀에 액세스하는 두 가지 방법을 제공합니다.

IConfiguration 또는 IOptions<T> 패턴을 사용하여 앱 구성에 비밀을 추가합니다.
SecretClient를 사용하여 요청 시 비밀 정보를 확인합니다.

구성에 비밀 추가

클라이언트를 사용하는 프로젝트의 Program.cs 파일에서, AddAzureKeyVaultSecrets의 IConfiguration 확장 메서드를 호출하여 비밀을 앱 구성의 일부로 추가합니다. 메서드는 연결 이름 매개 변수를 사용합니다.

builder.Configuration.AddAzureKeyVaultSecrets(connectionName: "key-vault");

메모

AddAzureKeyVaultSecrets API 이름으로 인해 약간의 혼란이 발생했습니다. 이 메서드는 지정된 연결 이름을 기반으로 SecretClient 구성하는 데 사용되며 구성에 비밀을 추가하는 데 사용되지 않습니다.

조언

connectionName 매개 변수는 앱 호스트 프로젝트에서 Azure Key Vault 리소스를 추가할 때 사용되는 이름과 일치해야 합니다. 자세한 사항은 에서 Azure Key Vault 리소스를 추가하는 방법을 참조하세요.

그런 다음 일반 IConfiguration API를 사용하거나 옵션 패턴을 사용하여 강력한 형식의 클래스에 바인딩함으로써 비밀 기반 구성 값을 검색할 수 있습니다. 종속성 주입 컨테이너에 등록된 예제 서비스 클래스에서 비밀을 검색하려면 다음 코드 조각을 고려합니다.

`IConfiguration` 인스턴스 검색

public class ExampleService(IConfiguration configuration)
{
    // Use configuration...
    private string _secretValue = configuration["SecretKey"];
}

앞의 예제에서는 종속성 주입을 위해 IConfiguration 인스턴스도 등록했다고 가정합니다. 자세한 내용은 종속성 주입을 .NET에서 참조하세요.

`IOptions<T>` 인스턴스 검색

public class ExampleService(IOptions<SecretOptions> options)
{
    // Use options...
    private string _secretValue = options.Value.SecretKey;
}

앞의 예제에서는 옵션 패턴에 사용할 SecretOptions 클래스를 구성한 것으로 가정합니다. 자세한 내용은 옵션 패턴을 .NET에서 참조하세요.

추가 AddAzureKeyVaultSecrets API 매개 변수는 다음 시나리오에 대해 선택적으로 사용할 수 있습니다.

Action<AzureSecurityKeyVaultSettings>? configureSettings: 일부 또는 모든 옵션을 인라인으로 설정합니다.
Action<SecretClientOptions>? configureClientOptions: SecretClientOptions을 인라인으로 설정합니다.
AzureKeyVaultConfigurationOptions? options: AzureKeyVaultConfigurationOptions을 인라인으로 설정합니다.

Azure 비밀 클라이언트 추가

또는 SecretClient 직접 사용하여 요청 시 비밀을 검색할 수 있습니다. 이렇게 하려면 약간 다른 등록 API가 필요합니다.

클라이언트 사용 프로젝트의 Program.cs 파일에서 AddAzureKeyVaultClient 인스턴스의 IHostApplicationBuilder 확장을 호출하여 종속성 주입 컨테이너를 통해 사용할 SecretClient 등록합니다.

builder.AddAzureKeyVaultClient(connectionName: "key-vault");

조언

작성기에서 SecretClient 추가한 후 종속성 주입을 사용하여 SecretClient 인스턴스를 가져올 수 있습니다. 예를 들어 예제 서비스에서 클라이언트를 검색하려면 클라이언트를 생성자 매개 변수로 정의하고 ExampleService 클래스가 종속성 주입 컨테이너에 등록되었는지 확인합니다.

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

종속성 주입에 대한 자세한 내용은 .NET 종속성 주입참조하세요.

키가 할당된 Azure Key Vault 클라이언트 추가

여러 SecretClient 인스턴스를 서로 다른 연결 이름으로 등록하려는 경우가 있을 수 있습니다. 키 Azure Key Vault 클라이언트를 등록하려면 AddKeyedAzureKeyVaultClient 메서드를 호출합니다.

builder.AddKeyedAzureKeyVaultClient(name: "feature-toggles");
builder.AddKeyedAzureKeyVaultClient(name: "admin-portal");

그런 다음 종속성 주입을 사용하여 SecretClient 인스턴스를 검색할 수 있습니다. 예를 들어 예제 서비스에서 클라이언트를 검색하려면 다음을 수행합니다.

public class ExampleService(
    [FromKeyedServices("feature-toggles")] SecretClient featureTogglesClient,
    [FromKeyedServices("admin-portal")] SecretClient adminPortalClient)
{
    // Use clients...
}

키가 지정된 서비스에 대한 자세한 내용은 .NET 종속성 주입: 키가 지정된 서비스를 참조하세요.

구성

.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": {
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "Diagnostics": {
              "ApplicationId": "myapp"
            }
          }
        }
      }
    }
  }
}

전체 Azure Key Vault 클라이언트 통합 JSON 스키마는 Aspire참조하세요.Azure. Security.KeyVault/ConfigurationSchema.json.

Aspire:Azure:Security:KeyVault 파일의 appsettings.json 섹션에서 구성을 설정한 경우 매개 변수를 전달하지 않고 메서드 AddAzureKeyVaultSecrets 호출하면 됩니다.

인라인 대리자 사용

Action<AzureSecurityKeyVaultSettings> 대리자를 전달하여 일부 또는 모든 옵션을 인라인으로 설정할 수도 있습니다( 예: AzureSecurityKeyVaultSettings.VaultUri설정).

builder.AddAzureKeyVaultSecrets(
    connectionName: "key-vault",
    configureSettings: settings => settings.VaultUri = new Uri("KEY_VAULT_URI"));

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

builder.AddAzureKeyVaultSecrets(
    connectionName: "key-vault",
    configureClientOptions: options => options.DisableChallengeResourceVerification = true))

구성 옵션

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

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

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의 제한 사항으로 인해 기본적으로 메트릭을 지원하지 않습니다.