Quickstart: Quarkus extension for Azure Blob Storage

Get started with the Quarkus extension for Azure Blob Storage to manage blobs and containers. In this article, you follow steps to try out example code for basic tasks.

Reference documentation | Library source code | Package (Maven) | Sample

Prerequisites

• Azure account with an active subscription - create an account for trial.
• Azure CLI - Install the Azure CLI 2.62.0 or above to run Azure CLI commands.
• Azure Storage account - create a storage account.
• Java Development Kit (JDK) version 17 or above.
• Apache Maven.

Setting up

This section walks you through preparing a project to work with the Quarkus extensions for Azure Blob Storage.

Download the sample application

The sample application used in this quickstart is a basic Quarkus application.

Use git to download a copy of the application to your development environment, and navigate to the storage-blob-quarkus directory.

git clone https://github.com/Azure-Samples/quarkus-azure.git
cd quarkus-azure
git checkout 2025-01-20
cd storage-blob-quarkus

Authenticate to Azure and authorize access to blob data

Application requests to Azure Blob Storage must be authorized. Using DefaultAzureCredential and the Azure Identity client library is the recommended approach for implementing passwordless connections to Azure services in your code, including Blob Storage. The Quarkus extension for Azure services supports this approach.

DefaultAzureCredential is a credential chain implementation provided by the Azure Identity client library for Java. DefaultAzureCredential supports multiple authentication methods and determines which method to use at runtime. This approach enables your app to use different authentication methods in different environments (local vs. production) without implementing environment-specific code.

The order and locations in which DefaultAzureCredential looks for credentials can be found in the Azure Identity library overview.

In this quickstart, your app authenticates using your Azure CLI sign-in credentials when running locally. After it's deployed to Azure, your app can then use a managed identity. This transition between environments doesn't require any code changes.

Assign roles to your Microsoft Entra user account

When developing locally, make sure that the user account that is accessing blob data has the correct permissions. You'll need Storage Blob Data Contributor to read and write blob data. To assign yourself this role, you'll need to be assigned the User Access Administrator role, or another role that includes the Microsoft.Authorization/roleAssignments/write action. You can assign Azure RBAC roles to a user using the Azure portal, Azure CLI, or Azure PowerShell. You can learn more about the available scopes for role assignments on the scope overview page.

In this scenario, you'll assign permissions to your user account, scoped to the storage account, to follow the Principle of Least Privilege. This practice gives users only the minimum permissions needed and creates more secure production environments.

The following example will assign the Storage Blob Data Contributor role to your user account, which provides both read and write access to blob data in your storage account.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

Sign-in and connect your app code to Azure using DefaultAzureCredential

You can authorize access to data in your storage account using the following steps:

1. Make sure you're authenticated with the same Microsoft Entra account you assigned the role to on your storage account. The following example shows how to authenticate via the Azure CLI:

   az login
   

2. Make sure you provide the endpoint of your Azure Blob Storage account. The following example shows how to set the endpoint using the environment variable QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT via the Azure CLI. Replace <resource-group-name> and <storage-account-name> with your resource group and storage account names before running the command:

   export QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT=$(az storage account show \
       --resource-group <resource-group-name> \
       --name <storage-account-name> \
       --query 'primaryEndpoints.blob' \
       --output tsv)
   

Run the sample

The code example performs the following actions:

• Injects a client object that is already authorized for data access via DefaultAzureCredential using the Quarkus extension for Azure Blob Storage.
• Creates a container in a storage account.
• Uploads a blob to the container.
• Lists the blobs in the container.
• Downloads the blob data to the local file system.
• Deletes the blob and container resources created by the app.
• Deletes the local source and downloaded files.

Run the application in JVM mode by using the following command:

mvn package
java -jar ./target/quarkus-app/quarkus-run.jar

The output of the app is similar to the following example (UUID values omitted for readability):

Uploading to Blob storage as blob:
        https://mystorageacct.blob.core.chinacloudapi.cn/quickstartblobsUUID/quickstartUUID.txt

Listing blobs...
        quickstartUUID.txt

Downloading blob to
        ./data/quickstartUUIDDOWNLOAD.txt

Press the Enter key to begin clean up

Deleting blob container...
Deleting the local source and downloaded files...
Done

Before you begin the cleanup process, check your data folder for the two files. You can compare them and observe that they're identical.

Optionally, you can run the sample in native mode. To do this, you need to have GraalVM installed, or use a builder image to build the native executable. For more information, see Building a Native Executable. This quickstart uses Docker as container runtime to build a Linux native executable. If you haven't installed Docker, you can download it from the Docker website.

Run the following command to build and execute the native executable in a Linux environment:

mvn package -Dnative -Dquarkus.native.container-build
./target/storage-blob-1.0.0-SNAPSHOT-runner

Understand the sample code

Next, you walk through the sample code to understand how it works.

Inject a client object with authorized access

Working with any Azure resource using the SDK begins with creating a client object. The Quarkus extension for Azure Blob Storage automatically injects a client object with authorized access using DefaultAzureCredential.

To successfully inject a client object, first you need to add the extensions quarkus-arc and quarkus-azure-storage-blob to your pom.xml file as dependencies:

<properties>
    <quarkus.platform.version>3.17.7</quarkus.platform.version>
    <quarkus.azure.services.version>1.1.1</quarkus.azure.services.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.quarkus.platform</groupId>
            <artifactId>quarkus-bom</artifactId>
            <version>${quarkus.platform.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>io.quarkiverse.azureservices</groupId>
            <artifactId>quarkus-azure-services-bom</artifactId>
            <version>${quarkus.azure.services.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-arc</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkiverse.azureservices</groupId>
        <artifactId>quarkus-azure-storage-blob</artifactId>
    </dependency>
</dependencies>

The quarkus-arc extension is required to use the @Inject annotation to inject the client object into your application code. The quarkus-bom and quarkus-azure-services-bom dependencies are used to manage the versions of the Quarkus platform and the Quarkus extension for Azure services.

Next, you can inject the client object into your application code using the @Inject annotation:

@Inject
BlobServiceClient blobServiceClient;

That's all you need to code to get a client object using the Quarkus extension for Azure Blob Storage. To make sure the client object is authorized to access your storage account at runtime, you need to follow steps in the previous section Authenticate to Azure and authorize access to blob data before running the application.

Manage blobs and containers

The following code example shows how to create a container, upload a blob, list blobs in a container, and download a blob.

// Create a unique name for the container
String containerName = "quickstartblobs" + java.util.UUID.randomUUID();

// Create the container and return a container client object
BlobContainerClient blobContainerClient = blobServiceClient.createBlobContainer(containerName);

// Create the ./data/ directory and a file for uploading and downloading
String localPath = "./data/";
new File(localPath).mkdirs();
String fileName = "quickstart" + java.util.UUID.randomUUID() + ".txt";

// Get a reference to a blob
BlobClient blobClient = blobContainerClient.getBlobClient(fileName);

// Write text to the file
FileWriter writer = null;
try
{
    writer = new FileWriter(localPath + fileName, true);
    writer.write("Hello, World!");
    writer.close();
}
catch (IOException ex)
{
    System.out.println(ex.getMessage());
}

System.out.println("\nUploading to Blob storage as blob:\n\t" + blobClient.getBlobUrl());

// Upload the blob
blobClient.uploadFromFile(localPath + fileName);

System.out.println("\nListing blobs...");

// List the blob(s) in the container.
for (BlobItem blobItem : blobContainerClient.listBlobs()) {
    System.out.println("\t" + blobItem.getName());
}

// Download the blob to a local file

// Append the string "DOWNLOAD" before the .txt extension for comparison purposes
String downloadFileName = fileName.replace(".txt", "DOWNLOAD.txt");

System.out.println("\nDownloading blob to\n\t " + localPath + downloadFileName);

blobClient.downloadToFile(localPath + downloadFileName);

File downloadedFile = new File(localPath + downloadFileName);
File localFile = new File(localPath + fileName);

// Clean up resources
System.out.println("\nPress the Enter key to begin clean up");
System.console().readLine();

System.out.println("Deleting blob container...");
blobContainerClient.delete();

System.out.println("Deleting the local source and downloaded files...");
localFile.delete();
downloadedFile.delete();

System.out.println("Done");

These operations are similar to the ones described in Quickstart: Azure Blob Storage client library for Java SE. For more detailed code explanations, see the following sections in that quickstart:

• Create a container
• Upload blobs to a container
• List the blobs in a container
• Download blobs
• Delete a container

Clean up

You can choose to follow the links in the Next steps section to deploy the Quarkus application to Azure. Or you can clean up the storage account by deleting the resource group. For more information, see Azure Resource Manager resource group and resource deletion.

Next steps