Merge pull request #308965 from avanigupta/user/avanigupta/afdDocs

[AppConfig] Add concept docs for AFD integration

Author: v-shils

articles/azure-app-configuration/TOC.yml

@@ -119,8 +119,6 @@
     items:
     - name: App Service & Azure Functions
       href: /azure/app-service/app-service-configuration-references
-    - name: Azure Front Door
-      href: how-to-connect-azure-front-door.md
   - name: Deployment
     items:
     - name: Overview
@@ -260,6 +258,15 @@
       href: howto-telemetry-python.md
     - name: JavaScript
       href: howto-telemetry-javascript.md
+
+- name: Hyperscale configuration
+  items:
+  - name: Overview
+    href: concept-hyperscale-client-configuration.md
+  - name: Connect to Azure Front Door
+    href: how-to-connect-azure-front-door.md
+  - name: Load Configuration from Azure Front Door
+    href: how-to-load-azure-front-door-configuration-provider.md
 - name: CI/CD integration
   items:
   - name: Use configuration files

articles/azure-app-configuration/concept-hyperscale-client-configuration.md

@@ -0,0 +1,97 @@
+---
+title: Hyperscale configuration delivery for client applications with Azure App Configuration (Preview) 
+description: Learn how to use hyperscale configuration delivery to your applications via Azure Front Door.
+author: avanigupta
+ms.author: avgupta
+ms.service: azure-app-configuration
+ms.topic: concept-article 
+ms.date: 12/02/2025
+---
+
+# Hyperscale configuration delivery for client applications (preview) 
+
+When it comes to consuming configuration, client applications have different requirements than server applications. They can't store secrets, they operate on a much larger scale, and users expect instant startup times from anywhere in the world. To meet the requirements of client-side application configuration, Azure App Configuration provides integration with Azure Front Door. Azure Front Door's edge-based content delivery network combined with Azure App Configuration's centralized configuration management enables client applications anywhere to get configuration fast, reliably and anonymously.
+
+## CDN-accelerated configuration delivery with Azure Front Door
+
+App Configuration gives developers a single, consistent place to define configuration settings and feature flags. By integrating Azure App Configuration with Azure Front Door, your configuration data is centrally managed through Azure App Configuration while being cached and distributed through Azure's content delivery network. This architecture is valuable for client-facing applications including mobile, desktop, and browser-based applications.
+
+## System architecture
+
+:::image type="content" source="media/hyperscale-configuration-architecture.png" alt-text="Architecture diagram for integration of Azure Front Door with Azure App Configuration."
+
+How it works
+- Client applications retrieve configuration through Azure Front Door endpoints without authentication, eliminating the security risk of embedding credentials in client-side code.
+- Azure Front Door uses Managed Identity to authenticate with Azure App Configuration securely.
+- A configurable subset of key-values, feature flags, or snapshots are exposed through Azure Front Door.
+- Edge caching enables high throughput and low latency configuration delivery.
+
+This architecture eliminates the need for custom proxies or gateways while providing secure, efficient configuration delivery to client applications.
+
+## Developer scenarios
+
+CDN-delivered configuration unlocks a range of client application scenarios:
+
+- Client-side feature rollouts for UI components
+- A/B testing or targeted experiences using feature flags
+- Control AI/LLM model parameters and UI behaviors through configuration
+- Dynamically control client-side agent behavior, safety modes, and guardrail settings through configuration
+- Consistent behavior for clients using snapshot-based configuration
+
+> [!NOTE]
+> This feature is currently available only in the Azure public cloud. 
+
+## Recommendations and considerations
+
+### Security
+
+Configuration exposed through Azure Front Door is publicly accessible without authentication, making proper security controls essential. Implement the following strategies to protect your configuration data from unintended exposure.
+
+#### Use a dedicated App Configuration store
+
+Consider using a dedicated App Configuration store for client-facing configuration delivered through Azure Front Door. This store should contain only nonsensitive settings that are safe for public consumption. This isolation strategy limits potential impact if configuration is inadvertently exposed, ensuring that sensitive data remains protected.
+
+#### Role Based Access Control using Managed Identity
+
+Azure Front Door accesses App Configuration data using either a system-assigned managed identity or a user-assigned managed identity. The selected identity must be assigned the `App Configuration Data Reader` role to retrieve configuration data. When you create the Azure Front Door endpoint through the App Configuration portal, this role assignment is created automatically. The portal displays a warning if the role assignment creation process encounters any issues. Restrict the managed identity to the `App Configuration Data Reader` role only and avoid assigning any roles with write permissions.
+
+### Request scoping
+
+Configure one or more filters to control which requests are allowed to pass through Azure Front Door. This prevents anonymous clients from bypassing the CDN cache through excessive or malformed requests that could overwhelm App Configuration and trigger service throttling.
+
+#### Request scoping through key-value filters
+
+- Configure Azure Front Door filters to precisely match your application's configuration requirements. Only expose the exact key patterns your application uses. For example, if your application loads keys with the `"App1:"` prefix, configure the Azure Front Door rule to allow only `"App1:"` keys, not broader patterns like `"App"`.
+
+- If your application loads feature flags, provide `".appconfig.featureflag/{YOUR-FEATURE-FLAG-PREFIX}"` filter for the Key with *Starts with* operator.
+
+- If you're using App Configuration provider libraries and your application loads ONLY feature flags, you should add two key filters in the Azure Front Door rules - one for `ALL` keys with no label and second for all keys starting with `".appconfig.featureflag/{YOUR-FEATURE-FLAG-PREFIX}"`. This is because App Configuration provider libraries load all key-values with no label by default when no key-value selector is specified. 
+
+#### Request scoping through multiple Azure Front Door endpoints
+
+Create separate Azure Front Door endpoints for applications with different configuration requirements. Rather than combining multiple filter rules in a single endpoint, each application connects to its dedicated endpoint with precisely scoped filters. This approach prevents applications from accessing each other's configuration data and simplifies filter management.
+
+### Failover and load balancing
+
+Client applications rely on Azure Front Door for failover and load balancing, as they don't connect directly to App Configuration. To enable automatic failover and geo-redundant configuration delivery, configure your App Configuration replicas as origins in the Azure Front Door endpoint. For details on how origin groups improve availability and performance, see [Azure Front Door routing methods](/azure/frontdoor/routing-methods)
+
+### Caching
+
+Configure Azure Front Door cache duration to balance configuration freshness and origin load. Azure Front Door controls the caching behavior, which means updates from App Configuration can only be seen by your application after the Front Door cache expires. This cache expiration time effectively becomes the minimum time before your app can observe new configuration values, regardless of how frequently the app checks for changes. 
+
+We recommend setting Azure Front Door cache TTL to at least 10 minutes and application refresh interval to at least 1 minute. With these settings, configuration updates may take up to 11 minutes to propagate: Azure Front Door 10 minute cache TTL plus up to 1 minute until the next application refresh. 
+
+You can choose appropriate refresh interval values that fit your application. Shorter cache durations will increase the number of requests routed through Azure Front Door. This model provides eventual consistency, not real-time propagation, which is expected for CDN-based delivery. Learn more about [Caching with Azure Front Door](/azure/frontdoor/front-door-caching).
+
+> [!NOTE]
+> Azure Front Door makes no guarantees about the amount of time that the content is stored in the cache. Cached content may be removed from the edge cache before the content expiration if the content isn't frequently used. Additionally, if App Configuration is unreachable, Azure Front Door may continue serving stale data from cache to maintain application availability. 
+
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Set up Azure Front Door with App Config](./how-to-connect-azure-front-door.md)
+
+## Related content
+
+- [Load Configuration from Azure Front Door in Client Applications](./how-to-load-azure-front-door-configuration-provider.md)
+

