Go-Konfigurationsanbieter

Azure App Configuration ist ein verwalteter Dienst, mit dem Entwickler ihre Anwendungskonfigurationen einfach und sicher zentralisieren können. Die Go-Konfigurationsanbieterbibliothek ermöglicht das verwaltete Laden einer Konfiguration aus einem Azure App Configuration-Speicher. Diese Clientbibliothek bietet zusätzliche Funktionen zum Azure SDK für Go.

Laden der Konfiguration

Mit dem Go-Anbieter für Azure App Configuration können Sie Konfigurationswerte aus Ihrem Azure App Configuration-Speicher in Ihre Go-Anwendungen laden. Sie können eine Verbindung entweder mit der Microsoft Entra ID-Authentifizierung oder mit einer Verbindungszeichenfolge herstellen.

Um den Go-Konfigurationsanbieter zu verwenden, installieren Sie das Paket:

go get github.com/Azure/AppConfiguration-GoProvider/azureappconfiguration

Sie rufen die Funktion Load aus dem Paket azureappconfiguration auf, um die Konfiguration aus Azure App Configuration zu laden. Die Funktion Load akzeptiert Authentifizierungsoptionen und Konfigurationsoptionen, um das Ladeverhalten anzupassen.

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)
	}
}

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/Azure/AppConfiguration-GoProvider/azureappconfiguration"
)

func main() {
	ctx := context.Background()
	
	// Get the connection string from environment variable
	connectionString := os.Getenv("AZURE_APPCONFIG_CONNECTION_STRING")
	
	// Set up authentication options
	authOptions := azureappconfiguration.AuthenticationOptions{
		ConnectionString: connectionString,
	}

	// Load configuration from Azure App Configuration
	appConfig, err := azureappconfiguration.Load(ctx, authOptions, nil)
	if err != nil {
		log.Fatalf("Failed to load configuration: %v", err)
	}
}

Laden bestimmter Schlüsselwerte mithilfe von Selektoren

Standardmäßig lädt der Konfigurationsanbieter alle Schlüsselwerte ohne Bezeichnung aus der App-Konfiguration. Sie können Schlüsselwerte selektiv laden, indem Sie das Feld Selectors in der Options-Struktur konfigurieren.

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)

Die Selector-Struktur unterstützt die folgenden Felder:

• KeyFilter: Bestimmt, welche Konfigurationsschlüssel einbezogen werden sollen. Verwenden Sie genaue Übereinstimmungen, Präfixabgleich mit *oder mehrere durch Komma getrennte Schlüssel.
• LabelFilter: Wählt Schlüsselwerte mit einer bestimmten Bezeichnung aus. Ist dieses Feld leer, werden Schlüsselwerte ohne Bezeichnung geladen.

Tag-Filter

Der TagFilters Parameter wählt Schlüsselwerte mit bestimmten Tags aus. Ein Schlüsselwert wird nur geladen, wenn er alle Tags und die entsprechenden Werte enthält, die in den Filtern angegeben sind.

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)

Kürzen des Schlüsselpräfixes

Beim Laden von Konfigurationswerten mit bestimmten Präfixen können Sie die Option TrimKeyPrefixes verwenden, um diese Präfixe aus den Schlüsseln in Ihrer Konfiguration zu entfernen. Dadurch werden klare Konfigurationsschlüssel in Ihrer Anwendung erstellt, während die Organisation im App-Konfigurationsspeicher aufrechterhalten bleibt.

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)

Wenn ihr App-Konfigurationsspeicher z. B. einen Schlüssel mit dem Namen TestApp:Settings:Messageenthält, kann er in Ihrer Anwendung wie Settings:Message nach dem Kürzen des TestApp: Präfixes zugänglich sein.

JSON-Inhaltstypbehandlung

Sie können JSON-Schlüsselwerte in der App-Konfiguration erstellen. Wenn ein Schlüsselwert mit dem Inhaltstyp "application/json" gelesen wird, parst der Konfigurationsanbieter ihn in geschachtelten Strukturen. Für weitere Informationen gehen Sie zu Inhaltstyp verwenden, um JSON-Schlüsselwerte in der App-Konfiguration zu speichern.

Nutzen der Konfiguration

Der von der AzureAppConfiguration-Funktion zurückgegebene Load-Typ bietet mehrere Methoden für den Zugriff auf Ihre Konfigurationsdaten:

Rückgängigmachen des Marshallen für Strukturen

