Coding Azure 22: Adding Configuration Information to an App Configuration Service

With the App Configuration service we built last time, we can now apply settings and configuration information. Here’s a look at how to do that and what the options are.

In my last post, Coding Azure 21: Managing Configuration Information with App Configuration, as part of creating the infrastructure to share configuration data among the components of a distributed application, I walked through creating an App Configuration service.

This is the post where I’ll describe the varieties of settings you can add and why you should pick any one of them. My next post will describe how to access those settings from your application code.

While I’ve positioned App Configuration as infrastructure for distributed applications, this post will show that an App Configuration service is worth considering as your primary source for configuration information. And the conversion doesn’t have to be difficult: If you have settings in an App Service’s Environment variables that you would like to add to your App Configuration service, you can use the Import/Export page under the Operations node in the menu on the left of your service to copy those settings in your service.

In addition, because of the way that App Configuration settings are accessed from your application, you may only have to tweak some code in your application’s Program.cs file to have your application use its settings from an App Configuration service (see my next post).

Adding Settings

First, of course, surf to your App Configuration service and then, in the menu on the left, expand the Operations node and click on the Configuration explorer node to open a page on the right. To add a setting, click on the +Create choice at the left end of the top menu on the Configuration explorer page.

When adding a setting, you must set its Key property and, optionally, its Label property. Those two values, together, uniquely identify a setting. You can have multiple settings with the same value for their Key property, provided all those settings have different values in their Label property. This enables you to have multiple settings with a Key property set to “A/R Queue Name,” but with different Labels—“dev,” “test” and “production.” In your application code, you can choose which Keys you want based on their labels.

Some advice on Labels: They cannot include asterisks (*) or commas (,) and, if your Label includes a backslash (/), you must insert the backslash twice. It’s also a good idea for your Labels to match any environment names that you’re using in your application to signal whether your application is running in production or test or development (and, be aware, Label names are case-sensitive when you use them in your code to retrieve a value).

It’s also a good idea to establish a naming convention for your Keys that will gather together settings that your application will retrieve as a group. The recommended best practice is to use some delimiter (typically a colon, “:”) to separate out the levels of grouping for your keys. A typical set of Key values might look like this:

SalesOrder:Invoicing:WebServiceUrl
SalesOrder:Invoicing:AuthorizationKey
SalesOrder:Products:WebServiceURL

If this naming convention looks suspiciously like the syntax used to retrieve values from an appsettings.json file in an ASP.NET Core application … well, that’s not by accident (as I’ll cover in my next post). This naming convention lets you treat separate settings in your service like sections in an appsettings file. In your application, you could, for example, retrieve all three settings by asking for a section called “SalesOrder”.

You can add one of four kinds of settings:

• Key Value pair
• Key Vault reference
• Snapshot reference
• AI configuration

Key Value Pairs

This is the default choice for an App Configuration setting—a value associated with a Key and an optional Label. If you select this option, a panel will open on the right that will let you specify, in addition to a Key and Label, a:

• Value: This can be anything from a single digit to a JSON document
• Content type: A hint to the application about how to parse the value in your setting.

If you put a JSON document in the Value, you should set Content type to application/json to support the default tools you’ll use when reading your settings.

Other than that, the Content type setting doesn’t make any difference to how a Key Value setting is processed unless you’re taking advantage of App Configuration’s support for Features Flags (and Content Type can’t even be retrieved in your application using the default tools).

Adding a setting with JSON in its Value can simplify moving settings from an appsettings.json file to your App Configuration service.

Key Vault References

This setting holds the information to access secret in one of your Key Vaults. In addition to preventing sensitive information from being stored in your App Configuration service, this choice allows you to split responsibility between the person making the secret available to your application (in the App Configuration service) and the person managing the secret (in the Key Vault).

In your application, the default tools you’ll use in your application for retrieving settings will access the Key Vault to retrieve the secret. This means that only your application will need permission to access the Key Vault (i.e., not your App Configuration service).

It will simplify the code your application needs to access values in the Key Vault if you use only one Key Vault from any App Configuration service. If that’s not possible, you can avoid complicating your code if your application can use the same set of credentials for all the Key Vaults used in your service (e.g., if one Managed Identity can access all the vaults).

In addition to specifying a Key and a Label for this setting, you have two tabs for specifying how your secret will be retrieved: Browse and Input.

If you pick the Browse option, you’ll need to provide:

• The subscription, resource group and name of the Key Vault is assigned to
• The key for the secret in the Key Vault
• The version of the secret

If you leave the version dropdown list blank or select Latest version from the dropdown list, you’ll always retrieve the latest value for the key (probably what you want). If you explicitly select the current version of the key from the dropdown list, then you’ll always get that version (i.e., if the secret is updated with a new version, your application will not get that new, “latest” version).

Using the Browse option, however, does require that you have the required permissions to browse the Key Vault. If you can’t browse the key vault, you’ll have to use the Input option.

With the Input option, you enter the URL that leads to the secret. Since that URL contains the vault name, the secret name and the version you want, it’s not completely opaque to the next developer who will be working with your service.

