Quarkus Azure Services Extensions
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-services
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.0.5</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 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](_images/quarkus-azure-app-configuration-portal.png)
Configure the Azure App Configuration Client
As you can see below in the Configuration Reference section, this extension has several configuration options. To be able to connect to the Azure App Configuration that we’ve just created, you must get the URL of the endpoing, it’s id and secret. 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)
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 endpoint, id and secret and set them to environment variables QUARKUS_AZURE_APP_CONFIGURATION_ENDPOINT
, QUARKUS_AZURE_APP_CONFIGURATION_ID
and QUARKUS_AZURE_APP_CONFIGURATION_SECRET
, instead of setting them to properties quarkus.azure.app.configuration.endpoint
, quarkus.azure.app.configuration.id
and quarkus.azure.app.configuration.secret
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 credentials to source control.
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 execute this sample you can run the following cURL commands:
-
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
Type |
Default |
|
---|---|---|
The flag to enable the app configuration. If set to false, the app configuration will be disabled Environment variable: |
boolean |
|
The endpoint of the app configuration. Required if quarkus.azure.app.configuration.enabled is set to true Environment variable: |
string |
|
The id of the app configuration. Required if quarkus.azure.app.configuration.enabled is set to true Environment variable: |
string |
|
The secret of the app configuration. Required if quarkus.azure.app.configuration.enabled is set to true Environment variable: |
string |
|
The label filter of the app configuration. Use comma as separator for multiple label names Environment variable: |
string |
Quarkus Azure Key Vault 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 Key Vault is a cloud service for securely storing and accessing secrets. A secret is anything that you want to tightly control access to, such as API keys, passwords, certificates, or cryptographic keys. This extension allows you to create and retrieve secret from Azure Key Vault by injecting the following object inside your Quarkus application.
-
com.azure.security.keyvault.secrets.SecretClient
-
com.azure.security.keyvault.secrets.SecretAsyncClient
The extension produces SecretClient and SecretAsyncClient using DefaultAzureCredential. Developers who want more control or whose scenario isn’t served by the default settings should build client using other credential types.
Installation
If you want to use this extension, you need to add the io.quarkiverse.azureservices:quarkus-azure-services
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-keyvault</artifactId>
<version>1.0.5</version>
</dependency>
How to Use It
Once you have added the extension to your project, follow the next steps, so you can inject com.azure.security.keyvault.secrets.SecretClient
or com.azure.security.keyvault.secrets.SecretAsyncClient
object in your application to manage secret.
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 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-keyvault \
--location eastus
Create a general-purpose key vault with the following command:
az keyvault create --name kvquarkusazurekv0423 \
--resource-group rg-quarkus-azure-keyvault \
--location eastus \
--enable-rbac-authorization false
Key Vault provides secure storage of generic secrets, such as passwords and database connection strings. All secrets in your key vault are stored encrypted. The Azure Key Vault service encrypts your secrets when you add them, and decrypts them automatically when you read them.
Access Control for secrets managed in Key Vault, is provided at the level of the Key Vault. The following command uses your Microsoft Entra ID to authorize the operation to manage secret. Even if you are the key vault owner, you need explicit permissions to perform operations against secret.
Assign all secret permissions(backup, delete, get, list, purge, recover, restore, set) to yourself:
az ad signed-in-user show --query id -o tsv \
| az keyvault set-policy \
--name kvquarkusazurekv0423 \
--object-id @- \
--secret-permissions all
If you log into the Azure portal, you can see the key vault you created. Select Objects → Secrets, you will find the Secrets page.
![Azure Portal showing Key Vault Secrets](_images/quarkus-azure-keyvault-secret-portal.png)
Configure the Azure Key Vault Secret Client
As you can see below in the Configuration Reference section, the configuration option quarkus.azure.keyvault.secret.endpoint
is mandatory.
To get the endpoint, execute the following Azure CLI command:
export QUARKUS_AZURE_KEYVAULT_SECRET_ENDPOINT=$(az keyvault show --name kvquarkusazurekv0423 \
--resource-group rg-quarkus-azure-keyvault \
--query properties.vaultUri \
--output tsv)
Notice that you get the endpoint and set it to environment variable QUARKUS_AZURE_KEYVAULT_SECRET_ENDPOINT
, instead of setting it to property quarkus.azure.keyvault.secret.endpoint
in the application.properties
file.
Although technically both approaches work, using environment variable is recommended, more flexible and more secure as there’s no risk of committing the endpoint to source control.
Inject the Azure Key Vault Secret Client
Now that your Azure environment is ready and that you have configured the extension, you can inject the com.azure.security.keyvault.secrets.SecretClient
object in your application, so you can interact with Azure Key Vault Secret.
This is a Quarkus CLI application. The application will:
-
Ask for a secret value.
-
Create a secret with name
mySecret
and set its value. -
Retrieve and print the secret value.
-
Delete the secret.
You can build and run the application in development mode using command:
quarkus dev
@QuarkusMain
public class KeyVaultSecretApplication implements QuarkusApplication {
@Inject
SecretClient secretClient;
@Override
public int run(String... args) throws Exception {
Console con = System.console();
String secretName = "mySecret";
System.out.println("Create secret: " + secretName);
System.out.println("Please provide the value of your secret > ");
String secretValue = con.readLine();
System.out.println("Creating a secret called '" + secretName + "' with value '" + secretValue + "' ... ");
secretClient.setSecret(new KeyVaultSecret(secretName, secretValue));
System.out.println("Retrieving your secret...");
KeyVaultSecret retrievedSecret = secretClient.getSecret(secretName);
System.out.println("Your secret's value is '" + retrievedSecret.getValue() + "'.");
System.out.println("Deleting your secret ... ");
SyncPoller<DeletedSecret, Void> deletionPoller = secretClient.beginDeleteSecret(secretName);
deletionPoller.waitForCompletion();
System.out.println("done.");
return 0;
}
}
After running the application, if you log into the Azure portal, you can see the key vault and the secret you created. As the secret is deleted, you will find the secret from Objects → Secrets → Manage deleted secrets.
![Azure Portal showing the deleted secrets](_images/quarkus-azure-keyvault-deleted-secret-portal.png)
You can also inject com.azure.security.keyvault.secrets.SecretAsyncClient
object to your application. For more usage, see com.azure.security.keyvault.secrets.secretasyncclient.
Extension Configuration Reference
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Type |
Default |
|
---|---|---|
The flag to enable the key vault secret. If set to false, the key vault secret will be disabled Environment variable: |
boolean |
|
The endpoint of Azure Key Vault Secret. Required if quarkus.azure.keyvault.secret.enabled is set to true Environment variable: |
string |
Quarkus Azure Blob Storage 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 Blob Storage is a massively scalable and secure object storage for cloud-native workloads, archives, data lakes, high-performance computing, and machine learning.
This extension allows you to store and retrieve blobs from Azure Blob Storage by injecting a com.azure.storage.blob.BlobServiceClient
or com.azure.storage.blob.BlobServiceAsyncClient
object inside your Quarkus application.
This is a step by step guide on how to use the Quarkus Azure Blob Storage extension. If you’re looking for a complete code sample, you can find it in the Azure Blob Storage sample.
Installation
If you want to use this extension, you need to add the io.quarkiverse.azureservices:quarkus-azure-services
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-storage-blob</artifactId>
<version>1.0.5</version>
</dependency>
How to Use It
Once you have added the extension to your project, follow the next steps, so you can inject com.azure.storage.blob.BlobServiceClient
or com.azure.storage.blob.BlobServiceAsyncClient
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 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-storage-blob \
--location eastus
Create a general-purpose storage account with the following command:
az storage account create \
--name stquarkusazurestorageblo \
--resource-group rg-quarkus-azure-storage-blob \
--location eastus \
--sku Standard_ZRS \
--encryption-services blob
If you log into the Azure portal, you can see the resource group and the storage account you created.
![Azure Portal showing the Azure storage account](_images/quarkus-azure-storage-blob-azure-portal1.png)
Blobs are always uploaded into a container. You can organize groups of blobs in containers similar to the way you organize your files on your computer in folders. This guide will use the Azure Storage Blob client to create the container if it doesn’t exist. Alternatively, follow instructions in Create a container if you want to create a container before uploading blobs.
Configure the Azure Storage Blob Client
As you can see below in the Configuration Reference section, this extension has several configuration options.
But one of them is mandatory, and that is the quarkus.azure.storage.blob.connection-string
.
To get the connection string, execute the following Azure CLI command:
export QUARKUS_AZURE_STORAGE_BLOB_CONNECTION_STRING=$(az storage account show-connection-string \
--resource-group rg-quarkus-azure-storage-blob \
--name stquarkusazurestorageblo \
--output tsv)
echo "QUARKUS_AZURE_STORAGE_BLOB_CONNECTION_STRING is: ${QUARKUS_AZURE_STORAGE_BLOB_CONNECTION_STRING}"
Notice that you get the connection string and set it to environment variable QUARKUS_AZURE_STORAGE_BLOB_CONNECTION_STRING
, instead of setting it to property quarkus.azure.storage.blob.connection-string
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 string to source control.
Inject the Azure Storage Blob Client
Now that your Azure environment is ready and that you have configured the extension, you can inject the com.azure.storage.blob.BlobServiceClient
object in your imperative application or inject the com.azure.storage.blob.BlobServiceAsyncClient
object in your reactive application, so you can interact with Azure Blob Storage.
Use the BlobServiceClient in an imperative application
The uploadBlob
method first creates the container container-quarkus-azure-storage-blob
, sets some text to a text file, and then uploads the text to the container.
The downloadBlob
method downloads the text file from the container and prints the text to the console.
To execute this sample you can run the following cURL commands:
-
curl -X POST localhost:8080/quarkus-azure-storage-blob
-
curl localhost:8080/quarkus-azure-storage-blob
@Path("/quarkus-azure-storage-blob")
@ApplicationScoped
public class StorageBlobResource {
@Inject
BlobServiceClient blobServiceClient;
@POST
public Response uploadBlob() {
BlobContainerClient blobContainerClient = blobServiceClient
.createBlobContainerIfNotExists("container-quarkus-azure-storage-blob");
BlobClient blobClient = blobContainerClient.getBlobClient("quarkus-azure-storage-blob.txt");
blobClient.upload(BinaryData.fromString("Hello quarkus-azure-storage-blob at " + LocalDateTime.now()), true);
return Response.status(CREATED).build();
}
@GET
public String downloadBlob() {
BlobContainerClient blobContainerClient = blobServiceClient
.getBlobContainerClient("container-quarkus-azure-storage-blob");
BlobClient blobClient = blobContainerClient.getBlobClient("quarkus-azure-storage-blob.txt");
return blobClient.downloadContent().toString();
}
}
You can go back to the Azure portal and see the container container-quarkus-azure-storage-blob
and the blob quarkus-azure-storage-blob.txt
that you’ve created.
![Azure Portal showing the content of the file uploaded with the BlobServiceClient object](_images/quarkus-azure-storage-blob-azure-portal2.png)
Use the BlobServiceAsyncClient in a reactive application
Similarly, the uploadBlob
method first creates the container container-quarkus-azure-storage-blob-async
, sets some text to a text file, and then uploads the text to the container.
The downloadBlob
method downloads the text file from the container and prints the text to the console.
To execute this sample you can run the following cURL commands:
-
curl -X POST localhost:8080/quarkus-azure-storage-blob-async
-
curl localhost:8080/quarkus-azure-storage-blob-async
@Path("/quarkus-azure-storage-blob-async")
@ApplicationScoped
public class StorageBlobAsyncResource {
@Inject
BlobServiceAsyncClient blobServiceAsyncClient;
@POST
public Uni<Response> uploadBlob() {
Mono<BlockBlobItem> blockBlobItem = blobServiceAsyncClient
.createBlobContainerIfNotExists("container-quarkus-azure-storage-blob-async")
.map(it -> it.getBlobAsyncClient("quarkus-azure-storage-blob-async.txt"))
.flatMap(it -> it.upload(BinaryData.fromString("Hello quarkus-azure-storage-blob-async at " + LocalDateTime.now()), true));
return Uni.createFrom().completionStage(blockBlobItem.toFuture()).map(it -> Response.status(CREATED).build());
}
@GET
public Uni<Response> downloadBlob() {
BlobAsyncClient blobAsyncClient = blobServiceAsyncClient.getBlobContainerAsyncClient("container-quarkus-azure-storage-blob-async")
.getBlobAsyncClient("quarkus-azure-storage-blob-async.txt");
return Uni.createFrom()
.completionStage(blobAsyncClient.downloadContent().map(it -> Response.ok().entity(it.toString()).build())
.toFuture());
}
}
You can also go back to the Azure portal and see the container container-quarkus-azure-storage-blob-async
and the blob quarkus-azure-storage-blob-async.txt
that you’ve created.
![Azure Portal showing the content of the file uploaded with the BlobServiceAsyncClient object](_images/quarkus-azure-storage-blob-azure-portal3.png)
Extension Configuration Reference
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Type |
Default |
|
---|---|---|
Whether a health check is published in case the smallrye-health extension is present. Environment variable: |
boolean |
|
If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. When DevServices is enabled Quarkus will attempt to automatically configure and start an azurite instance when running in Dev or Test mode and when Docker is running. Environment variable: |
boolean |
|
The container image name to use, for container based DevServices providers. Environment variable: |
string |
|
Optional fixed port the Dev services will listen to. If not defined, the port will be chosen randomly. Environment variable: |
int |
|
Indicates if the azurite instance managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Azure Storage Blob starts a new container. The discovery uses the Container sharing is only used in dev mode. Environment variable: |
boolean |
|
The value of the This property is used when you need multiple shared azurite instances. Environment variable: |
string |
|
The flag to enable the storage blob. If set to false, the storage blob will be disabled Environment variable: |
boolean |
|
The connection string of Azure Storage Account. Required if quarkus.azure.storage.blob.enabled is set to true Environment variable: |
string |