azure-appconfiguration-provider (original) (raw)

Azure App Configuration Python Provider client library for Python

Azure App Configuration is a managed service that helps developers centralize their application configurations simply and securely. This provider adds additional functionality above the azure-sdk-for-python.

Using the provider enables loading sets of configurations from an Azure App Configuration store in a managed way.

Getting started

Get credentials

Use the Azure CLI snippet below to get the connection string from the Configuration Store.

az appconfig credential list --name

Alternatively, get the connection string from the Azure Portal.

Creating a provider

You can create a client with a connection string:

import os from azure.appconfiguration.provider import load

connection_string = os.environ["APPCONFIGURATION_CONNECTION_STRING"]

Connecting to Azure App Configuration using connection string

config = load(connection_string=connection_string, **kwargs)

or with Entra ID:

import os from azure.appconfiguration.provider import load from azure.identity import DefaultAzureCredential

endpoint = os.environ["APPCONFIGURATION_ENDPOINT_STRING"] credential = DefaultAzureCredential()

Connecting to Azure App Configuration using Entra ID

config = load(endpoint=endpoint, credential=credential, **kwargs)

these providers will by default load all configurations with (No Label) from your configuration store into a dictionary of key/values.

Features

Currently the Azure App Configuration Provider enables:

Examples

Selecting configurations

You can refine or expand the configurations loaded from your store by using SettingSelectors. Setting selectors provide a way to pass a key filter and label filter into the provider.

from azure.appconfiguration.provider import load, SettingSelector

Connection to Azure App Configuration using SettingSelector

selects = [SettingSelector(key_filter="message*")] config = load( endpoint=endpoint, credential=credential, selects=selects, feature_flag_enabled=True, feature_flag_selectors=None, **kwargs, )

In this example, configuration settings with keys matching message* are loaded. Feature flags are also enabled, so the default feature flags (those with no label) will be loaded.

Filtering by Tags

You can filter configuration settings by tags using the tag_filters parameter on SettingSelector. Tag filters must follow the format "tagName=tagValue".

from azure.appconfiguration.provider import load, SettingSelector

Filtering by tags

selects = [SettingSelector(key_filter="*", tag_filters=["env=prod"])] config = load(endpoint=endpoint, credential=credential, selects=selects, **kwargs)

Loading from Snapshots

You can load configuration settings from a snapshot by providing snapshot_name on SettingSelector. When snapshot_name is specified, all configuration settings from the snapshot are loaded. Note that snapshot_name cannot be used together with key_filter, label_filter, or tag_filters. In the examples below, endpoint, credential, and snapshot_name are assumed to be defined. See the snapshot sample for complete setup.

from azure.appconfiguration.provider import load, SettingSelector

Step 2: Loading configuration settings from the snapshot

snapshot_selects = [SettingSelector(snapshot_name=snapshot_name)] config = load(endpoint=endpoint, credential=credential, selects=snapshot_selects, **kwargs)

You can also mix snapshot selectors with regular selectors. Later selectors take precedence when there are duplicate keys.

Step 3: Combine snapshot with regular selectors (later selectors take precedence)

mixed_selects = [ SettingSelector(snapshot_name=snapshot_name), # Load all settings from snapshot SettingSelector(key_filter="override.*", label_filter="prod"), # Also load specific override settings ] config_mixed = load(endpoint=endpoint, credential=credential, selects=mixed_selects, **kwargs)

Dynamic Refresh

The provider can be configured to refresh configurations from the store on a set interval. This is done by providing a refresh_on to the provider, which is a list of key(s) that will be watched for changes, and when they do change a refresh can happen. refresh_interval is the period of time in seconds between refreshes. on_refresh_success is a callback that will be called only if a change is detected and no error happens. on_refresh_error is a callback that will be called when a refresh fails.

import os from azure.appconfiguration.provider import load, WatchKey

connection_string = os.environ["APPCONFIGURATION_CONNECTION_STRING"]

config = load( endpoint=endpoint, credential=credential, refresh_on=[WatchKey("Sentinel")], refresh_interval=60, **kwargs, )

In this example, the sentinel key will be checked for changes no sooner than every 60 seconds. In order to check for changes, the provider's refresh method needs to be called.

config.refresh()

Once the provider is refreshed, the configurations can be accessed as normal. And if any changes have been made it will be updated with the latest values. If the refresh_interval hasn't passed since the last refresh check, the provider will not check for changes.

For additional info check out Dynamic Refresh on MS Learn.

Trimming Keys

You can trim the prefix off of keys by providing a list of trimmed key prefixes to the provider. For example, if you have the key(s) like /application/message in your configuration store, you could trim /application/ from them.

from azure.appconfiguration.provider import load

Connecting to Azure App Configuration using Entra ID and trim key prefixes

trimmed = ["test."] config = load(endpoint=endpoint, credential=credential, trim_prefixes=trimmed, **kwargs)

Resolving Key Vault References

Key Vault References can be resolved by providing credentials to your key vault to the provider.

With Credentials

You can provide a keyvault_credential and all key vault references will be resolved with it. The provider will attempt to connect to any key vault referenced with the credential provided.

from azure.appconfiguration.provider import load, SettingSelector

Connection to Azure App Configuration using Entra ID and Resolving Key Vault References

selects = [SettingSelector(key_filter="*", label_filter="prod")]

config = load(endpoint=endpoint, credential=credential, keyvault_credential=credential, selects=selects, **kwargs)

With Client Configs

You can provide keyvault_client_configs with a mapping of Key Vault URIs to client configurations. This is useful when different Key Vaults require different credentials.

from azure.appconfiguration.provider import load, SettingSelector

Connection to Azure App Configuration using Entra ID with Provided Client

client_configs = {key_vault_uri: {"credential": credential}} selects = [SettingSelector(key_filter="*", label_filter="prod")] config = load( endpoint=endpoint, credential=credential, keyvault_client_configs=client_configs, selects=selects, **kwargs, )

Secret Resolver

If no credentials or client configs are provided, a secret_resolver can be used. Secret resolver provides a way to return any value you want for a key vault reference.

from azure.appconfiguration.provider import load

def secret_resolver(uri): return "From Secret Resolver"

config = load(endpoint=endpoint, credential=credential, secret_resolver=secret_resolver, **kwargs)

Secret Refresh Interval

When using Key Vault references, the provider can periodically refresh resolved secrets. If you set the secret_refresh_interval parameter, secrets are refreshed at that interval (minimum 1 second).

from azure.appconfiguration.provider import load

Refresh Key Vault secrets every 120 seconds

config = load( endpoint=endpoint, credential=credential, keyvault_credential=credential, secret_refresh_interval=120, **kwargs, )

Geo Replication

The Azure App Configuration Provider library will automatically discover the provided configuration store's replicas and use the replicas if any issue arises. From more information see Geo-Replication.

Replica discovery is enabled by default. If you want to disable it, you can set replica_discovery_enabled to False.

from azure.appconfiguration.provider import load

Disabling replica discovery

config = load(endpoint=endpoint, credential=credential, replica_discovery_enabled=False, **kwargs)

You can also enable load balancing to distribute requests across replicas by setting load_balancing_enabled to True.

from azure.appconfiguration.provider import load

Enabling load balancing across replicas

config = load(endpoint=endpoint, credential=credential, load_balancing_enabled=True, **kwargs)

Loading Feature Flags

Feature Flags can be loaded from config stores using the provider. Feature flags are loaded as a list of feature flag objects stored in the provider under feature_management, then feature_flags.

from azure.appconfiguration.provider import load

config = load(endpoint=endpoint, credential=credential, feature_flag_enabled=True, **kwargs) feature_flags = config["feature_management"]["feature_flags"] alpha = next(flag for flag in feature_flags if flag["id"] == "Alpha") print(alpha["enabled"])

By default all feature flags with no label are loaded when feature_flag_enabled is set to True. If you want to load feature flags with a specific label you can use SettingSelector to filter the feature flags.

from azure.appconfiguration.provider import load, SettingSelector

config = load( endpoint=endpoint, credential=credential, feature_flag_enabled=True, feature_flag_selectors=[SettingSelector(key_filter="*", label_filter="dev")], **kwargs, ) feature_flags = config["feature_management"]["feature_flags"] alpha = next(flag for flag in feature_flags if flag["id"] == "Alpha") print(alpha["enabled"])

To enable refresh for feature flags you need to enable refresh. This will allow the provider to refresh feature flags the same way it refreshes configurations. Unlike configurations, all loaded feature flags are monitored for changes and will cause a refresh. Refresh of configuration settings and feature flags are independent of each other. Both are trigged by the refresh method, but a feature flag changing will not cause a refresh of configurations and vice versa. Also, if refresh for configuration settings is not enabled, feature flags can still be enabled for refresh.

import os from azure.appconfiguration.provider import load, WatchKey

connection_string = os.environ["APPCONFIGURATION_CONNECTION_STRING"]

config = load( endpoint=endpoint, credential=credential, refresh_on=[WatchKey("message")], refresh_on_feature_flags=True, refresh_interval=60, feature_flag_enabled=True, feature_flag_refresh_enabled=True, **kwargs, )

JSON Content Type

Configuration settings with a JSON content type (e.g., application/json) are automatically deserialized into their corresponding Python objects when loaded by the provider.

from azure.appconfiguration.provider import load

Settings with JSON content type are automatically deserialized

config = load(endpoint=endpoint, credential=credential, **kwargs) app_config = config["app/config"] # Returns a dict if the value is JSON print(app_config["timeout"])

Configuration Mapper

You can provide a configuration_mapper callback to transform configuration settings before they are added to the provider.

from azure.appconfiguration.provider import load

def my_mapper(setting): # Transform the setting as needed setting.value = setting.value.strip()

config = load(endpoint=endpoint, credential=credential, configuration_mapper=my_mapper, **kwargs)

Startup Timeout

The provider supports configurable startup timeout with automatic retry. By default, the provider allows 100 seconds for the initial load from Azure App Configuration. You can customize this with the startup_timeout parameter.

from azure.appconfiguration.provider import load

config = load(endpoint=endpoint, credential=credential, startup_timeout=200, **kwargs)

Async Support

The provider includes full async support via the azure.appconfiguration.provider.aio module.

from azure.appconfiguration.provider.aio import load

Connecting to Azure App Configuration using Entra ID

config = await load(endpoint=endpoint, credential=credential, **kwargs) print(config["message"])

await credential.close() await config.close()

Key concepts

The AzureAppConfigurationProvider is the main object returned by load(). It implements the Mapping interface, so it can be used like a read-only dictionary. Call refresh() (or await refresh() for async) to pull the latest values from the store.

Key types used:

Troubleshooting

Logging

This library uses the standard logging library for logging. Information about configuration loading, refresh, and Key Vault resolution is logged at the DEBUG level.

Common Issues

Next steps

Check out our Django and Flask examples to see how to use the provider in a web application.

Django

Flask

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.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., label, 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 theMicrosoft 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.

Release History

2.5.0 (2026-05-22)

Features Added

Other Changes

2.4.0 (2026-02-17)

Features Added

Bugs Fixed

2.3.1 (2025-11-13)

Bugs Fixed

2.3.0 (2025-11-12)

Features Added

Bugs Fixed

Other Changes

2.2.0 (2025-08-08)

Features Added

2.1.0 (2025-04-28)

Features Added

2.0.2 (2025-04-17)

Other Changes

2.1.0b1 (2025-04-10)

Bugs Fixed

2.0.1 (2025-03-07)

Bugs Fixed

Other Changes

2.0.0 (2025-01-06)

Features Added

2.0.0b3 (2024-11-13)

Breaking Changes

2.0.0b2 (2024-10-11)

Feature Added

Bugs Fixed

2.0.0b1 (2024-09-11)

Features Added

1.3.0 (2024-09-09)

Features Added

1.2.0 (2024-05-24)

Features Added

Bugs Fixed

1.1.0 (2024-01-29)

Features Added

Bugs Fixed

1.1.0b3 (2023-12-19)

Features Added

Bugs Fixed

Other Changes

1.1.0b2 (2023-09-29)

Features Added

Bugs Fixed

1.1.0b1 (2023-09-13)

Features Added

Other Changes

1.0.0 (2023-03-09)

Breaking Changes

Other Changes

1.0.0b2 (2023-02-15)

Features Added

Breaking Changes

Bugs Fixed

Other Changes

1.0.0b1 (2022-10-13)

New Azure App Configuration Provider

Provides additional support above the Azure App Configuration SDK. Enables:

The Azure App Configuration Provider once loaded returns a dictionary of key/value pairs to use in configuration.

endpoint = "https://.azconfig.io" default_credential = DefaultAzureCredential() config = AzureAppConfigurationProvider.load( endpoint=endpoint, credential=default_credential) print(config["message"])