AI Configuration

This setting type allows you to store configuration settings for a large language model (e.g., the number of tokens the model allocates for processing).

App Snapshot Reference and Snapshots

A snapshot reference points to an App Configuration snapshot, which is a collection of settings with their values at the time the snapshot was created. Snapshots can be useful in, for example, getting a “frozen” view of your settings before a rollout or to capture the “last known good” state of some settings.

The values in the snapshot’s collection of settings are read-only/immutable: If you change the values in a setting that’s part of a snapshot, those changes are not reflected in the snapshot. The snapshots themselves cannot be deleted (they can, however, be archived and—eventually—will be purged).

Creating a Snapshot

To create a snapshot, in the menu on the left of your service, under the Operations node, select Snapshots to open a page on the right. Then click on the +Create menu choice at the left end of the menu across the top of the page to open the Create a snapshot page.

On the Create a snapshot page, give your snapshot a:

• Name: You’ll use this name when adding a Snapshot Reference to your settings in Configuration Explorer
• Filter: You must add at least one filter (but no more than three) to select the settings that will be added to the snapshot.
• Composition Type: Controls how the filters are used to select settings.
• Recovery Options: This allows you to specify how long a snapshot is kept after it is archived (this is separate from the soft delete option you set when you created your service). The maximum length of time is controlled by the pricing plan for your service.
• Tags: You can associate tags with your snapshot either by adding them directly using the Click to add tags link at the top of the page or conditionally by associating a tag with a filter.

Selecting Snapshot Settings

Adding a filter defines the criteria to be used to select the settings to be added to your snapshot. You can specify up to three filters, with each filter being a combination of Key and Label values:

• Key: When setting the Key value in a filter you have four choices:
  » Key values that are an exact match to the text you enter in the criteria
  » Key values that start with the text you enter
  » Key values that match a list of comma-delimited text you enter
  » All Key values
• Labels: When setting the Label value, the only criteria you can pick is an exact match to the text you enter

As an example: If you wanted to create a snapshot containing all the settings labeled “production,” you would create a filter with the Key criteria set to “All” and Label criteria set to “production.”

The snapshot’s Composition type option controls how many different versions for any Key value will be added to the snapshot.

If the Composition type is set to “Key” (the default), then only one setting for any Key value will be added to the snapshot (this also simplifies using the snapshot in your application). If there are multiple settings with the same Key value, then only the setting that matches the rest of the criteria in the last filter in the snapshot for that Key will be added to the snapshot.

This means, for example, that if you have two filters the same criteria for a Key (e.g., “QueueName”) and the Label criteria for the last of those two filters is that the Label must be set to “dev,” then only one setting will be added: the setting with its Key set to “QueueName” and its Label set to “dev.” The Label criteria on the first filter is irrelevant.

If you set the composition type to “Key-Label” then you can have multiple settings with the same Key in the snapshot, each with a different label. Be aware that this will make it more difficult to use the snapshot in your application.

You can also set how long, in days, a snapshot will be kept after you archive it and before it is purged (the upper limit is set by your App Configuration’s pricing plan). You cannot create a new snapshot with the same name as either an existing or archived snapshot (and, by the way, even if you set the archive time to zero, your snapshot is still kept for one hour after you archive it).

After you’ve defined your snapshot, click on the Create button at the bottom of the page. The snapshot will be created and the settings selected in your filters with their current values will be added to the snapshot.

You can view your list of snapshots available from the Snapshots node in the menu on the left of your service. In that list, you can use the View choice from the menu at the right end of the snapshot to see what settings were captured in your snapshot and what values were saved.

Creating a Snapshot Reference

You can now return to Configuration explorer and create a Snapshot reference setting that uses your snapshot. You’ll be able to select your Snapshot from a dropdown list.

Securing the Service to Your Application

Your best choice for controlling access to your service from your application is to assign the application component that will be accessing your service a Managed Identity through the App Service that’s hosting that application component.

For your application or Web Service to read settings, you need to assign it the Managed Identity Data Reader role:

1. In the menu on the left, click on Access control (IAM) to open a page on the right.
2. On that page, click on the Add role assignment button to start the wizard.
3. In the textbox enter App Configuration Data Reader and click on the role when it appears to select it.
4. Click the Next button at the bottom of the page.
5. On the next page of the wizard, select the Managed identity radio button.
6. Click the +Select members link to open the Select managed identities panel on the right.
7. From the Subscription dropdown list, select the subscription for the Managed Identity your application will be using.
8. From the Managed Identity textbox, select User-assigned managed identity.
9. From the list of Managed Identities, select the identity your application will be using.
10. Click the Select button at the bottom of the page to close the panel and return to the wizard.
11. Click the Review + assign button at the bottom of the page to assign that Managed Identity to the role.
12. Click the Review + assign button at the bottom of the page to give that Managed Identity access to your App Configuration service and return to the Access Control (IAM) page.

Now that you’ve created an App Configuration service and loaded it with settings, you’ll want to read those settings from your application. That’s my next post. Stay tuned.