Quarkus Azure App Configuration Extension

Quarkus Azure Services Extensions are developed and supported by Microsoft as part of their commitment to Open Standard Enterprise Java. For more information, see Jakarta EE on Azure.

Azure App Configuration is a fast, scalable parameter storage for app configuration. This extension allows to inject a io.smallrye.config.SmallRyeConfig object inside your Quarkus application so you can access the app configuration stored in Azure.

Installation

If you want to use this extension, you need to add the io.quarkiverse.azureservices:quarkus-azure-app-configuration extension first to your build file.

For instance, with Maven, add the following dependency to your POM file:

<dependency>
    <groupId>io.quarkiverse.azureservices</groupId>
    <artifactId>quarkus-azure-app-configuration</artifactId>
    <version>1.1.2</version>
</dependency>

How to Use It

Once you have added the extension to your project, follow the next steps, so you can inject io.smallrye.config.SmallRyeConfig object in your application to store and read blobs.

Setup your Azure Environment

First thing first. For this sample to work, you need to have an Azure account as well as Azure CLI installed. The Azure CLI is available to install in Windows, macOS and GNU/Linux environments. Checkout the installation guide. Then, you need an Azure subscription and log into it by using the az login command. You can run az version to find the version and az upgrade to upgrade to the latest version.

Create an Azure resource group with the az group create command. A resource group is a logical container into which Azure resources are deployed and managed.

az group create \
    --name rg-quarkus-azure-app-configuration \
    --location eastus

Create an Azure App Configuration store with the following command:

az appconfig create \
    --name appcs-quarkus-azure-app-configuration \
    --resource-group rg-quarkus-azure-app-configuration \
    --location eastus

Then create some key-value properties with the following commands:

az appconfig kv set --name appcs-quarkus-azure-app-configuration --yes --key myKeyOne --value "Value 1"
az appconfig kv set --name appcs-quarkus-azure-app-configuration --yes --key myKeyTwo --value "Value 2"

You can list the key-value properties with the following command:

az appconfig kv list --name appcs-quarkus-azure-app-configuration

If you log into the Azure portal, you can see the resource group and the key-value you created.

Azure Portal showing the app configuration

Configure the Azure App Configuration Client

As you can see below in the Configuration Reference section, the property quarkus.azure.app.configuration.endpoint is required if the extension is enabled.

For that, execute the following Azure CLI command:

export QUARKUS_AZURE_APP_CONFIGURATION_ENDPOINT=$(az appconfig show \
  --resource-group rg-quarkus-azure-app-configuration \
  --name appcs-quarkus-azure-app-configuration \
  --query endpoint -o tsv)

Notice that you get the endpoint and set it to environment variable QUARKUS_AZURE_APP_CONFIGURATION_ENDPOINT, instead of setting it to property quarkus.azure.app.configuration.endpoint in the application.properties file. Although technically both approaches work, using environment variable is recommended and more secure as there’s no risk of committing the connection information to source control.

To be able to connect to the Azure App Configuration that you’ve just created, you have two options to authenticate to Azure App Configuration, either with Microsoft Entra ID or access keys. The following sections describe how to authenticate with both options. For optimal security, it is recommended to use Microsoft Entra ID for authentication.

Authenticating to Azure App Configuration with Microsoft Entra ID

You can authenticate to Azure App Configuration with Microsoft Entra ID. Run the following commands to assign the App Configuration Data Reader role to the signed-in user as a Microsoft Entra identity.

# Retrieve the app configuration resource ID
APP_CONFIGURATION_RESOURCE_ID=$(az appconfig show \
    --resource-group rg-quarkus-azure-app-configuration \
    --name appcs-quarkus-azure-app-configuration \
    --query 'id' \
    --output tsv)
# Assign the "App Configuration Data Reader" role to the current signed-in identity
az role assignment create \
    --assignee $(az ad signed-in-user show --query 'id' --output tsv) \
    --role "App Configuration Data Reader" \
    --scope $APP_CONFIGURATION_RESOURCE_ID

Authenticating to Azure App Configuration with access keys

You can also authenticate to Azure App Configuration with access keys. Run the following commands to export the Azure App Configuration access keys as environment variables.

credential=$(az appconfig credential list \
    --name appcs-quarkus-azure-app-configuration \
    --resource-group rg-quarkus-azure-app-configuration \
    | jq 'map(select(.readOnly == true)) | .[0]')
export QUARKUS_AZURE_APP_CONFIGURATION_ID=$(echo "${credential}" | jq -r '.id')
export QUARKUS_AZURE_APP_CONFIGURATION_SECRET=$(echo "${credential}" | jq -r '.value')

Notice that you get the id and secret and set them to environment variables QUARKUS_AZURE_APP_CONFIGURATION_ID and QUARKUS_AZURE_APP_CONFIGURATION_SECRET, instead of setting them to properties quarkus.azure.app.configuration.id and quarkus.azure.app.configuration.secret in the application.properties file, with the similar reasons as mentioned above.

Inject the SmallRyeConfig

Now that your Azure environment is ready and that you have configured the extension, you can inject the SmallRyeConfig object in your application, so you can interact with Azure App Configuration.

@Path("/config")
@Produces(MediaType.APPLICATION_JSON)
public class ConfigResource {

  @Inject
  SmallRyeConfig config;

  @GET
  @Path("/{name}")
  public Response configValue(@PathParam("name") final String name) {
      return Response.ok(config.getConfigValue(name)).build();
  }
}

To test this sample you can run the following cURL commands after the application is started:

  • curl -X GET localhost:8080/config/myKeyOne

  • curl -X GET localhost:8080/config/myKeyTwo

Extension Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.azure.app.configuration.enabled

The flag to enable the app configuration. If set to false, the app configuration will be disabled

Environment variable: QUARKUS_AZURE_APP_CONFIGURATION_ENABLED

boolean

true

quarkus.azure.app.configuration.endpoint

The endpoint of the app configuration. Required if quarkus.azure.app.configuration.enabled is set to true

Environment variable: QUARKUS_AZURE_APP_CONFIGURATION_ENDPOINT

string

quarkus.azure.app.configuration.id

The id of the app configuration. Required if quarkus.azure.app.configuration.enabled is set to true and access keys are used for authentication

Environment variable: QUARKUS_AZURE_APP_CONFIGURATION_ID

string

quarkus.azure.app.configuration.secret

The secret of the app configuration. Required if quarkus.azure.app.configuration.enabled is set to true and access keys are used for authentication

Environment variable: QUARKUS_AZURE_APP_CONFIGURATION_SECRET

string

quarkus.azure.app.configuration.labels

The label filter of the app configuration. Use comma as separator for multiple label names

Environment variable: QUARKUS_AZURE_APP_CONFIGURATION_LABELS

string