Die Unmarshal-Methode bietet eine typsichere Methode zum Laden von Konfigurationswerten in Go-Strukturen. Dieser Ansatz verhindert Laufzeitfehler aus falsch eingegebenen Konfigurationsschlüsseln und sorgt für eine bessere Verwaltbarkeit des Codes. Die Methode akzeptiert einen optionalen ConstructionOptions-Parameter zum Anpassen der Zuordnung von Konfigurationsschlüsseln zu Strukturfeldern.

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)
}

Benutzerdefinierte Schlüsseltrennzeichen

Sie können mithilfe von ConstructionOptions anpassen, wie Konfigurationsschlüssel Strukturfeldern zugeordnet werden. Dies ist nützlich, wenn Ihre Konfigurationsschlüssel andere Trennzeichen als den Standardpunkt verwenden (.):

// 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)
}

Die ConstructionOptions-Struktur unterstützt die folgenden Trennzeichen: ., ,, ;, -, _, __, /, :. Wenn keine Angabe erfolgt, wird das Standardtrennzeichen . verwendet.

Abrufen von unformatierten JSON-Bytes

Die GetBytes-Methode ruft Ihre Konfiguration als unformatierte JSON-Daten ab und bietet somit Flexibilität für die Integration in JSON-Verarbeitungsbibliotheken oder Konfigurationsframeworks wie viper. Diese Methode akzeptiert auch einen optionalen ConstructionOptions-Parameter zum Steuern der Schlüsselhierarchiezuordnung.

// 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)
}

Konfigurationsaktualisierung

Durch konfigurieren der Aktualisierung kann die Anwendung die neuesten Werte aus dem App-Konfigurationsspeicher abrufen, ohne neu starten zu müssen. Sie können Aktualisierungsoptionen mithilfe des Felds RefreshOptions in der Options-Struktur konfigurieren. Die geladene Konfiguration wird aktualisiert, wenn Änderungen der ausgewählten Schlüsselwerte auf dem Server erkannt werden. Standardmäßig wird ein Aktualisierungsintervall von 30 Sekunden verwendet, Sie können es jedoch mit der Interval-Eigenschaft überschreiben.

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)

Das Einrichten von RefreshOptions allein aktualisiert die Konfiguration nicht automatisch. Sie müssen die Refresh-Methode für die AzureAppConfiguration-Instanz aufrufen, um eine Aktualisierung auszulösen.

// Trigger a refresh
if err := appConfig.Refresh(ctx); err != nil {
	log.Printf("Failed to refresh configuration: %v", err)
}

Dieses Design verhindert unnötige Anforderungen an die App-Konfiguration, wenn ihre Anwendung im Leerlauf ist. Sie sollten den Aufruf Refresh dort verwenden, wo Ihre Anwendungsaktivität auftritt. Dies wird als aktivitätsgesteuerte Konfigurationsaktualisierung bezeichnet. Sie können z. B. Refresh beim Verarbeiten einer eingehenden Anforderung oder innerhalb einer Iteration aufrufen, in der Sie eine komplexe Aufgabe ausführen.

Aktualisieren bei einem Sentinelschlüssel

Ein Sentinel-Schlüssel ist ein Schlüssel, den Sie aktualisieren, nachdem Sie die Änderung aller anderen Schlüssel abgeschlossen haben. Der Konfigurationsanbieter überwacht den Sentinelschlüssel anstelle aller ausgewählten Schlüsselwerte. Wird eine Änderung erkannt, werden alle Konfigurationswerte von Ihrer App aktualisiert.

Dieser Ansatz ist nützlich, wenn mehrere Schlüsselwerte aktualisiert werden. Wenn Sie den Sentinel-Schlüssel erst aktualisieren, nachdem alle anderen Konfigurationsänderungen abgeschlossen wurden, stellen Sie sicher, dass die Konfiguration der Anwendung nur einmal neu geladen wird, wobei die Konsistenz beibehalten wird.

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: "",
			},
		},
	},
}

Benutzerdefinierter Aktualisierungsrückruf

Die OnRefreshSuccess-Methode registriert eine Rückruffunktion, die ausgeführt wird, wenn die Konfiguration erfolgreich aktualisiert wurde und tatsächliche Änderungen erkannt wurden.

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
    }
})

Featureflags

Featurekennzeichnungen in der Azure App-Konfiguration bieten eine moderne Möglichkeit, die Verfügbarkeit von Features in Ihren Anwendungen zu steuern. Im Gegensatz zu regulären Konfigurationswerten müssen Featureflags explizit mithilfe des Felds FeatureFlagOptions in der Options-Struktur geladen werden.

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)

Funktionsverwaltung

Die Go-Funktionsverwaltungsbibliothek bietet eine strukturierte Möglichkeit, Anwendungsfunktionen basierend auf Featureflags zu entwickeln und verfügbar zu machen. Die Featureverwaltungsbibliothek ist so konzipiert, dass sie mit der Konfigurationsanbieterbibliothek zusammenarbeitet.

