Azure App Configuration은 개발자가 애플리케이션 구성을 간단하고 안전하게 중앙 집중화하도록 도와주는 관리형 서비스입니다. Go 구성 공급자 라이브러리를 사용하면 관리되는 방식으로 Azure App Configuration 저장소에서 구성을 로드할 수 있습니다. 이 클라이언트 라이브러리는 Go용 Azure SDK를 기반으로 추가 기능을 추가합니다.
구성 로드
Azure App Configuration Go 공급자를 사용하면 Azure App Configuration 저장소에서 Go 애플리케이션으로 구성 값을 로드할 수 있습니다. Microsoft Entra ID 인증 또는 연결 문자열을 사용하여 연결할 수 있습니다.
Go 구성 공급자를 사용하려면 패키지를 설치합니다.
go get github.com/Azure/AppConfiguration-GoProvider/azureappconfiguration
Load 패키지에서 azureappconfiguration 함수를 호출하여 Azure App Configuration에서 구성을 로드합니다. 이 Load 함수는 인증 옵션 및 구성 옵션을 수락하여 로드 동작을 사용자 지정합니다.
DefaultAzureCredential와 다른 토큰 자격 증명 구현을 사용하여 App Configuration 저장소에 인증할 수 있습니다.
지침에 따라 자격 증명에 App Configuration Data Reader 역할을 할당합니다.
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/Azure/AppConfiguration-GoProvider/azureappconfiguration"
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
)
func main() {
ctx := context.Background()
// Get the endpoint from environment variable
endpoint := os.Getenv("AZURE_APPCONFIG_ENDPOINT")
// Create a credential using DefaultAzureCredential
credential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
log.Fatalf("Failed to create credential: %v", err)
}
// Set up authentication options
authOptions := azureappconfiguration.AuthenticationOptions{
Endpoint: endpoint,
Credential: credential,
}
// Load configuration from Azure App Configuration
appConfig, err := azureappconfiguration.Load(ctx, authOptions, nil)
if err != nil {
log.Fatalf("Failed to load configuration: %v", err)
}
}
선택기를 사용하여 특정 키 값 로드
기본적으로 구성 공급자는 App Configuration의 레이블 없이 모든 키-값을 로드합니다.
Selectors 구조체에서 Options 필드를 구성하여 키 값을 선택적으로 로드할 수 있습니다.
options := &azureappconfiguration.Options{
Selectors: []azureappconfiguration.Selector{
{
// Load configuration values with prefix "App:" and no label
KeyFilter: "App:*",
LabelFilter: "",
},
{
// Load configuration values with prefix "App:" and "Prod" label
KeyFilter: "App:*",
LabelFilter: "Prod",
},
},
}
appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)
Selector 구조체는 다음 필드를 지원합니다.
-
KeyFilter: 포함할 구성 키를 결정합니다. 정확한 일치 항목,
*와 접두사 일치 또는 쉼표로 구분된 여러 키를 사용합니다. - LabelFilter: 특정 레이블이 있는 키 값을 선택합니다. 비어 있는 경우 레이블이 없는 키 값을 로드합니다.
비고
여러 선택기에 겹치는 키가 포함된 경우 이후 선택기가 이전 선택기보다 우선합니다.
태그 필터
매개 변수는 TagFilters 특정 태그가 있는 키-값을 선택합니다. 키-값은 필터에 지정된 모든 태그와 해당 값이 있는 경우에만 로드됩니다.
options := &azureappconfiguration.Options{
Selectors: []azureappconfiguration.Selector{
{
// Load configuration values with prefix "App:" and specific tags
KeyFilter: "App:*",
TagFilters: []string{"env=prod"},
},
},
}
appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)
비고
문자 별표(*), 쉼표(,), 및 백슬래시(\)는 예약 문자이며, 태그 필터에서 사용할 때는 백슬래시로 이스케이프해야 합니다.
키에서 접두사 자르기
특정 접두사를 사용하여 구성 값을 로드할 때 TrimKeyPrefixes 옵션을 사용하여 구성의 키에서 이러한 접두사를 제거할 수 있습니다. 애플리케이션에 더 깔끔한 설정 키를 만들고, 동시에 App Configuration 저장소의 구성을 체계적으로 유지할 수 있습니다.
options := &azureappconfiguration.Options{
// Load configuration values with prefix "TestApp:" and trim the prefix
Selectors: []azureappconfiguration.Selector{
{
KeyFilter: "TestApp:*",
},
},
TrimKeyPrefixes: []string{"TestApp:"},
}
appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)
예를 들어, App Configuration 저장소에 TestApp:Settings:Message라는 키가 포함되어 있으면, Settings:Message 접두사를 제거한 후 애플리케이션에서 TestApp:로 액세스할 수 있습니다.
JSON 콘텐츠 형식 처리
App Configuration에서 JSON 키 값을 만들 수 있습니다. 콘텐츠 형식 "application/json"의 키-값을 읽으면 구성 공급자가 중첩된 구조로 구문 분석합니다. 자세한 내용은 콘텐츠 형식을 사용하여 App Configuration에서 JSON 키 값을 저장하는 방법을 참조하세요.
비고
버전 1.2.0부터 구성 제공자는 application/json 콘텐츠 유형을 가진 키-값에 대해 (JSONC)에 정의된 대로 주석을 허용합니다.
구성 사용
AzureAppConfiguration 함수에서 반환되는 Load 형식은 구성 데이터에 액세스하는 몇 가지 메서드를 제공합니다.
구조체에 대한 역 마샬링
Unmarshal 메서드는 Go 구조체에 구성 값을 로드하는 형식 안전한 방법을 제공합니다. 이 방법을 사용하면 런타임 오류가 잘못 입력된 구성 키를 방지하고 코드를 더 쉽게 유지 관리할 수 있습니다. 이 메서드는 구성 키를 구조체 필드에 매핑하는 방법을 사용자 지정하는 선택적 ConstructionOptions 매개 변수를 허용합니다.
type Config struct {
Message string
App struct {
Name string
Debug bool
Settings struct {
Timeout int
RetryCount int
}
}
}
func main() {
// ... load configuration ...
// Create a configuration struct and unmarshal into it
var config Config
if err := appConfig.Unmarshal(&config, nil); err != nil {
log.Fatalf("Failed to unmarshal configuration: %v", err)
}
// Access configuration values
fmt.Printf("Message: %s\n", config.Message)
fmt.Printf("App Name: %s\n", config.App.Name)
fmt.Printf("Debug Mode: %t\n", config.App.Debug)
fmt.Printf("Timeout: %d seconds\n", config.App.Settings.Timeout)
}
사용자 지정 키 구분 기호
ConstructionOptions를 사용하여 구성 키를 구조체 필드에 매핑하는 방법을 사용자 지정할 수 있습니다. 이는 구성 키가 기본 점(.)과 다른 구분 기호를 사용하는 경우에 유용합니다.
// Configuration keys using colon separator: "App:Name", "App:Settings:Timeout"
constructionOptions := &azureappconfiguration.ConstructionOptions{
Separator: ":",
}
var config Config
if err := appConfig.Unmarshal(&config, constructionOptions); err != nil {
log.Fatalf("Failed to unmarshal configuration: %v", err)
}
ConstructionOptions 구조체는 ., ,, ;, -, _, __, /, : 구분 기호 를 지원합니다. 지정하지 않으면 . 기본 구분 기호가 사용됩니다.
원시 JSON 바이트 가져오기
GetBytes 메서드는 구성을 원시 JSON 데이터로 검색하여 JSON 처리 라이브러리 또는 viper 같은 구성 프레임워크와 통합하기 위한 유연성을 제공합니다. 이 메서드는 키 계층 매핑을 제어하는 선택적 ConstructionOptions 매개 변수도 허용합니다.
// Get configuration as JSON bytes with default separator
jsonBytes, err := appConfig.GetBytes(nil)
if err != nil {
log.Fatalf("Failed to get configuration as bytes: %v", err)
}
fmt.Println("Raw JSON Configuration:")
fmt.Println(string(jsonBytes))
// Get configuration with custom separator
constructionOptions := &azureappconfiguration.ConstructionOptions{
Separator: ":",
}
jsonBytes, err = appConfig.GetBytes(constructionOptions)
if err != nil {
log.Fatalf("Failed to get configuration as bytes: %v", err)
}
// Example: Use with viper
v := viper.New()
v.SetConfigType("json")
if err := v.ReadConfig(bytes.NewBuffer(jsonBytes)); err != nil {
log.Fatalf("Failed to read config into viper: %v", err)
}
구성 새로 고침
새로 고침을 구성하면 애플리케이션이 다시 시작하지 않고도 App Configuration 저장소에서 최신 값을 끌어올 수 있습니다.
RefreshOptions 구조체의 Options 필드를 사용하여 새로 고침 옵션을 구성할 수 있습니다. 서버에서 선택한 키-값의 변경 내용이 검색되면 로드된 구성이 업데이트됩니다. 기본 새로 고침 간격은 30초이지만 Interval 속성으로 이를 재정의할 수 있습니다.
options := &azureappconfiguration.Options{
// Load all keys that start with `TestApp:` and have no label
Selectors: []azureappconfiguration.Selector{
{
KeyFilter: "TestApp:*",
LabelFilter: "",
},
},
// Trigger full configuration refresh when any selected key changes
RefreshOptions: azureappconfiguration.KeyValueRefreshOptions{
Enabled: true,
// Check for changes no more often than every 60 seconds
Interval: 60 * time.Second,
},
}
appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)
RefreshOptions 하나만 설정해도 구성이 자동으로 새로 고쳐지지는 않습니다. 새로 고침을 트리거하려면 Refresh 인스턴스에서 AzureAppConfiguration 메서드를 호출해야 합니다.
// Trigger a refresh
if err := appConfig.Refresh(ctx); err != nil {
log.Printf("Failed to refresh configuration: %v", err)
}
이 디자인은 애플리케이션이 유휴 상태일 때 App Configuration에 대한 불필요한 요청을 방지합니다. 애플리케이션 활동이 발생하는 Refresh 호출을 포함해야 합니다. 이를 활동 기반 구성 새로 고침이라고 합니다. 예를 들어 들어오는 요청을 처리할 때 또는 복잡한 작업을 수행하는 반복 내에서 Refresh을(를) 호출할 수 있습니다.
비고
어떤 이유로든 새로 고침 호출이 실패하더라도 애플리케이션은 캐시된 구성을 계속 사용합니다. 구성된 새로 고침 간격이 통과되고 새로 고침 호출이 애플리케이션 활동에 의해 트리거되면 또 다른 시도가 수행됩니다.
Refresh를 호출하는 것은 구성된 새로 고침 간격이 지나기 전에 작동하지 않으므로 자주 호출하더라도 성능에 미치는 영향은 최소화됩니다.
sentinel 키에서 새로 고침
sentinel 키는 다른 모든 키의 변경을 완료한 후 업데이트하는 키입니다. 구성 공급자는 선택한 모든 키 값 대신 sentinel 키를 모니터링합니다. 변경이 감지되면 앱이 모든 구성 값을 새로 고칩니다.
이 방법은 여러 키-값을 업데이트할 때 유용합니다. 다른 모든 구성 변경이 완료된 후에만 sentinel 키를 업데이트하면 애플리케이션이 구성을 한 번만 다시 로드하고 일관성을 유지합니다.
options := &azureappconfiguration.Options{
// Load all keys that start with `TestApp:` and have no label
Selectors: []azureappconfiguration.Selector{
{
KeyFilter: "TestApp:*",
LabelFilter: "",
},
},
// Trigger full configuration refresh only if the `SentinelKey` changes
RefreshOptions: azureappconfiguration.KeyValueRefreshOptions{
Enabled: true,
WatchedSettings: []azureappconfiguration.WatchedSetting{
{
Key: "SentinelKey",
Label: "",
},
},
},
}
사용자 지정 새로 고침 콜백
OnRefreshSuccess 메서드는 구성이 성공적으로 새로 고쳐지고 실제 변경 내용이 감지될 때마다 실행될 콜백 함수를 등록합니다.
var config Config
if err := appConfig.Unmarshal(&config, nil); err != nil {
log.Fatalf("Failed to unmarshal configuration: %v", err)
}
// Register refresh callback
appConfig.OnRefreshSuccess(func() {
// Re-unmarshal the configuration
err := appConfig.Unmarshal(&config, nil)
if err != nil {
log.Printf("Failed to unmarshal updated configuration: %s", err)
return
}
})
기능 표시기
Azure App Configuration의 기능 플래그는 애플리케이션에서 기능 가용성을 제어하는 최신 방법을 제공합니다. 일반 구성 값과 달리 FeatureFlagOptions 구조체의 Options 필드를 사용하여 기능 플래그를 명시적으로 로드해야 합니다.
options := &azureappconfiguration.Options{
FeatureFlagOptions: azureappconfiguration.FeatureFlagOptions{
Enabled: true,
// Load feature flags that start with `TestApp:` and have `dev` label
Selectors: []azureappconfiguration.Selector{
{
KeyFilter: "TestApp:*",
LabelFilter: "dev",
},
},
RefreshOptions: azureappconfiguration.RefreshOptions{
Enabled: true,
Interval: 60 * time.Second,
},
},
}
appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)
팁 (조언)
선택기가 지정되지 않은 경우 App Configuration 저장소에 FeatureFlagOptions레이블이 없는모든 기능 플래그를 로드합니다. 기능 플래그의 기본 새로 고침 간격은 30초입니다.
중요합니다
Azure App Configuration에서 로드된 기능 플래그를 효과적으로 사용하고 관리하려면 패키지를 설치하고 사용합니다 featuremanagement . 이 라이브러리는 애플리케이션에서 기능 동작을 제어하는 구조화된 방법을 제공합니다.
기능 관리
기능 관리 Go 라이브러리는 기능 플래그를 기반으로 애플리케이션 기능을 개발하고 노출하는 구조화된 방법을 제공합니다. 기능 관리 라이브러리는 구성 공급자 라이브러리와 함께 작동하도록 설계되었습니다.
기능 관리 라이브러리에서 기능 플래그를 사용하려면 필요한 패키지를 설치합니다.
go get github.com/microsoft/Featuremanagement-Go/featuremanagement
go get github.com/microsoft/Featuremanagement-Go/featuremanagement/providers/azappconfig
다음 예제에서는 기능 관리 라이브러리를 구성 공급자와 통합하여 기능 가용성을 동적으로 제어하는 방법을 보여 줍니다.
import (
"github.com/microsoft/Featuremanagement-Go/featuremanagement"
"github.com/microsoft/Featuremanagement-Go/featuremanagement/providers/azappconfig"
)
func main() {
// Set up authentication options
authOptions := azureappconfiguration.AuthenticationOptions{
Endpoint: endpoint,
Credential: credential,
}
// Load configuration with feature flags enabled
options := &azureappconfiguration.Options{
FeatureFlagOptions: azureappconfiguration.FeatureFlagOptions{
Enabled: true,
RefreshOptions: azureappconfiguration.RefreshOptions{
Enabled: true,
},
},
}
appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)
if err != nil {
log.Fatalf("Failed to load configuration: %v", err)
}
// Create feature flag provider using the Azure App Configuration
featureFlagProvider, err := azappconfig.NewFeatureFlagProvider(appConfig)
if err != nil {
log.Fatalf("Error creating feature flag provider: %v", err)
}
// Create feature manager
featureManager, err := featuremanagement.NewFeatureManager(featureFlagProvider, nil)
if err != nil {
log.Fatalf("Error creating feature manager: %v", err)
}
// Use the feature manager to check feature flags
isEnabled, err := featureManager.IsEnabled("Beta")
if err != nil {
log.Printf("Error checking feature flag: %v", err)
return
}
if isEnabled {
fmt.Println("Beta feature is enabled!")
// Execute beta functionality
} else {
fmt.Println("Beta feature is disabled")
// Execute standard functionality
}
}
Go 기능 관리 라이브러리를 사용하는 방법에 대한 자세한 내용은 기능 플래그 빠른 시작을 참조하세요.
Key Vault 참조
Azure App Configuration은 Azure Key Vault에 저장된 비밀 참조를 지원합니다. App Configuration에서 Key Vault에 저장된 비밀에 매핑되는 키를 만들 수 있지만 로드된 후에는 다른 구성처럼 액세스할 수 있습니다.
구성 공급자 라이브러리는 App Configuration에 저장된 다른 키와 마찬가지로 Key Vault 참조를 검색합니다.
KeyVaultOptions 구조체의 Options 필드를 사용하여 Key Vault 액세스를 구성해야 합니다.
Key Vault에 연결
Key Vault 인스턴스에 인증할 수 있는 자격 증명을 제공하여 Key Vault 액세스를 구성할 수 있습니다.
import (
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
)
// Create a credential for Key Vault access
credential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
log.Fatalf("Failed to create credential: %v", err)
}
options := &azureappconfiguration.Options{
KeyVaultOptions: azureappconfiguration.KeyVaultOptions{
Credential: credential,
},
}
appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)
사용자 지정 비밀 확인자
기본 자격 증명 기반 접근 방식이 적합하지 않은 경우 Key Vault 참조를 처리하는 사용자 지정 비밀 확인자 함수를 제공할 수도 있습니다.
options := &azureappconfiguration.Options{
KeyVaultOptions: azureappconfiguration.KeyVaultOptions{
SecretResolver: func(ctx context.Context, keyVaultReference url.URL) (string, error) {
// Custom logic to resolve secrets
// This could integrate with your existing secret management system
// or provide fallback values for development environments
if isDevelopment {
return os.Getenv("FALLBACK_SECRET_VALUE"), nil
}
// Implement your custom secret retrieval logic here
return retrieveSecret(keyVaultReference)
},
},
}
중요합니다
애플리케이션이 적절한 Key Vault 구성 없이 Key Vault 참조를 포함하는 키 값을 로드하는 경우 로드 작업 중에 오류가 반환됩니다. Key Vault 액세스 또는 비밀 확인자를 올바르게 구성했는지 확인합니다.
Key Vault 비밀 새로 고침
Azure App Configuration을 사용하면 구성 새로 고침 주기와 독립적으로 비밀 새로 고침 간격을 구성할 수 있습니다. 이는 App Configuration의 Key Vault 참조 URI가 변경되지 않은 상태로 유지되지만 Key Vault의 기본 비밀이 보안 사례의 일부로 회전될 수 있기 때문에 보안에 매우 중요합니다.
애플리케이션에서 항상 가장 최신 비밀 값을 사용하도록 하려면 RefreshOptions 구조체에서 KeyVaultOptions 필드를 구성합니다.
import (
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
)
// Create a credential for Key Vault access
credential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
log.Fatalf("Failed to create credential: %v", err)
}
options := &azureappconfiguration.Options{
KeyVaultOptions: azureappconfiguration.KeyVaultOptions{
Credential: credential,
RefreshOptions: azureappconfiguration.RefreshOptions{
Enabled: true,
Interval: 5 * time.Minute,
},
},
}
appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)
스냅샷
스냅샷 은 App Configuration 저장소의 키-값의 명명된 변경할 수 없는 하위 집합입니다. 스냅샷 구성하는 키-값은 키 및 레이블 필터를 사용하여 만드는 동안 선택됩니다. 스냅샷이 만들어지면 포함된 키-값은 변경되지 않은 상태로 유지됩니다.
스냅샷에서 키-값을 로드하도록 SnapshotName 구조체 내의 Selector 필드를 구성할 수 있습니다.
options := &azureappconfiguration.Options{
Selectors: []azureappconfiguration.Selector{
{KeyFilter: "app*", LabelFilter: "prod"},
{SnapshotName: "my-snapshot"},
},
}
appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)
Geo-replication
지역에서 복제를 사용하는 방법에 대한 자세한 내용은 지역 복제 사용으로 이동하세요.
시작 과정 다시 시도
구성 로드는 애플리케이션을 시작하는 동안 중요한 경로 작업입니다. 안정성을 보장하기 위해 Azure App Configuration 공급자는 초기 구성 로드 중에 강력한 재시도 메커니즘을 구현합니다. 이렇게 하면 성공적인 시작을 방해할 수 있는 일시적인 네트워크 문제로부터 애플리케이션을 보호할 수 있습니다.
다음을 통해 이 동작을 사용자 지정할 수 있습니다.Options.StartupOptions
options := &azureappconfiguration.Options{
StartupOptions: azureappconfiguration.StartupOptions{
Timeout: 5 * time.Minute,
},
}
appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)
다음 단계
Go 구성 공급자를 사용하는 방법을 알아보려면 다음 자습서를 계속 진행하세요.