articles/azure-app-configuration/configuration-provider-overview.md

@@ -73,6 +73,8 @@ Distributed Tracing | [GA](./reference-dotnet-provider.md#distributed-tracing) |
 Health Check | [GA](./reference-dotnet-provider.md#health-check) | GA | WIP | WIP | WIP | N/A 
 Select by Tag Filters | [GA](./reference-dotnet-provider.md#load-specific-key-values-using-selectors) | WIP | GA | GA | [GA](./reference-javascript-provider.md#tag-filters) | [GA](./reference-go-provider.md#tag-filters)
 Snapshot Reference | [GA](./reference-dotnet-provider.md#snapshot-reference) | WIP | WIP | WIP | WIP | WIP
+Load from Azure Front Door | [Preview](./reference-dotnet-provider.md#connect-to-azure-front-door) | WIP | WIP | WIP | [Preview](./reference-javascript-provider.md#connect-to-azure-front-door)  | WIP
+
 
 ## Support policy
 

articles/azure-app-configuration/faq.yml

@@ -182,6 +182,10 @@ sections:
           - **Reduce key-value revision retention** if you perform frequent key-value updates and you don't need to retain revisions for the maximum duration allowed by your App Configuration store. Revisions count toward your store's total storage usage. If the storage quota is exceeded, you'll no longer be able to create or modify key-values or feature flags.
           - **Improve your application resiliency**: Consider integrating geo-replication to allow failover and load balancing. Check the best practices for [building highly resilient applications](./howto-best-practices.md#building-applications-with-high-resiliency).
 
+      - question: How can I use App Configuration in client applications with hyperscale configuration?
+        answer: |
+          See [best practices for client applications in App Configuration](./howto-best-practices.md#client-applications-in-app-configuration)
+
       - question: Why can't I create an App Configuration store with the same name as one that I just deleted?
         answer: |
           All App Configuration stores in the Standard and Premium tiers have automatically enabled the [soft-delete](concept-soft-delete.md) feature. When a Standard or Premium tier App Configuration store is deleted, its name is reserved for the retention period. To recreate a store with the same name before the retention period expires, you need to [purge the soft-deleted store](howto-recover-deleted-stores-in-azure-app-configuration.md#list-recover-or-purge-a-soft-deleted-app-configuration-store) first, provided the store doesn't have purge protection enabled. If the purge protection is enabled, you must wait for the retention period to elapse. Use the purge function or set a shorter retention period if you often need to recreate a store with the same name. Workflows that require recreating a store with the same name should allow for one hour between purging a configuration store and performing the subsequent create. This recommendation is in place because once a purge is requested the actual cleanup of configuration store resources is performed asynchronously, requiring a bit of extra time to finalize. To avoid any need to wait, workflows that create ephemeral configuration stores are recommended to use unique names.

articles/azure-app-configuration/how-to-connect-azure-front-door.md

@@ -16,7 +16,7 @@ Azure App Configuration supports direct integration with Azure Front Door (previ
 You can connect your App Configuration store to existing Azure Front Door profiles or create new profiles directly from the App Configuration interface for a quick start.
 
 > [!NOTE]
-> This feature is only available in the Azure public cloud.
+> This feature is currently available only in the Azure public cloud.
 
 ## Prerequisites
 
@@ -29,9 +29,9 @@ Before you begin, ensure you have:
 - App Configuration Data Owner or App Configuration Data Reader role 
 - Basic understanding of [CDN and content delivery concepts](/azure/frontdoor/front-door-overview)
 
-## Set up the Azure Front Door integration
+## Connect to Azure Front Door
 
-To integrate Azure Front Door with your App Configuration store, follow these steps:
+To connect Azure Front Door with your App Configuration store, follow these steps:
 
 1. In the Azure portal, navigate to your App Configuration store.
 
@@ -88,13 +88,17 @@ Create a new Azure Front Door profile and connect it to your App Configuration s
 1. **Filter Configuration to scope the request**: Configure one or more filters to control which requests pass through Azure Front Door. This prevents accidental exposure of sensitive configuration and ensures only the settings your application needs are accessible. The filters here must exactly match those used in your application code; otherwise, requests will be rejected by Azure Front Door.
 
    > [!NOTE]
-   > To set up the right scoping filters, you need to know what filters are used in your application to load key-values or snapshots from App Configuration. For example, if your application needs to load keys that start with the *App1:* prefix, and a snapshot whose name is *MySnapshot*, enter those values in the Key and Snapshot name filters as shown in the screenshot above.
+   > To configure scoping filters correctly, ensure that the prefix filter in Azure Front Door exactly matches the selector your application uses to load keys from App Configuration. For example, if your application loads keys using the prefix "App1:", configure the same Starts with = "App1:" key filter in Azure Front Door. If your application instead uses a more specific key prefix such as "App1:Version", but Azure Front Door is allowlisted for "App1:" key filter (or vice versa), the request will be rejected because the selectors do not match exactly.
 
    - **Key**: The key filter to apply when querying Azure App Configuration for key-values. Reserved characters: asterisk (`*`), comma (`,`), and backslash (`\`) must be escaped using a backslash (`\`) when filtering multiple key-values.
    - **Label**: The label filter to apply when querying Azure App Configuration for key-values. Reserved characters: asterisk (`*`), comma (`,`), and backslash (`\`) must be escaped using a backslash (`\`) when filtering multiple key-values.
    - **Tags**: The tag name and value filter to apply when querying Azure App Configuration for key-values. Reserved characters: asterisk (`*`), comma (`,`), backslash (`\`), and equals (`=`) must always be escaped using a backslash (`\`).
    - **Snapshot name**: Name of snapshot whose content should be accessible through this Azure Front Door endpoint. You can select one or more snapshots to restrict access to specific snapshots.
 
+   > [!NOTE]
+   > If your application loads feature flags, provide ".appconfig.featureflag/{YOUR-FEATURE-FLAG-PREFIX}" filter for the Key with *Starts with* operator.
+
+
 1. Select **Create & Connect** to create the profile and establish the connection.
 
 ### Connect to an existing Azure Front Door profile
@@ -130,7 +134,7 @@ The table displays:
 
 Monitor for warnings such as "Identity not configured" which indicate additional setup requirements. Address these warnings promptly to ensure proper functionality.
 
-## Disconnect Azure Front Door integration
+## Disconnect Azure Front Door
 
 When you no longer need to manage your Front Door profile through App Configuration, disconnect your App Configuration store from Azure Front Door.
 
@@ -151,8 +155,14 @@ If you encounter issues while connecting Azure Front Door to your App Configurat
 - From Front Door portal, make sure that the origin is correctly set up to be able to authenticate with the App Configuration origin. Learn how to [use managed identities to authenticate to origins](/azure/frontdoor/origin-authentication-with-managed-identities)
 - Verify that the Azure Front Door resource provider is registered in your subscription.
 
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Load Configuration from Azure Front Door in Client Applications](./how-to-load-azure-front-door-configuration-provider.md)
+
 ## Related content
 
+- [Configuration Management for Client Applications](./concept-hyperscale-client-configuration.md)
 - [Learn more about Azure Front Door](/azure/frontdoor/)
 - [Configure App Configuration feature flags](/azure/azure-app-configuration/concept-feature-management)
 - [Set up managed identities](/azure/active-directory/managed-identities-azure-resources/)