Um Featureflags mit der Funktionsverwaltungsbibliothek zu verwenden, installieren Sie die erforderlichen Pakete:

go get github.com/microsoft/Featuremanagement-Go/featuremanagement
go get github.com/microsoft/Featuremanagement-Go/featuremanagement/providers/azappconfig

Im folgenden Beispiel wird veranschaulicht, wie Sie die Funktionsverwaltungsbibliothek in den Konfigurationsanbieter integrieren, um die Verfügbarkeit von Features dynamisch zu steuern:

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
	}
}

Weitere Informationen zur Verwendung der Go-Funktionsverwaltungsbibliothek finden Sie in der Schnellstartanleitung zu Featureflags.

Key Vault-Verweis

Azure App Configuration unterstützt das Verweisen auf Geheimnisse, die in Azure Key Vault gespeichert sind. In App Configuration können Sie Schlüssel erstellen, die in Key Vault gespeicherten Geheimnissen zugeordnet sind, die aber wie jede andere Konfiguration nach dem Laden aufgerufen werden können.

Die Konfigurationsanbieterbibliothek ruft Key Vault-Verweise ab, wie dies auch für alle anderen Schlüssel der Fall ist, die in App Configuration gespeichert sind. Sie müssen den Key Vault-Zugriff mithilfe des Felds KeyVaultOptions in der Options-Struktur konfigurieren.

Verbindung mit Key Vault herstellen

Sie können den Key Vault-Zugriff konfigurieren, indem Sie Anmeldeinformationen angeben, die sich bei Ihren Key Vault-Instanzen authentifizieren können.

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)

Benutzerdefinierter Geheimnislöser

Sie können auch eine benutzerdefinierte Funktion für Geheimnislöser bereitstellen, um Key Vault-Verweise zu behandeln, wenn der standardmäßige anmeldeinformationsbasierte Ansatz nicht geeignet ist:

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-Geheimnisaktualisierung

Mit der Azure App-Konfiguration können Sie geheime Aktualisierungsintervalle unabhängig vom Aktualisierungszyklus der Konfiguration konfigurieren. Dies ist für die Sicherheit von entscheidender Bedeutung, da der Key Vault-Referenz-URI in der App-Konfiguration unverändert bleibt, der zugrunde liegende Schlüssel im Key Vault jedoch möglicherweise im Rahmen Ihrer Sicherheitspraktiken rotiert wird.

Um sicherzustellen, dass Ihre Anwendung immer die aktuellsten Geheimniswerte verwendet, konfigurieren Sie das Feld RefreshOptions Eigenschaft in der KeyVaultOptions-Struktur.

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)

Schnappschuss

Snapshot ist eine benannte, unveränderliche Teilmenge der Schlüsselwerte eines App-Konfigurationsspeichers. Die Schlüsselwerte, aus denen eine Momentaufnahme besteht, werden während der Erstellungszeit durch die Verwendung von Schlüssel- und Bezeichnungsfiltern ausgewählt. Nachdem eine Momentaufnahme erstellt wurde, bleiben die darin enthaltenen Schlüsselwerte garantiert unverändert.

Sie können das Feld SnapshotName in der Selector-Struktur so konfigurieren, dass Schlüsselwerte aus einer Momentaufnahme geladen werden:

options := &azureappconfiguration.Options{
	Selectors: []azureappconfiguration.Selector{
		{KeyFilter: "app*", LabelFilter: "prod"},
		{SnapshotName: "my-snapshot"},
	},
}

appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)

Georeplikation

Informationen zur Verwendung der Georeplikation finden Sie unter Aktivieren der Georeplikation.

Neustart-Versuch

Beim Laden der Konfiguration handelt es sich um einen kritischen Pfadvorgang beim Starten der Anwendung. Um die Zuverlässigkeit zu gewährleisten, implementiert der Azure App-Konfigurationsanbieter während der anfänglichen Konfigurationslast einen robusten Wiederholungsmechanismus. Dadurch wird Ihre Anwendung vor vorübergehenden Netzwerkproblemen geschützt, die andernfalls den erfolgreichen Start verhindern können.

Sie können dieses Verhalten über folgendes Options.StartupOptionsanpassen:

options := &azureappconfiguration.Options{
	StartupOptions: azureappconfiguration.StartupOptions{
		Timeout: 5 * time.Minute,
	},
}

appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)

Nächste Schritte

Um zu erfahren, wie Sie den Go-Konfigurationsanbieter verwenden, fahren Sie mit dem folgenden Tutorial fort: