azureappconfiguration

package module
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 19, 2025 License: MIT Imports: 29 Imported by: 14

README

Azure App Configuration - Go Provider

PkgGoDev

Overview

Azure App Configuration provides centralized configuration storage and management, allowing users to update their configurations without the need to rebuild and redeploy their applications. The App Configuration provider for Go is built on top of the Azure Go SDK and is designed to simplify data consumption in App Configuration with rich features. Users can consume App Configuration key-values as strongly-typed structs with data binding or load them into popular third-party configuration libraries, minimizing code changes. The Go provider offers features such as configuration composition from multiple labels, key prefix trimming, automatic resolution of Key Vault references, feature flags, failover with geo-replication for enhanced reliability, and many more.

Installation

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

Getting Started

Official documentation on how to use the Azure App Configuration provider is available in the following quickstarts:

Examples

Data Collection

The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry by setting the environment variable AZURE_APP_CONFIGURATION_TRACING_DISABLED to TRUE. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft’s privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

Documentation

Overview

Package azureappconfiguration provides a client for Azure App Configuration, enabling Go applications to manage application settings with Microsoft's Azure App Configuration service.

The azureappconfiguration package allows loading configuration data from Azure App Configuration in a structured way, with support for automatic Key Vault reference resolution, hierarchical configuration construction, and strongly typed configuration binding.

For more information about Azure App Configuration, see: https://learn.microsoft.com/en-us/azure/azure-app-configuration/

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AuthenticationOptions 

type AuthenticationOptions struct {
	// Credential is a token credential for Azure EntraID Authentication.
	// Required when Endpoint is provided.
	Credential azcore.TokenCredential

	// Endpoint is the URL of the Azure App Configuration service.
	// Required when using token-based authentication with Credential.
	Endpoint string

	// ConnectionString is the connection string for the Azure App Configuration service.
	ConnectionString string
}

AuthenticationOptions contains parameters for authenticating with the Azure App Configuration service. Either a connection string or an endpoint with credential must be provided.

type AzureAppConfiguration 

type AzureAppConfiguration struct {
	// contains filtered or unexported fields
}

An AzureAppConfiguration is a configuration provider that stores and manages settings sourced from Azure App Configuration.

func Load 

func Load(ctx context.Context, authentication AuthenticationOptions, options *Options) (*AzureAppConfiguration, error)

Load initializes a new AzureAppConfiguration instance and loads the configuration data from Azure App Configuration service.

Parameters:

  • ctx: The context for the operation.
  • authentication: Authentication options for connecting to the Azure App Configuration service
  • options: Configuration options to customize behavior, such as key filters and prefix trimming

Returns:

  • A configured AzureAppConfiguration instance that provides access to the loaded configuration data
  • An error if the operation fails, such as authentication errors or connectivity issues

func (*AzureAppConfiguration) GetBytes 

func (azappcfg *AzureAppConfiguration) GetBytes(options *ConstructionOptions) ([]byte, error)

GetBytes returns the configuration as a JSON byte array with hierarchical structure. This method is particularly useful for integrating with "encoding/json" package or third-party configuration packages like Viper or Koanf.

Parameters:

  • options: Optional parameters for controlling JSON construction, particularly the key separator

Returns:

  • A byte array containing the JSON representation of the configuration
  • An error if JSON marshalling fails or if an invalid separator is specified

func (*AzureAppConfiguration) OnRefreshSuccess 

func (azappcfg *AzureAppConfiguration) OnRefreshSuccess(callback func())

OnRefreshSuccess registers a callback function that will be executed whenever the configuration is successfully refreshed and actual changes were detected.

Multiple callback functions can be registered, and they will be executed in the order they were added. Callbacks are only executed when configuration values actually change. They run synchronously in the thread that initiated the refresh.

Parameters:

  • callback: A function with no parameters that will be called after a successful refresh

func (*AzureAppConfiguration) Refresh 

func (azappcfg *AzureAppConfiguration) Refresh(ctx context.Context) error

Refresh manually triggers a refresh of the configuration from Azure App Configuration. It checks if any watched settings have changed, and if so, reloads all configuration data.

The refresh only occurs if:

  • Refresh has been configured with RefreshOptions when the client was created
  • The configured refresh interval has elapsed since the last refresh
  • No other refresh operation is currently in progress

If the configuration has changed, any callback functions registered with OnRefreshSuccess will be executed.

Parameters:

  • ctx: The context for the operation.

Returns:

  • An error if refresh is not configured, or if the refresh operation fails

func (*AzureAppConfiguration) Unmarshal 

func (azappcfg *AzureAppConfiguration) Unmarshal(v any, options *ConstructionOptions) error

Unmarshal parses the configuration and stores the result in the value pointed to v. It builds a hierarchical configuration structure based on key separators. It supports converting values to appropriate target types.

Fields in the target struct are matched with configuration keys using the field name by default. For custom field mapping, use json struct tags.

Parameters:

  • v: A pointer to the struct to populate with configuration values
  • options: Optional parameters (e,g, separator) for controlling the unmarshalling behavior

Returns:

  • An error if unmarshalling fails due to type conversion issues or invalid configuration

type ConstructionOptions 

type ConstructionOptions struct {
	// Separator specifies the character used to determine hierarchy in configuration keys
	// when mapping to nested struct fields during unmarshaling operations.
	// Supported values: '.', ',', ';', '-', '_', '__', '/', ':'.
	// If not provided, the default separator "." will be used.
	Separator string
}

ConstructionOptions contains parameters for parsing keys with hierarchical structure.

type FeatureFlagOptions added in v1.1.0 

type FeatureFlagOptions struct {
	// Enabled specifies whether feature flags will be loaded from Azure App Configuration.
	Enabled bool

	// If no selectors are provided, all feature flags with no label will be loaded when enabled feature flags.
	Selectors []Selector

	// RefreshOptions specifies the behavior of feature flags refresh.
	// Refresh interval must be greater than 1 second. If not provided, the default interval 30 seconds will be used
	// All loaded feature flags will be automatically watched when feature flags refresh is enabled.
	RefreshOptions RefreshOptions
}

FeatureFlagOptions contains optional parameters for Azure App Configuration feature flags that will be parsed and transformed into feature management configuration.

type KeyValueRefreshOptions 

type KeyValueRefreshOptions struct {
	// WatchedSettings specifies the key-value settings to watch for changes
	WatchedSettings []WatchedSetting

	// Interval specifies the minimum time interval between consecutive refresh operations for the watched settings
	// Must be greater than 1 second. If not provided, the default interval 30 seconds will be used
	Interval time.Duration

	// Enabled specifies whether the provider should automatically refresh when the configuration is changed.
	Enabled bool
}

KeyValueRefreshOptions contains optional parameters to configure the behavior of key-value settings refresh

type KeyVaultOptions 

type KeyVaultOptions struct {
	// Credential specifies the token credential used to authenticate to Azure Key Vault services.
	// This is required for Key Vault reference resolution unless a custom SecretResolver is provided.
	Credential azcore.TokenCredential

	// SecretResolver specifies a custom implementation for resolving Key Vault references.
	// When provided, this takes precedence over using the default resolver with Credential.
	SecretResolver SecretResolver

	// RefreshOptions specifies the behavior of Key Vault secrets refresh.
	// Sets the refresh interval for periodically reloading secrets from Key Vault, must be greater than 1 minute.
	RefreshOptions RefreshOptions
}

KeyVaultOptions contains parameters to configure the build-in Key Vault reference resolution. These options determine how the provider will authenticate with and retrieve

type Options 

type Options struct {
	// TrimKeyPrefixes specifies a list of prefixes to trim from the keys of all key-values
	// retrieved from Azure App Configuration, making them more suitable for binding to structured types.
	TrimKeyPrefixes []string

	// Selectors defines what key-values to load from Azure App Configuration
	// Each selector combines a key filter and label filter
	// If selectors are not provided, all key-values with no label are loaded by default.
	Selectors []Selector

	// RefreshOptions contains optional parameters to configure the behavior of key-value settings refresh
	RefreshOptions KeyValueRefreshOptions

	// KeyVaultOptions configures how Key Vault references are resolved.
	KeyVaultOptions KeyVaultOptions

	// FeatureFlagOptions contains optional parameters for Azure App Configuration feature flags.
	FeatureFlagOptions FeatureFlagOptions

	// ClientOptions provides options for configuring the underlying Azure App Configuration client.
	ClientOptions *azappconfig.ClientOptions

	// ReplicaDiscoveryEnabled specifies whether to enable replica discovery for the Azure App Configuration service.
	// It defaults to true, which allows the provider to discover and use replicas for improved availability.
	ReplicaDiscoveryEnabled *bool

	// LoadBalancingEnabled specifies whether to enable load balancing across multiple replicas of the Azure App Configuration service.
	// It defaults to false.
	LoadBalancingEnabled bool
}

Options contains optional parameters to configure the behavior of an Azure App Configuration provider. It provides control over which key-values to fetch, how to trim key prefixes, and how to handle Key Vault references.

type RefreshOptions 

type RefreshOptions struct {
	// Interval specifies the minimum time interval between consecutive refresh operations
	Interval time.Duration

	// Enabled specifies whether the provider should automatically refresh when data is changed.
	Enabled bool
}

RefreshOptions contains optional parameters to configure the behavior of refresh

type SecretResolver 

type SecretResolver interface {
	// ResolveSecret resolves a Key Vault reference URL to the actual secret value.
	//
	// Parameters:
	//   - ctx: The context for the operation
	//   - keyVaultReference: A URL in the format "https://{keyVaultName}.vault.azure.net/secrets/{secretName}/{secretVersion}"
	//
	// Returns:
	//   - The resolved secret value as a string
	//   - An error if the secret could not be resolved
	ResolveSecret(ctx context.Context, keyVaultReference url.URL) (string, error)
}

SecretResolver is an interface to resolve secrets from Key Vault references. Implement this interface to provide custom secret resolution logic.

type Selector 

type Selector struct {
	// KeyFilter specifies which keys to retrieve from Azure App Configuration.
	// It can include wildcards, e.g. "app*" will match all keys starting with "app".
	KeyFilter string

	// LabelFilter specifies which labels to retrieve from Azure App Configuration.
	// Empty string or omitted value will use the default no-label filter.
	// Note: Wildcards are not supported in label filters.
	LabelFilter string
}

Selector specifies what key-values to load from Azure App Configuration.

type WatchedSetting 

type WatchedSetting struct {
	Key   string
	Label string
}

WatchedSetting specifies the key and label of a key-value setting to watch for changes

Source Files

View all Source files

Directories

Path Synopsis
internal
fm
jsonc
Package jsonc provides support for parsing JSON with comments (JSONC).
 Package jsonc provides support for parsing JSON with comments (JSONC).
refresh
tracing
tree

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.