Integrate Min.io sdk compatible with all S3 Api compliant vendors. Available for jdk and native runtime.

Project configuration

Once you have your Quarkus project configured you can add the minio extension to your project by running the following command in your project base directory:

./mvnw quarkus:add-extension -Dextensions="minio"

This will add the following to your pom.xml:

<dependency>
    <groupId>io.quarkiverse.minio</groupId>
    <artifactId>quarkus-minio</artifactId>
    <version>3.8.3</version>
</dependency>

Native support only

If you need configless programmatic only creation of MinioClient, then your project should be configured as followed :

<dependency>
    <groupId>io.quarkiverse.minio</groupId>
    <artifactId>quarkus-minio-native</artifactId>
    <version>3.8.3</version>
</dependency>

Usage

An io.minio.MinioClient is made available to your application as a CDI bean if configuration is found.

package com.acme.minio;

import io.minio.MinioClient;

import jakarta.enterprise.context.ApplicationScoped;

import jakarta.inject.Inject;

@ApplicationScoped
public class SampleService {

    @Inject
    MinioClient minioClient;

    @ConfigProperty(name = "minio.bucket-name")
    String bucketName;

    public String getObject(String name) {
        try (InputStream is = minio.getObject(
                GetObjectArgs.builder()
                        .bucket(bucketName)
                        .object(objectName)
                        .build())
        ) {
           // Do whatever you want...
        } catch (MinioException e) {
            throw new IllegalStateException(e);
        }
    }

}

Async Minio Client

In addition to the blocking MinioClient the extension also provides io.minio.MinioAsyncClient beans with no extra configuration effort.

Just specify MinioAsyncClient in place of MinioClient and you’re good to go.

package com.acme.minio;

import io.minio.MinioAsyncClient;

// ...

@ApplicationScoped
public class SampleService {

    @Inject
    MinioAsyncClient minioClient;

    // ...

    public String getObject(String name) {
        try (InputStream is = minio.getObject(
                GetObjectArgs.builder()
                        .bucket(bucketName)
                        .object(objectName)
                        .build())
                        .get() // Waits for the result in a blocking fashion
        ) {
           // Do whatever you want...
        } catch (MinioException e) {
            // ...
        }
    }

}

Minio Admin Client

It’s also possible to get a io.minio.admin.MinioAdminClient injected.

package com.acme.minio;

import io.minio.MinioAsyncClient;
import io.minio.admin.MinioAdminClient;
import io.minio.admin.UserInfo;

// ...

@ApplicationScoped
public class SampleService {

    @Inject
    MinioAdminClientClient minioAdminClient;

    // ...

    public void setAdminUser() {
            var nullPolicy = null;
            minioAdminClient.addUser(
               "supersecret_user_access_key",
                UserInfo.Status.ENABLED,
               "supersecret_user_secret_key",
                nullPolicy, // Allow to specify PBAC
                List.of() // Optional list of group membership
        );
    }

}

Multiple Minio clients

Configuring Multiple MinioClients

Defining multiple minio clients works exactly the same way as defining a single minio client, with one important change: you define a name.

In the following example, you have 3 different minio clients:

  • The default one,

  • A minio client named other,

  • A minio client named public,

each with its own configuration.

quarkus.minio.host=http://localhost
quarkus.minio.port=9000
quarkus.minio.secure=false
quarkus.minio.access-key=minioaccess
quarkus.minio.secret-key=miniosecret

quarkus.minio.other.enabled=true
# Deprecated key with fallback to `host`.
# Will be removed in future release.
quarkus.minio.other.url=acme
quarkus.minio.other.access-key=minioaccess
quarkus.minio.other.secret-key=miniosecret

quarkus.minio.public.enabled=true
quarkus.minio.public.host=http://public:9000
quarkus.minio.public.secure=false
quarkus.minio.public.access-key=minioaccess
quarkus.minio.public.secret-key=miniosecret

Notice there is an extra bit in the key. The syntax is as follows: quarkus.minio.[optional name.][bucket property].

Named minio clients need to specify at least one build time property so that Quarkus knows they exist. Generally this will be the enabled property.

Named MinioClient injection

When using multiple minio clients, each MinioClient also has the io.quarkiverse.minio.client.MinioQualifier qualifier with the name of the minio client as the value. Using the above properties to configure three different minio clients, you can also inject each one as follows:

@Inject
MinioClient defaultMinioClient;

@Inject
@MinioQualifier("public")
MinioClient publicMinioClient;

@Inject
@MinioQualifier("other")
MinioClient otherMinioClient;

Configuration Reference

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

Configuration property

Type

Default

quarkus.minio.devservices.enabled

Enable or disable Dev Services explicitly. Dev Services are automatically enabled unless quarkus.minio.host is set.

Environment variable: QUARKUS_MINIO_DEVSERVICES_ENABLED

boolean

true

quarkus.minio.devservices.port

Optional fixed port the dev service will listen to.

If not defined, the port will be chosen randomly.

Environment variable: QUARKUS_MINIO_DEVSERVICES_PORT

int

0

quarkus.minio.devservices.image-name

The Minio container image to use.

Environment variable: QUARKUS_MINIO_DEVSERVICES_IMAGE_NAME

string

minio/minio:RELEASE.2025-04-22T22-12-26Z

quarkus.minio.devservices.shared

Indicates if the Minio server 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 Minio starts a new container.

The discovery uses the quarkus-dev-service-minio label. The value is configured using the service-name property.

Container sharing is only used in dev mode.

Environment variable: QUARKUS_MINIO_DEVSERVICES_SHARED

boolean

true

quarkus.minio.devservices.reuse-enabled

Whether to keep Dev Service containers running after a dev mode session or test suite execution to reuse them in the next dev mode session.

Enabled by default

Environment variable: QUARKUS_MINIO_DEVSERVICES_REUSE_ENABLED

boolean

true

quarkus.minio.devservices.service-name

The value of the quarkus-dev-service-minio label attached to the started container. This property is used when shared is set to true. In this case, before starting a container, Dev Services for Minio looks for a container with the quarkus-dev-service-minio label set to the configured value. If found, it will use this container instead of starting a new one. Otherwise, it starts a new container with the quarkus-dev-service-minio label set to the specified value.

This property is used when you need multiple shared Minio servers.

Environment variable: QUARKUS_MINIO_DEVSERVICES_SERVICE_NAME

string

minio

quarkus.minio.devservices.access-key

Minio root username access key.

Environment variable: QUARKUS_MINIO_DEVSERVICES_ACCESS_KEY

string

minioaccess

quarkus.minio.devservices.secret-key

Minio root username secret key.

Environment variable: QUARKUS_MINIO_DEVSERVICES_SECRET_KEY

string

miniosecret

quarkus.minio.devservices.container-env."environment-variable-name"

Extra environment variables that will be passed to the devservice.

Environment variable: QUARKUS_MINIO_DEVSERVICES_CONTAINER_ENV__ENVIRONMENT_VARIABLE_NAME_

Map<String,String>

quarkus.minio.enabled

Should the extension provide a MinioClient. If set to false, you will have to create the clients yourself, but will still benefit the native compatibility work.

Environment variable: QUARKUS_MINIO_ENABLED

boolean

true

quarkus.minio.produce-metrics

If value is true (default) and the io.quarkus.quarkus-micrometer is present in the class path, then the minio client will produce metrics.

Only true for clients produced by the extension

Environment variable: QUARKUS_MINIO_PRODUCE_METRICS

boolean

true

quarkus.minio.maximum-allowed-tag

If minio clients are to produce metrics, then the uri tag will have a max of 100 values

Environment variable: QUARKUS_MINIO_MAXIMUM_ALLOWED_TAG

int

100

quarkus.minio.host

The minio server host. The host may contains the port, though it’s not recommended. If a specific port is needed, quakus.minio.port is a better fit.

Environment variable: QUARKUS_MINIO_HOST

string

required

quarkus.minio.access-key

The minio server access key

Environment variable: QUARKUS_MINIO_ACCESS_KEY

string

required

quarkus.minio.secret-key

The minio server secret key

Environment variable: QUARKUS_MINIO_SECRET_KEY

string

required

quarkus.minio.region

An optional bucket region

Environment variable: QUARKUS_MINIO_REGION

string

quarkus.minio.port

An optional port number. Specifically usefull if you want to access bucket that doesn’t use standard port (i.e. 80 for HTTP and 443 for HTTPS)

Environment variable: QUARKUS_MINIO_PORT

int

quarkus.minio.secure

An optional boolean to enable secure connection. Defaults to true

Environment variable: QUARKUS_MINIO_SECURE

boolean

true

quarkus.minio."named-minio-clients".enabled

Should the extension provide a MinioClient. If set to false, you will have to create the clients yourself, but will still benefit the native compatibility work.

Environment variable: QUARKUS_MINIO__NAMED_MINIO_CLIENTS__ENABLED

boolean

true

quarkus.minio."named-minio-clients".host

The minio server host. The host may contains the port, though it’s not recommended. If a specific port is needed, quakus.minio.port is a better fit.

Environment variable: QUARKUS_MINIO__NAMED_MINIO_CLIENTS__HOST

string

required

quarkus.minio."named-minio-clients".access-key

The minio server access key

Environment variable: QUARKUS_MINIO__NAMED_MINIO_CLIENTS__ACCESS_KEY

string

required

quarkus.minio."named-minio-clients".secret-key

The minio server secret key

Environment variable: QUARKUS_MINIO__NAMED_MINIO_CLIENTS__SECRET_KEY

string

required

quarkus.minio."named-minio-clients".region

An optional bucket region

Environment variable: QUARKUS_MINIO__NAMED_MINIO_CLIENTS__REGION

string

quarkus.minio."named-minio-clients".port

An optional port number. Specifically usefull if you want to access bucket that doesn’t use standard port (i.e. 80 for HTTP and 443 for HTTPS)

Environment variable: QUARKUS_MINIO__NAMED_MINIO_CLIENTS__PORT

int

quarkus.minio."named-minio-clients".secure

An optional boolean to enable secure connection. Defaults to true

Environment variable: QUARKUS_MINIO__NAMED_MINIO_CLIENTS__SECURE

boolean

true