Amazon S3 Client

Amazon Simple Storage Service (Amazon S3) is an object storage service for storing and retrieving any amount of data, for uses such as application storage, backup and recovery, archives and data lakes. This client lets you manage buckets and upload, download, copy, list and delete objects.

For more information, see the Amazon S3 documentation.

The extension is based on AWS Java SDK 2.x. It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async).

The Quarkus extension supports two programming models:

  • Blocking access using URL Connection HTTP client (by default), the Apache 5.x HTTP client, the Apache HTTP client (deprecated) or the AWS CRT-based HTTP client

  • Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client or the AWS CRT-based HTTP client

In this guide, we see how you can get your REST services to use Amazon S3 locally and on AWS.

Prerequisites

To complete this guide, you need:

  • JDK 21+ installed with JAVA_HOME configured appropriately

  • an IDE

  • Apache Maven 3.8.1+

  • Docker, to run Amazon S3 locally with Dev Services and to run the tests

  • Optionally, GraalVM or Mandrel installed to build a native executable

No AWS account is required: Dev Services and the local Floci container provide everything you need. You only need an AWS account and the AWS Command Line Interface if you want to deploy to AWS.

Start Floci automatically with Dev Services

The easiest way to start working with Amazon S3 is to run a local instance using Dev Services. Dev Services starts a Floci container in dev and test modes, and configures the client to use it, so you don’t need an AWS account.

The container listens on a random port, so you never hard-code an endpoint. It is labelled quarkus-dev-service-floci and shared between the Quarkus applications running in dev mode. Refer to Dev Services for Amazon Services for the provider selection, the container configuration and the init scripts.

Start Floci manually

You can also start a Floci container yourself:

docker run --rm --name floci --publish 4566:4566 -d floci/floci:latest-compat

This starts a Floci instance that is accessible on port 4566. Floci exposes all the services it emulates on this single endpoint.

The latest-compat image ships the AWS CLI, already configured to target the local endpoint. Run the provisioning commands of this guide inside the container, with docker exec floci aws …​. You do not need to install or configure the AWS CLI on your host.

You can check the region, the credentials and the endpoint used inside the container:

docker exec floci env | grep AWS_

The CLI uses the region us-east-1, the credentials test / test, and the endpoint http://localhost:4566 seen from inside the container. An application running on the host reaches Floci at http://localhost:4566; an application running in another container must use the container name, for example http://floci:4566, and the containers must share a Docker network.

Solution

The application built here allows to manage files stored in Amazon S3.

It uses the synchronous client first, then the asynchronous client in Going asynchronous.

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.

The solution is located in the amazon-s3-quickstart directory.

Walkthrough

Creating the Maven project

First, we need a new project. Create a new project with the following command:

mvn io.quarkus.platform:quarkus-maven-plugin:4.0.0.Beta2:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=amazon-s3-quickstart \
    -DclassName="org.acme.s3.S3SyncClientResource" \
    -Dpath="/s3" \
    -Dextensions="rest-jackson,amazon-s3"
cd amazon-s3-quickstart

This command generates a Maven structure importing the Quarkus REST and Amazon S3 Client extensions. After this, the amazon-s3 extension has been added to your pom.xml, along with quarkus-rest and quarkus-rest-jackson.

The Amazon S3 extensions are a component of the Quarkus platform, and the generated pom.xml already imports their BOM through it, which is the recommended setup.

Due to differing release schedules, the Quarkus platform may not include the latest Quarkus Amazon Services release. If you need features from a newer release, replace the generated quarkus-amazon-services-bom import with the Quarkus Amazon Services BOM:

<dependency>
    <groupId>io.quarkiverse.amazonservices</groupId>
    <artifactId>quarkus-amazon-services-bom</artifactId>
    <version>4.0.0.Beta5</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

The command also generates a S3SyncClientResourceTest class and a S3SyncClientResourceIT class that call the hello endpoint of the generated resource. The next section replaces that resource: delete these two files, or update them to match the endpoints you create.

Setting up the model

Because the primary goal of our application is to upload a file into the S3 bucket, we need to setup the model we will be using to define the multipart/form-data payload, in the form of a POJO annotated with @RestForm.

The default setting for quarkus.http.limits.max-body-size is 10240K. This may limit your ability to upload multipart files larger than the default. If you want to upload larger files, you will need to set this limit explicitly.

Create a org.acme.s3.FormData class as follows:

package org.acme.s3;

import java.io.File;
import jakarta.ws.rs.core.MediaType;
import org.jboss.resteasy.reactive.PartType;
import org.jboss.resteasy.reactive.RestForm;

public class FormData {

    @RestForm("file")
    public File data;

    @RestForm
    @PartType(MediaType.TEXT_PLAIN)
    public String filename;

    @RestForm
    @PartType(MediaType.TEXT_PLAIN)
    public String mimetype;

}

The class defines three fields:

  • data that captures the stream of uploaded bytes from the client

  • filename that captures the filename provided by the submitted form

  • mimetype the content type of the uploaded file

In the second step let’s create a bean that will represent a file in a Amazon S3 bucket as follows:

package org.acme.s3;

import software.amazon.awssdk.services.s3.model.S3Object;

public class FileObject {
    private String objectKey;

    private Long size;

    public FileObject() {
    }

    public static FileObject from(S3Object s3Object) {
        FileObject file = new FileObject();
        if (s3Object != null) {
            file.setObjectKey(s3Object.key());
            file.setSize(s3Object.size());
        }
        return file;
    }

    public String getObjectKey() {
        return objectKey;
    }

    public Long getSize() {
        return size;
    }

    public FileObject setObjectKey(String objectKey) {
        this.objectKey = objectKey;
        return this;
    }

    public FileObject setSize(Long size) {
        this.size = size;
        return this;
    }
}

Nothing fancy. One important thing to note is that having a default constructor is required by the JSON serialization layer. The static from method creates a bean based on the S3Object object provided by the S3 client response when listing all the objects in a bucket.

Creating the REST resource

Now create a org.acme.s3.CommonResource that will consist of methods to prepare S3 request to get object from a S3 bucket, or to put file into a S3 bucket. Note a configuration property bucket.name is defined here as the request method required name of the S3 bucket.

package org.acme.s3;

import org.eclipse.microprofile.config.inject.ConfigProperty;

import software.amazon.awssdk.services.s3.model.GetObjectRequest;
import software.amazon.awssdk.services.s3.model.PutObjectRequest;

abstract public class CommonResource {

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

    protected PutObjectRequest buildPutRequest(FormData formData) {
        return PutObjectRequest.builder()
                .bucket(bucketName)
                .key(formData.filename)
                .contentType(formData.mimetype)
                .build();
    }

    protected GetObjectRequest buildGetRequest(String objectKey) {
        return GetObjectRequest.builder()
                .bucket(bucketName)
                .key(objectKey)
                .build();
    }

}

Then, create a org.acme.s3.S3SyncClientResource that will provides an API to upload/download files as well as to list all the files in a bucket.

package org.acme.s3;

import java.util.Comparator;
import java.util.List;
import java.util.stream.Collectors;

import jakarta.inject.Inject;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.core.Response.ResponseBuilder;
import jakarta.ws.rs.core.Response.Status;
import software.amazon.awssdk.core.ResponseBytes;
import software.amazon.awssdk.core.sync.RequestBody;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.GetObjectResponse;
import software.amazon.awssdk.services.s3.model.ListObjectsRequest;
import software.amazon.awssdk.services.s3.model.PutObjectResponse;

@Path("/s3")
public class S3SyncClientResource extends CommonResource {
    @Inject
    S3Client s3;

    @POST
    @Path("upload")
    @Consumes(MediaType.MULTIPART_FORM_DATA)
    public Response uploadFile(FormData formData) throws Exception {

        if (formData.filename == null || formData.filename.isEmpty()) {
            return Response.status(Status.BAD_REQUEST).build();
        }

        if (formData.mimetype == null || formData.mimetype.isEmpty()) {
            return Response.status(Status.BAD_REQUEST).build();
        }

        PutObjectResponse putResponse = s3.putObject(buildPutRequest(formData),
                RequestBody.fromFile(formData.data));
        if (putResponse != null) {
            return Response.ok().status(Status.CREATED).build();
        } else {
            return Response.serverError().build();
        }
    }

    @GET
    @Path("download/{objectKey}")
    @Produces(MediaType.APPLICATION_OCTET_STREAM)
    public Response downloadFile(String objectKey) {
        ResponseBytes<GetObjectResponse> objectBytes = s3.getObjectAsBytes(buildGetRequest(objectKey));
        ResponseBuilder response = Response.ok(objectBytes.asByteArray());
        response.header("Content-Disposition", "attachment;filename=" + objectKey);
        response.header("Content-Type", objectBytes.response().contentType());
        return response.build();
    }

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public List<FileObject> listFiles() {
        ListObjectsRequest listRequest = ListObjectsRequest.builder().bucket(bucketName).build();

        //HEAD S3 objects to get metadata
        return s3.listObjects(listRequest).contents().stream()
                .map(FileObject::from)
                .sorted(Comparator.comparing(FileObject::getObjectKey))
                .collect(Collectors.toList());
    }
}

Configuring Amazon S3 clients

Both Amazon S3 clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory. Additionally, you need to add to the classpath a proper implementation of the sync client. By default, the extension uses the URL connection HTTP client, so you need to add a URL connection client dependency to the pom.xml file:

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>url-connection-client</artifactId>
</dependency>

If you want to use the Apache 5.x HTTP client instead, configure it as follows:

quarkus.s3.sync-client.type=apache5

And add the following dependency to the application pom.xml:

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>apache5-client</artifactId>
</dependency>

If you want to use the Apache HTTP client instead, configure it as follows:

quarkus.s3.sync-client.type=apache

And add the following dependency to the application pom.xml:

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>apache-client</artifactId>
</dependency>

The AWS SDK has deprecated the Apache HTTP client in favor of the Apache 5.x HTTP client, which is a drop-in replacement: prefer apache5. The build logs a warning when the Apache HTTP client is used. Set quarkus.aws.sync-client.apache-deprecation-warning=false to disable it, see Deprecated Apache HTTP client.

If you want to use the AWS CRT-based HTTP client instead, configure it as follows:

quarkus.s3.sync-client.type=aws-crt

And add the following dependency to the application pom.xml:

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>aws-crt-client</artifactId>
</dependency>

Use Dev Services

With Dev Services, there is nothing to configure: in dev and test modes, Dev Services starts Floci and configures the endpoint, the region and the credentials of the clients.

Use a manually started Floci

If you started Floci yourself, configure the client to use it as follows:

quarkus.s3.endpoint-override=http://localhost:4566 (1)

quarkus.s3.aws.region=us-east-1 (2)
quarkus.s3.aws.credentials.type=static (3)
quarkus.s3.aws.credentials.static-provider.access-key-id=test-key
quarkus.s3.aws.credentials.static-provider.secret-access-key=test-secret
1 Override the Amazon S3 client to use Floci instead of the actual AWS service. When it is set, Dev Services does not start a local stack for Amazon S3.
2 Floci defaults to us-east-1
3 The static credentials provider lets you set the access-key-id and secret-access-key directly

Use your AWS account

If you want to work with an AWS account, you need an AWS account with access to Amazon S3 and the AWS Command Line Interface, then remove or comment out the endpoint-override and the static credentials properties of the previous section. By default, the Amazon S3 client uses the default credentials provider chain that looks for credentials in this order:

  • Java System Properties - aws.accessKeyId and aws.secretAccessKey

  • Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY

  • Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI

  • Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,

  • Instance profile credentials delivered through the Amazon EC2 metadata service

And the region from your AWS CLI profile will be used.

Without endpoint-override, Dev Services starts a local stack for Amazon S3 in dev and test modes, and the client uses it instead of your AWS account. Removing the endpoint-override is therefore not enough to use your AWS account in these modes: also disable Dev Services for Amazon S3:

quarkus.s3.devservices.enabled=false

Dev Services never starts in production mode.

Create the S3 bucket

Set the name of the S3 bucket used by the application:

bucket.name=quarkus.s3.quickstart

Floci works with the default addressing style of the S3 client, so a manual local instance needs no extra property. If your local stack does not support the virtual-hosted-style addressing of the S3 client, enable path-style access:

quarkus.s3.path-style-access=true
With Dev Services

Let Dev Services create the bucket on startup:

quarkus.s3.devservices.buckets=${bucket.name}
On a manually started Floci

Create the bucket using the AWS CLI of the Floci container:

docker exec floci aws s3 mb s3://quarkus.s3.quickstart
On your AWS account

Create the bucket with your own AWS CLI:

aws s3 mb s3://quarkus.s3.quickstart

Creating a frontend

Now let’s add a simple web page to interact with our S3SyncClientResource. Quarkus automatically serves static resources located under the META-INF/resources directory. In the src/main/resources/META-INF/resources directory, add a s3.html file with the content from this s3.html file in it.

Run the application in Dev Mode

Run the application in dev mode with:

./mvnw clean quarkus:dev

If you use Dev Services, it starts a Floci container and configures the Amazon S3 clients to use it. The Dev Services card of the Dev UI, at http://localhost:8080/q/dev-ui, shows the container and the endpoint it exposes.

  • Open a browser to http://localhost:8080/s3.html to use the synchronous client

  • Upload new files to the current S3 bucket via the form and see the list of files in the bucket

Next steps

Packaging

Packaging your application is as simple as ./mvnw clean package. It can then be run with java -jar target/quarkus-app/quarkus-run.jar.

With GraalVM or Mandrel installed, you can also create a native executable binary:

./mvnw clean package -Dnative

Without GraalVM or Mandrel, build the native executable inside a container:

./mvnw clean package -Dnative -Dquarkus.native.container-build=true

Depending on your system, that will take some time. Run the native executable with ./target/amazon-s3-quickstart-1.0.0-SNAPSHOT-runner.

Dev Services does not start in production mode, so you need to make sure that your application.properties file is configured to use your AWS account or a local stack. To use a local Floci instance, pass the endpoint and the credentials on the command line: 
java \
    -Dquarkus.s3.endpoint-override=http://localhost:4566 \
    -Dquarkus.s3.aws.region=us-east-1 \
    -Dquarkus.s3.aws.credentials.type=static \
    -Dquarkus.s3.aws.credentials.static-provider.access-key-id=test-key \
    -Dquarkus.s3.aws.credentials.static-provider.secret-access-key=test-secret \
    -jar target/quarkus-app/quarkus-run.jar

See the Packaging applications guide for more details.

Going asynchronous

Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.

Create a org.acme.s3.S3AsyncClientResource that will be similar to our S3SyncClientResource but using an asynchronous programming model.

package org.acme.s3;

import java.nio.ByteBuffer;
import java.util.Comparator;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

import jakarta.inject.Inject;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.core.Response.Status;
import mutiny.zero.flow.adapters.AdaptersToFlow;

import org.jboss.resteasy.reactive.RestMulti;
import org.reactivestreams.Publisher;

import io.smallrye.mutiny.Multi;
import io.smallrye.mutiny.Uni;
import io.vertx.core.buffer.Buffer;
import software.amazon.awssdk.core.async.AsyncRequestBody;
import software.amazon.awssdk.core.async.AsyncResponseTransformer;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import software.amazon.awssdk.services.s3.model.ListObjectsRequest;
import software.amazon.awssdk.services.s3.model.ListObjectsResponse;

@Path("/async-s3")
public class S3AsyncClientResource extends CommonResource {
    @Inject
    S3AsyncClient s3;

    @POST
    @Path("upload")
    @Consumes(MediaType.MULTIPART_FORM_DATA)
    public Uni<Response> uploadFile(FormData formData) throws Exception {

        if (formData.filename == null || formData.filename.isEmpty()) {
            return Uni.createFrom().item(Response.status(Status.BAD_REQUEST).build());
        }

        if (formData.mimetype == null || formData.mimetype.isEmpty()) {
            return Uni.createFrom().item(Response.status(Status.BAD_REQUEST).build());
        }

        return Uni.createFrom()
                .completionStage(() -> {
                    return s3.putObject(buildPutRequest(formData), AsyncRequestBody.fromFile(formData.data));
                })
                .onItem().ignore().andSwitchTo(Uni.createFrom().item(Response.created(null).build()))
                .onFailure().recoverWithItem(th -> {
                    th.printStackTrace();
                    return Response.serverError().build();
                });
    }

    @GET
    @Path("download/{objectKey}")
    @Produces(MediaType.APPLICATION_OCTET_STREAM)
    public RestMulti<Buffer> downloadFile(String objectKey) {

        return RestMulti.fromUniResponse(Uni.createFrom()
                .completionStage(() -> s3.getObject(buildGetRequest(objectKey),
                        AsyncResponseTransformer.toPublisher())),
                response -> Multi.createFrom().safePublisher(AdaptersToFlow.publisher((Publisher<ByteBuffer>) response))
                        .map(S3AsyncClientResource::toBuffer),
                response -> Map.of("Content-Disposition", List.of("attachment;filename=" + objectKey), "Content-Type",
                        List.of(response.response().contentType())));
    }

    @GET
    public Uni<List<FileObject>> listFiles() {
        ListObjectsRequest listRequest = ListObjectsRequest.builder()
                .bucket(bucketName)
                .build();

        return Uni.createFrom().completionStage(() -> s3.listObjects(listRequest))
                .onItem().transform(result -> toFileItems(result));
    }

    private static Buffer toBuffer(ByteBuffer bytebuffer) {
        byte[] result = new byte[bytebuffer.remaining()];
        bytebuffer.get(result);
        return Buffer.buffer(result);
    }

    private List<FileObject> toFileItems(ListObjectsResponse objects) {
        return objects.contents().stream()
                .map(FileObject::from)
                .sorted(Comparator.comparing(FileObject::getObjectKey))
                .collect(Collectors.toList());
    }
}

If you want to use the AWS CRT-based S3 client, add the io.quarkiverse.amazon.s3.runtime.S3Crt qualifier as follows:

@Inject
@S3Crt
S3AsyncClient s3;

For a named native CRT client, combine @S3Crt with @AmazonClient:

@Inject
@S3Crt
@AmazonClient("archive")
S3AsyncClient archive;

Use quarkus.s3."archive".* for its S3 settings, AWS region, credentials and endpoint, and quarkus.s3."archive".crt-client.* for native CRT settings. Unset settings fall back to the corresponding quarkus.s3.* settings. The native S3 CRT client is different from a standard S3 asynchronous client using the CRT HTTP transport; the latter does not use @S3Crt or crt-client.* settings.

And add the following dependency to the application pom.xml:

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>aws-crt-client</artifactId>
</dependency>

To enable the asynchronous client, you also need to add the Netty HTTP client dependency to the pom.xml:

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>netty-nio-client</artifactId>
</dependency>

If you want to use the AWS CRT-based HTTP client instead, configure it as follows:

quarkus.s3.async-client.type=aws-crt

And add the following dependency to the application pom.xml:

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>aws-crt-client</artifactId>
</dependency>

Quarkus dev mode picks up the new resource, and restarts by itself when pom.xml changes: if the application is still running, wait a few seconds, then call it again. Otherwise, run it again with ./mvnw quarkus:dev.

Going further

You have built a Quarkus application that uses Amazon S3, developed locally against Dev Services and ready to run on your AWS account. You are all set to build great applications with Amazon S3, with the fast startup, the low memory footprint and the developer joy of Quarkus.

To go further:

Load configuration from S3 objects

Load application properties from objects in S3. See Configuration from AWS to compare providers, read properties in your application and configure AWS access.

For example, upload this UTF-8 document as config/application.json:

{"host":"database.example.com","port":5432}

Then configure a named entry in your local application.properties:

quarkus.s3.config.enabled=true
quarkus.s3.config.entries.database.bucket=my-config-bucket
quarkus.s3.config.entries.database.key=config/application.json
quarkus.s3.config.entries.database.prefix=myapp.database

# Explicit format overrides Content-Type and the key's extension
quarkus.s3.config.entries.database.format=json

# S3-specific defaults; polling is opt-in
quarkus.s3.config.max-object-size=1M
quarkus.s3.config.update-interval=PT0S

The document exposes myapp.database.host and myapp.database.port. Without a prefix it exposes host and port. Configure more entries under quarkus.s3.config.entries.<name> to combine objects, including objects in different buckets reachable with the same AWS credentials and region. Enter keys and version IDs exactly as stored: do not URL-encode spaces, +, %, ? or #, and do not add a leading slash unless it belongs to the key.

Formats and size limits

For auto (the per-entry default), a recognized Content-Type takes precedence over the key’s extension:

  • JSON: application/json, text/json or a media type ending in +json.

  • YAML: application/yaml, application/x-yaml, text/yaml, text/x-yaml or a media type ending in +yaml.

  • Properties: text/x-java-properties, text/java-properties or application/x-java-properties.

  • Otherwise, .json, .properties, .yaml or .yml selects the format (case-insensitive).

Media type parameters such as charset=utf-8 are ignored; the body must always be valid UTF-8. text/plain and application/octet-stream are ambiguous and fall back to the extension. Unrecognized formats fail rather than guessing from the body. If an upload tool sets an incorrect recognized Content-Type, use an explicit entry format. Set quarkus.s3.config.format to choose a default format for all entries; an entry can override it, including with format=auto to detect its format independently. For explicit formats, YAML dependencies and prefix requirements, see the shared format rules. A zero-byte object contributes no properties, removing its previous contribution after a successful refresh. Compressed files and arbitrary binary objects are not supported.

Objects larger than 1 MiB are rejected by default. To allow objects up to 2 MiB, set quarkus.s3.config.max-object-size=2M. Choose a positive limit below 2 GiB. This limits each downloaded object, not the application’s total memory usage; use a small number of configuration documents rather than large data files.

Current objects, pinned versions and polling

An entry without version-id reads the current object; bucket versioning is not required for this mode. To pin an immutable version:

quarkus.s3.config.entries.database.version-id=your-object-version-id

You can also supply the pin directly through an environment variable:

export QUARKUS_S3_CONFIG_ENTRIES__DATABASE__VERSION_ID=your-object-version-id

Use a real version ID from a versioned bucket. The literal null version ID is rejected because S3 can overwrite that version in an unversioned or versioning-suspended bucket; it is not an immutable pin. Omit version-id to follow such objects.

After a pinned version loads successfully, the application keeps those values even if a newer version is uploaded. Polling only follows current objects, not successfully loaded pins. To use a different pinned version, change version-id and restart the application.

Polling is disabled by default. Set quarkus.s3.config.update-interval=30S to enable it (minimum one second). Unchanged objects are not downloaded again, but update checks still make AWS requests and may incur charges. Use one document or coordinated version pins when a release must be consistent across files. See startup and refresh behavior and dynamic reads for publication and update behavior.

Client settings and permissions

Configure AWS access with the default quarkus.s3 settings. Set a socket timeout to stop a stalled object download:

quarkus.s3.aws.region=eu-west-1
quarkus.s3.api-call-timeout=10S
quarkus.s3.api-call-attempt-timeout=3S
# Fail a body read that stalls for more than 3 seconds
quarkus.s3.sync-client.socket-timeout=3S
# For a local S3-compatible endpoint, also configure endpoint-override and path-style-access

Grant s3:GetObject for current reads and s3:GetObjectVersion for pinned versions, scoped to the selected objects, plus the appropriate KMS permissions for SSE-KMS. No ListBucket permission is required to fetch explicit objects, but without it S3 can return 403 rather than 404 for a missing key; diagnostics cannot reliably distinguish those cases. SSE-S3/SSE-KMS decryption is handled by S3; customer-provided SSE-C keys and automatic archive restoration are not supported.

S3 Transfer Manager

The S3 Transfer Manager is a high-level utility of the AWS SDK on top of the asynchronous S3 client. Use it to transfer large objects or many files: it splits large uploads and downloads into parts sent in parallel, transfers whole directories, reports progress, and can pause and resume an upload.

The extension exposes S3TransferManager as a CDI bean. Add the following dependency to the application pom.xml:

<dependency>
    <groupId>io.quarkiverse.amazonservices</groupId>
    <artifactId>quarkus-amazon-s3-transfer-manager</artifactId>
</dependency>

The Transfer Manager uses the corresponding asynchronous S3 client, so configure it as described in Going asynchronous. Use @AmazonClient("archive") to select a named client, with or without @S3Crt:

@Inject
@AmazonClient("archive")
S3TransferManager archiveTransfers;

@Inject
@S3Crt
@AmazonClient("archive")
S3TransferManager archiveCrtTransfers;

Injecting a named Transfer Manager is sufficient to create its underlying client; injecting that client separately is not required. The native CRT client uses quarkus.s3."archive".crt-client.*, falling back to quarkus.s3.crt-client.* for absent settings.

The parallel transfers require an asynchronous S3 client with multipart support. The recommended one is the AWS CRT-based S3 client: add the aws-crt-client dependency, as described in Going asynchronous, and inject the Transfer Manager with the @S3Crt qualifier:

@Inject
@S3Crt
S3TransferManager transferManager;

Without the qualifier, the Transfer Manager uses the asynchronous client based on the Netty HTTP client or the AWS CRT-based HTTP client. That client has no multipart support by default, so the Transfer Manager logs a warning and transfers each object in a single request. To enable it, configure multipart support on the underlying client; no custom producer is needed:

quarkus.s3.multipart.enabled=true
# Optional: sizes accept byte counts or binary unit suffixes such as M
quarkus.s3.multipart.threshold-in-bytes=100000000
quarkus.s3.multipart.minimum-part-size-in-bytes=8M

These settings apply to standard S3 asynchronous clients with either HTTP transport. Named clients inherit them unless overridden with quarkus.s3."client-name".multipart.*. They also affect direct calls to those clients, not just Transfer Manager operations. They do not apply to synchronous clients or the dedicated @S3Crt client, which uses crt-client.* settings. The Transfer Manager reuses the configured client without overriding its multipart settings. For other settings not exposed as configuration properties, you can still override the client configuration with a producer.

Then upload a file:

CompletedFileUpload upload = transferManager.uploadFile(b -> b
        .putObjectRequest(r -> r.bucket(bucketName).key("report.pdf"))
        .source(Paths.get("target/report.pdf")))
        .completionFuture()
        .join();

downloadFile, uploadDirectory, downloadDirectory and copy work the same way.

Configuration Reference

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

Configuration property

Type

Default

quarkus.s3.interceptors

List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.

The list should consists of class names which implements software.amazon.awssdk.core.interceptor.ExecutionInterceptor interface. Classes will be attempted to be loaded via CDI first, and if no CDI beans are available, then the constructor with no parameters will be invoked to instantiate each class.

Environment variable: QUARKUS_S3_INTERCEPTORS

list of string

quarkus.s3.telemetry.enabled

OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true.

Environment variable: QUARKUS_S3_TELEMETRY_ENABLED

boolean

true when quarkus-opentelemetry is present, false otherwise

quarkus.s3.sync-client.type

Type of the sync HTTP client implementation

Environment variable: QUARKUS_S3_SYNC_CLIENT_TYPE

url, apache, apache5, aws-crt

url

quarkus.s3.async-client.type

Type of the async HTTP client implementation

Environment variable: QUARKUS_S3_ASYNC_CLIENT_TYPE

netty, aws-crt

netty

quarkus.s3.devservices.enabled

If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. The local AWS stack is provided by the stack provider configured with provider.

Environment variable: QUARKUS_S3_DEVSERVICES_ENABLED

boolean

quarkus.s3.devservices.container-properties."container-properties"

Generic properties that are pass for additional container configuration.

Environment variable: QUARKUS_S3_DEVSERVICES_CONTAINER_PROPERTIES__CONTAINER_PROPERTIES_

Map<String,String>

quarkus.s3.devservices.provider

The dev services stack provider to use for this service. If not specified, the global setting from quarkus.aws.devservices.provider is used. Supported values: "floci", "localstack", "ministack", "moto"

This allows per-service override of the global stack selection.

Environment variable: QUARKUS_S3_DEVSERVICES_PROVIDER

floci, localstack, ministack, moto

quarkus.s3.devservices.buckets

The buckets to create on startup.

Environment variable: QUARKUS_S3_DEVSERVICES_BUCKETS

list of string

default

quarkus.s3.config.enabled

Enable loading configuration from explicitly selected S3 objects. No bucket listing is performed.

Environment variable: QUARKUS_S3_CONFIG_ENABLED

boolean

false

quarkus.s3.config.fail-on-missing-config

Fail startup unless every selected object can be fetched and decoded into a complete, collision-free snapshot.

Environment variable: QUARKUS_S3_CONFIG_FAIL_ON_MISSING_CONFIG

boolean

true

quarkus.s3.config.ordinal

Config source ordinal; defaults between application.properties and .env.

Environment variable: QUARKUS_S3_CONFIG_ORDINAL

int

270

quarkus.s3.config.format

Default document format for entries. Auto uses a recognized Content-Type, then the object key’s extension.

Environment variable: QUARKUS_S3_CONFIG_FORMAT

auto, raw, json, properties, yaml

auto

quarkus.s3.config.update-interval

Polling interval for unpinned objects. Zero disables polling; positive values must be at least one second.

Environment variable: QUARKUS_S3_CONFIG_UPDATE_INTERVAL

Duration 

PT0S

quarkus.s3.config.max-object-size

Maximum bytes per object, enforced while reading. Must be positive and less than 2 GiB.

Environment variable: QUARKUS_S3_CONFIG_MAX_OBJECT_SIZE

MemorySize 

1M

quarkus.s3.accelerate-mode

quarkus.s3."client-name".accelerate-mode

Enable using the accelerate endpoint when accessing S3.

Accelerate endpoints allow faster transfer of objects by using Amazon CloudFront’s globally distributed edge locations.

Environment variable: QUARKUS_S3_ACCELERATE_MODE

boolean

false

quarkus.s3.checksum-validation

quarkus.s3."client-name".checksum-validation

Enable doing a validation of the checksum of an object stored in S3.

Environment variable: QUARKUS_S3_CHECKSUM_VALIDATION

boolean

true

quarkus.s3.chunked-encoding

quarkus.s3."client-name".chunked-encoding

Enable using chunked encoding when signing the request payload for software.amazon.awssdk.services.s3.model.PutObjectRequest and software.amazon.awssdk.services.s3.model.UploadPartRequest.

Environment variable: QUARKUS_S3_CHUNKED_ENCODING

boolean

true

quarkus.s3.dualstack

quarkus.s3."client-name".dualstack

Enable dualstack mode for accessing S3. If you want to use IPv6 when accessing S3, dualstack must be enabled.

Environment variable: QUARKUS_S3_DUALSTACK

boolean

false

quarkus.s3.path-style-access

quarkus.s3."client-name".path-style-access

Enable using path style access for accessing S3 objects instead of DNS style access. DNS style access is preferred as it will result in better load balancing when accessing S3.

Environment variable: QUARKUS_S3_PATH_STYLE_ACCESS

boolean

false

quarkus.s3.use-arn-region-enabled

quarkus.s3."client-name".use-arn-region-enabled

Enable cross-region call to the region specified in the S3 resource ARN different than the region the client was configured with. If this flag is not set to 'true', the cross-region call will throw an exception.

Environment variable: QUARKUS_S3_USE_ARN_REGION_ENABLED

boolean

false

quarkus.s3.profile-name

quarkus.s3."client-name".profile-name

Define the profile name that should be consulted to determine the default value of use-arn-region-enabled. This is not used, if the use-arn-region-enabled is configured to 'true'.

If not specified, the value in AWS_PROFILE environment variable or aws.profile system property is used and defaults to default name.

Environment variable: QUARKUS_S3_PROFILE_NAME

string

quarkus.s3.config.entries."entries".bucket

Bucket name or access point identifier accepted by the S3 SDK.

Environment variable: QUARKUS_S3_CONFIG_ENTRIES__ENTRIES__BUCKET

string

required

quarkus.s3.config.entries."entries".key

Exact object key, without URL encoding or a leading slash unless it is part of the key.

Environment variable: QUARKUS_S3_CONFIG_ENTRIES__ENTRIES__KEY

string

required

quarkus.s3.config.entries."entries".version-id

Optional immutable version to read. The mutable S3 null version is rejected. Successfully loaded pins are not polled.

Environment variable: QUARKUS_S3_CONFIG_ENTRIES__ENTRIES__VERSION_ID

string

quarkus.s3.config.entries."entries".prefix

Optional property prefix, joined to decoded document keys with a dot. Required for raw or scalar values.

Environment variable: QUARKUS_S3_CONFIG_ENTRIES__ENTRIES__PREFIX

string

quarkus.s3.config.entries."entries".format

Format override; defaults to the source-wide format. Auto uses a recognized Content-Type, then the object’s extension; unknown formats fail. YAML requires quarkus-config-yaml.

Environment variable: QUARKUS_S3_CONFIG_ENTRIES__ENTRIES__FORMAT

auto, raw, json, properties, yaml

AWS SDK client configurations

Type

Default

quarkus.s3.endpoint-override

quarkus.s3."client-name".endpoint-override

The endpoint URI with which the SDK should communicate.

If not specified, an appropriate endpoint to be used for the given service and region.

Environment variable: QUARKUS_S3_ENDPOINT_OVERRIDE

URI

quarkus.s3.api-call-timeout

quarkus.s3."client-name".api-call-timeout

The amount of time to allow the client to complete the execution of an API call.

This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc.

This value should always be positive, if present.

Environment variable: QUARKUS_S3_API_CALL_TIMEOUT

Duration 

quarkus.s3.api-call-attempt-timeout

quarkus.s3."client-name".api-call-attempt-timeout

The amount of time to wait for the HTTP request to complete before giving up and timing out.

This value should always be positive, if present.

Environment variable: QUARKUS_S3_API_CALL_ATTEMPT_TIMEOUT

Duration 

quarkus.s3.advanced.use-quarkus-scheduled-executor-service

quarkus.s3."client-name".advanced.use-quarkus-scheduled-executor-service

Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task.

When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools.

Environment variable: QUARKUS_S3_ADVANCED_USE_QUARKUS_SCHEDULED_EXECUTOR_SERVICE

boolean

true

AWS services configurations

Type

Default

quarkus.s3.aws.region

quarkus.s3."client-name".aws.region

An Amazon Web Services region that hosts the given service.

It overrides region provider chain with static value of region with which the service client should communicate.

If not set, region is retrieved via the default providers chain in the following order:

  • aws.region system property

  • region property from the profile file

  • Instance profile file

See software.amazon.awssdk.regions.Region for available regions.

Environment variable: QUARKUS_S3_AWS_REGION

Region

quarkus.s3.aws.credentials.type

quarkus.s3."client-name".aws.credentials.type

Configure the credentials provider that should be used to authenticate with AWS.

Available values:

  • default - the provider will attempt to identify the credentials automatically using the following checks:

    • Java System Properties - aws.accessKeyId and aws.secretAccessKey

    • Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY

    • Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI

    • Credentials delivered through the Amazon EC2 container service if AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and security manager has permission to access the variable.

    • Instance profile credentials delivered through the Amazon EC2 metadata service

  • static - the provider that uses the access key and secret access key specified in the static-provider section of the config.

  • system-property - it loads credentials from the aws.accessKeyId, aws.secretAccessKey and aws.sessionToken system properties.

  • env-variable - it loads credentials from the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN environment variables.

  • profile - credentials are based on AWS configuration profiles. This loads credentials from a profile file, allowing you to share multiple sets of AWS security credentials between different tools like the AWS SDK for Java and the AWS CLI.

  • container - It loads credentials from a local metadata service. Containers currently supported by the AWS SDK are Amazon Elastic Container Service (ECS) and AWS Greengrass

  • instance-profile - It loads credentials from the Amazon EC2 Instance Metadata Service.

  • process - Credentials are loaded from an external process. This is used to support the credential_process setting in the profile credentials file. See Sourcing Credentials From External Processes for more information.

  • custom - Credentials are loaded from a registered bean of type AwsCredentialsProvider matching the specified name.

  • anonymous - It always returns anonymous AWS credentials. Anonymous AWS credentials result in un-authenticated requests and will fail unless the resource or API’s policy has been configured to specifically allow anonymous access.

Environment variable: QUARKUS_S3_AWS_CREDENTIALS_TYPE

default, static, system-property, env-variable, profile, container, instance-profile, process, custom, anonymous

default

Default credentials provider configuration

Type

Default

quarkus.s3.aws.credentials.default-provider.async-credential-update-enabled

quarkus.s3."client-name".aws.credentials.default-provider.async-credential-update-enabled

Whether this provider should fetch credentials asynchronously in the background.

If this is true, threads are less likely to block, but additional resources are used to maintain the provider.

Environment variable: QUARKUS_S3_AWS_CREDENTIALS_DEFAULT_PROVIDER_ASYNC_CREDENTIAL_UPDATE_ENABLED

boolean

false

quarkus.s3.aws.credentials.default-provider.reuse-last-provider-enabled

quarkus.s3."client-name".aws.credentials.default-provider.reuse-last-provider-enabled

Whether the provider should reuse the last successful credentials provider in the chain.

Reusing the last successful credentials provider will typically return credentials faster than searching through the chain.

Environment variable: QUARKUS_S3_AWS_CREDENTIALS_DEFAULT_PROVIDER_REUSE_LAST_PROVIDER_ENABLED

boolean

true

Static credentials provider configuration

Type

Default

quarkus.s3.aws.credentials.static-provider.access-key-id

quarkus.s3."client-name".aws.credentials.static-provider.access-key-id

AWS Access key id

Environment variable: QUARKUS_S3_AWS_CREDENTIALS_STATIC_PROVIDER_ACCESS_KEY_ID

string

quarkus.s3.aws.credentials.static-provider.secret-access-key

quarkus.s3."client-name".aws.credentials.static-provider.secret-access-key

AWS Secret access key

Environment variable: QUARKUS_S3_AWS_CREDENTIALS_STATIC_PROVIDER_SECRET_ACCESS_KEY

string

quarkus.s3.aws.credentials.static-provider.session-token

quarkus.s3."client-name".aws.credentials.static-provider.session-token

AWS Session token

Environment variable: QUARKUS_S3_AWS_CREDENTIALS_STATIC_PROVIDER_SESSION_TOKEN

string

AWS Profile credentials provider configuration

Type

Default

quarkus.s3.aws.credentials.profile-provider.profile-name

quarkus.s3."client-name".aws.credentials.profile-provider.profile-name

The name of the profile that should be used by this credentials provider.

If not specified, the value in AWS_PROFILE environment variable or aws.profile system property is used and defaults to default name.

Environment variable: QUARKUS_S3_AWS_CREDENTIALS_PROFILE_PROVIDER_PROFILE_NAME

string

Process credentials provider configuration

Type

Default

quarkus.s3.aws.credentials.process-provider.async-credential-update-enabled

quarkus.s3."client-name".aws.credentials.process-provider.async-credential-update-enabled

Whether the provider should fetch credentials asynchronously in the background.

If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider.

Environment variable: QUARKUS_S3_AWS_CREDENTIALS_PROCESS_PROVIDER_ASYNC_CREDENTIAL_UPDATE_ENABLED

boolean

false

quarkus.s3.aws.credentials.process-provider.credential-refresh-threshold

quarkus.s3."client-name".aws.credentials.process-provider.credential-refresh-threshold

The amount of time between when the credentials expire and when the credentials should start to be refreshed.

This allows the credentials to be refreshed *before* they are reported to expire.

Environment variable: QUARKUS_S3_AWS_CREDENTIALS_PROCESS_PROVIDER_CREDENTIAL_REFRESH_THRESHOLD

Duration 

15S

quarkus.s3.aws.credentials.process-provider.process-output-limit

quarkus.s3."client-name".aws.credentials.process-provider.process-output-limit

The maximum size of the output that can be returned by the external process before an exception is raised.

Environment variable: QUARKUS_S3_AWS_CREDENTIALS_PROCESS_PROVIDER_PROCESS_OUTPUT_LIMIT

MemorySize 

1M

quarkus.s3.aws.credentials.process-provider.command

quarkus.s3."client-name".aws.credentials.process-provider.command

The command that should be executed to retrieve credentials. Command and parameters are seperated list entries.

Environment variable: QUARKUS_S3_AWS_CREDENTIALS_PROCESS_PROVIDER_COMMAND

list of string

Custom credentials provider configuration

Type

Default

quarkus.s3.aws.credentials.custom-provider.name

quarkus.s3."client-name".aws.credentials.custom-provider.name

The name of custom AwsCredentialsProvider bean.

Environment variable: QUARKUS_S3_AWS_CREDENTIALS_CUSTOM_PROVIDER_NAME

string

Multipart transfer configuration for the standard S3 asynchronous client

Type

Default

quarkus.s3.multipart.enabled

quarkus.s3."client-name".multipart.enabled

Enable automatic multipart transfers for the standard S3 asynchronous client, with either Netty or the AWS CRT HTTP transport. Includes direct calls and transfers through the Transfer Manager. Named clients inherit absent settings from the default client. Does not apply to the synchronous client or the dedicated @S3Crt client.

Environment variable: QUARKUS_S3_MULTIPART_ENABLED

boolean

false

quarkus.s3.multipart.threshold-in-bytes

quarkus.s3."client-name".multipart.threshold-in-bytes

Size above which a transfer uses multipart when enabled. Must be greater than zero. If not set, the AWS SDK default is used.

Environment variable: QUARKUS_S3_MULTIPART_THRESHOLD_IN_BYTES

MemorySize 

Same as minimum-part-size-in-bytes

quarkus.s3.multipart.minimum-part-size-in-bytes

quarkus.s3."client-name".multipart.minimum-part-size-in-bytes

Minimum part size for multipart transfers when enabled. Must be greater than zero. If not set, the AWS SDK default is used.

Environment variable: QUARKUS_S3_MULTIPART_MINIMUM_PART_SIZE_IN_BYTES

MemorySize 

8M

AWS CRT-based S3 client configuration

Type

Default

quarkus.s3.crt-client.initial-read-buffer-size-in-bytes

quarkus.s3."client-name".crt-client.initial-read-buffer-size-in-bytes

Configure the starting buffer size the client will use to buffer the parts downloaded from S3.

Environment variable: QUARKUS_S3_CRT_CLIENT_INITIAL_READ_BUFFER_SIZE_IN_BYTES

long

Equal to the resolved part size * 10

quarkus.s3.crt-client.max-concurrency

quarkus.s3."client-name".crt-client.max-concurrency

Specifies the maximum number of S3 connections that should be established during a transfer.

Environment variable: QUARKUS_S3_CRT_CLIENT_MAX_CONCURRENCY

int

quarkus.s3.crt-client.minimum-part-size-in-bytes

quarkus.s3."client-name".crt-client.minimum-part-size-in-bytes

Sets the minimum part size for transfer parts.

Environment variable: QUARKUS_S3_CRT_CLIENT_MINIMUM_PART_SIZE_IN_BYTES

long

8MB

quarkus.s3.crt-client.target-throughput-in-gbps

quarkus.s3."client-name".crt-client.target-throughput-in-gbps

The target throughput for transfer requests.

Environment variable: QUARKUS_S3_CRT_CLIENT_TARGET_THROUGHPUT_IN_GBPS

double

10

quarkus.s3.crt-client.max-native-memory-limit-in-bytes

quarkus.s3."client-name".crt-client.max-native-memory-limit-in-bytes

The amount of native memory that CRT is allowed to use when making requests to S3. Only specify the memory limit explicitly when necessary. Refer to the AWS SDK documentation for further details.

Environment variable: QUARKUS_S3_CRT_CLIENT_MAX_NATIVE_MEMORY_LIMIT_IN_BYTES

long

Based on a number of parameters such as target throughput

Sync HTTP transport configurations

Type

Default

quarkus.s3.sync-client.connection-timeout

The maximum amount of time to establish a connection before timing out.

Environment variable: QUARKUS_S3_SYNC_CLIENT_CONNECTION_TIMEOUT

Duration 

2S

quarkus.s3.sync-client.socket-timeout

The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out.

Environment variable: QUARKUS_S3_SYNC_CLIENT_SOCKET_TIMEOUT

Duration 

30S

quarkus.s3.sync-client.tls-key-managers-provider.type

TLS key managers provider type.

Available providers:

  • none - Use this provider if you don’t want the client to present any certificates to the remote TLS host.

  • system-property - Provider checks the standard javax.net.ssl.keyStore, javax.net.ssl.keyStorePassword, and javax.net.ssl.keyStoreType properties defined by the JSSE.

  • file-store - Provider that loads the key store from a file.

Environment variable: QUARKUS_S3_SYNC_CLIENT_TLS_KEY_MANAGERS_PROVIDER_TYPE

none, system-property, file-store

system-property

quarkus.s3.sync-client.tls-key-managers-provider.file-store.path

Path to the key store.

Environment variable: QUARKUS_S3_SYNC_CLIENT_TLS_KEY_MANAGERS_PROVIDER_FILE_STORE_PATH

path

quarkus.s3.sync-client.tls-key-managers-provider.file-store.type

Key store type.

See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types.

Environment variable: QUARKUS_S3_SYNC_CLIENT_TLS_KEY_MANAGERS_PROVIDER_FILE_STORE_TYPE

string

quarkus.s3.sync-client.tls-key-managers-provider.file-store.password

Key store password

Environment variable: QUARKUS_S3_SYNC_CLIENT_TLS_KEY_MANAGERS_PROVIDER_FILE_STORE_PASSWORD

string

quarkus.s3.sync-client.tls-trust-managers-provider.type

TLS trust managers provider type.

Available providers:

  • trust-all - Use this provider to disable the validation of servers certificates and therefore trust all server certificates.

  • system-property - Provider checks the standard javax.net.ssl.keyStore, javax.net.ssl.keyStorePassword, and javax.net.ssl.keyStoreType properties defined by the JSSE.

  • file-store - Provider that loads the key store from a file.

Environment variable: QUARKUS_S3_SYNC_CLIENT_TLS_TRUST_MANAGERS_PROVIDER_TYPE

trust-all, system-property, file-store

system-property

quarkus.s3.sync-client.tls-trust-managers-provider.file-store.path

Path to the key store.

Environment variable: QUARKUS_S3_SYNC_CLIENT_TLS_TRUST_MANAGERS_PROVIDER_FILE_STORE_PATH

path

quarkus.s3.sync-client.tls-trust-managers-provider.file-store.type

Key store type.

See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types.

Environment variable: QUARKUS_S3_SYNC_CLIENT_TLS_TRUST_MANAGERS_PROVIDER_FILE_STORE_TYPE

string

quarkus.s3.sync-client.tls-trust-managers-provider.file-store.password

Key store password

Environment variable: QUARKUS_S3_SYNC_CLIENT_TLS_TRUST_MANAGERS_PROVIDER_FILE_STORE_PASSWORD

string

Apache HTTP client specific configurations

Type

Default

quarkus.s3.sync-client.apache.connection-acquisition-timeout

The amount of time to wait when acquiring a connection from the pool before giving up and timing out.

Environment variable: QUARKUS_S3_SYNC_CLIENT_APACHE_CONNECTION_ACQUISITION_TIMEOUT

Duration 

10S

quarkus.s3.sync-client.apache.connection-max-idle-time

The maximum amount of time that a connection should be allowed to remain open while idle.

Environment variable: QUARKUS_S3_SYNC_CLIENT_APACHE_CONNECTION_MAX_IDLE_TIME

Duration 

60S

quarkus.s3.sync-client.apache.connection-time-to-live

The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency.

Environment variable: QUARKUS_S3_SYNC_CLIENT_APACHE_CONNECTION_TIME_TO_LIVE

Duration 

quarkus.s3.sync-client.apache.max-connections

The maximum number of connections allowed in the connection pool.

Each built HTTP client has its own private connection pool.

Environment variable: QUARKUS_S3_SYNC_CLIENT_APACHE_MAX_CONNECTIONS

int

50

quarkus.s3.sync-client.apache.expect-continue-enabled

Whether the client should send an HTTP expect-continue handshake before each request.

Environment variable: QUARKUS_S3_SYNC_CLIENT_APACHE_EXPECT_CONTINUE_ENABLED

boolean

true

quarkus.s3.sync-client.apache.use-idle-connection-reaper

Whether the idle connections in the connection pool should be closed asynchronously.

When enabled, connections left idling for longer than quarkus..sync-client.connection-max-idle-time will be closed. This will not close connections currently in use.

Environment variable: QUARKUS_S3_SYNC_CLIENT_APACHE_USE_IDLE_CONNECTION_REAPER

boolean

true

quarkus.s3.sync-client.apache.tcp-keep-alive

Configure whether to enable or disable TCP KeepAlive.

Environment variable: QUARKUS_S3_SYNC_CLIENT_APACHE_TCP_KEEP_ALIVE

boolean

false

quarkus.s3.sync-client.apache.proxy.enabled

Enable HTTP proxy

Environment variable: QUARKUS_S3_SYNC_CLIENT_APACHE_PROXY_ENABLED

boolean

false

quarkus.s3.sync-client.apache.proxy.endpoint

The endpoint of the proxy server that the SDK should connect through.

Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised.

Environment variable: QUARKUS_S3_SYNC_CLIENT_APACHE_PROXY_ENDPOINT

URI

quarkus.s3.sync-client.apache.proxy.username

The username to use when connecting through a proxy.

Environment variable: QUARKUS_S3_SYNC_CLIENT_APACHE_PROXY_USERNAME

string

quarkus.s3.sync-client.apache.proxy.password

The password to use when connecting through a proxy.

Environment variable: QUARKUS_S3_SYNC_CLIENT_APACHE_PROXY_PASSWORD

string

quarkus.s3.sync-client.apache.proxy.ntlm-domain

For NTLM proxies - the Windows domain name to use when authenticating with the proxy.

Environment variable: QUARKUS_S3_SYNC_CLIENT_APACHE_PROXY_NTLM_DOMAIN

string

quarkus.s3.sync-client.apache.proxy.ntlm-workstation

For NTLM proxies - the Windows workstation name to use when authenticating with the proxy.

Environment variable: QUARKUS_S3_SYNC_CLIENT_APACHE_PROXY_NTLM_WORKSTATION

string

quarkus.s3.sync-client.apache.proxy.preemptive-basic-authentication-enabled

Whether to attempt to authenticate preemptively against the proxy server using basic authentication.

Environment variable: QUARKUS_S3_SYNC_CLIENT_APACHE_PROXY_PREEMPTIVE_BASIC_AUTHENTICATION_ENABLED

boolean

quarkus.s3.sync-client.apache.proxy.non-proxy-hosts

The hosts that the client is allowed to access without going through the proxy.

Environment variable: QUARKUS_S3_SYNC_CLIENT_APACHE_PROXY_NON_PROXY_HOSTS

list of string

AWS CRT-based HTTP client specific configurations

Type

Default

quarkus.s3.sync-client.crt.connection-max-idle-time

The maximum amount of time that a connection should be allowed to remain open while idle.

Environment variable: QUARKUS_S3_SYNC_CLIENT_CRT_CONNECTION_MAX_IDLE_TIME

Duration 

60S

quarkus.s3.sync-client.crt.max-concurrency

The maximum number of allowed concurrent requests.

Environment variable: QUARKUS_S3_SYNC_CLIENT_CRT_MAX_CONCURRENCY

int

50

quarkus.s3.sync-client.crt.connection-acquisition-timeout

The amount of time to wait when initially establishing a connection before giving up and timing out.

Environment variable: QUARKUS_S3_SYNC_CLIENT_CRT_CONNECTION_ACQUISITION_TIMEOUT

Duration 

10S

quarkus.s3.sync-client.crt.proxy.enabled

Enable HTTP proxy

Environment variable: QUARKUS_S3_SYNC_CLIENT_CRT_PROXY_ENABLED

boolean

false

quarkus.s3.sync-client.crt.proxy.endpoint

The endpoint of the proxy server that the SDK should connect through.

Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised.

Environment variable: QUARKUS_S3_SYNC_CLIENT_CRT_PROXY_ENDPOINT

URI

quarkus.s3.sync-client.crt.proxy.username

The username to use when connecting through a proxy.

Environment variable: QUARKUS_S3_SYNC_CLIENT_CRT_PROXY_USERNAME

string

quarkus.s3.sync-client.crt.proxy.password

The password to use when connecting through a proxy.

Environment variable: QUARKUS_S3_SYNC_CLIENT_CRT_PROXY_PASSWORD

string

quarkus.s3.sync-client.crt.tcp-keep-alive.enabled

Configure whether to enable or disable TCP KeepAlive.

Environment variable: QUARKUS_S3_SYNC_CLIENT_CRT_TCP_KEEP_ALIVE_ENABLED

boolean

false

quarkus.s3.sync-client.crt.tcp-keep-alive.keep-alive-interval

Time between TCP keepalive packets being sent to the peer.

Environment variable: QUARKUS_S3_SYNC_CLIENT_CRT_TCP_KEEP_ALIVE_KEEP_ALIVE_INTERVAL

Duration 

75MS

quarkus.s3.sync-client.crt.tcp-keep-alive.keep-alive-timeout

Time to wait for a keepalive response before considering the connection timed out.

Environment variable: QUARKUS_S3_SYNC_CLIENT_CRT_TCP_KEEP_ALIVE_KEEP_ALIVE_TIMEOUT

Duration 

7200MS

quarkus.s3.sync-client.crt.tcp-keep-alive.keep-alive-probes

Number of keepalive probes allowed to fail before the connection is considered lost.

Environment variable: QUARKUS_S3_SYNC_CLIENT_CRT_TCP_KEEP_ALIVE_KEEP_ALIVE_PROBES

int

9

Async HTTP transport configurations

Type

Default

quarkus.s3.async-client.max-concurrency

The maximum number of allowed concurrent requests.

For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_MAX_CONCURRENCY

int

50

quarkus.s3.async-client.max-pending-connection-acquires

The maximum number of pending acquires allowed.

Once this exceeds, acquire tries will be failed.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_MAX_PENDING_CONNECTION_ACQUIRES

int

10000

quarkus.s3.async-client.read-timeout

The amount of time to wait for a read on a socket before an exception is thrown.

Specify 0 to disable.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_READ_TIMEOUT

Duration 

30S

quarkus.s3.async-client.write-timeout

The amount of time to wait for a write on a socket before an exception is thrown.

Specify 0 to disable.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_WRITE_TIMEOUT

Duration 

30S

quarkus.s3.async-client.connection-timeout

The amount of time to wait when initially establishing a connection before giving up and timing out.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_CONNECTION_TIMEOUT

Duration 

10S

quarkus.s3.async-client.connection-acquisition-timeout

The amount of time to wait when acquiring a connection from the pool before giving up and timing out.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_CONNECTION_ACQUISITION_TIMEOUT

Duration 

2S

quarkus.s3.async-client.connection-time-to-live

The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_CONNECTION_TIME_TO_LIVE

Duration 

quarkus.s3.async-client.connection-max-idle-time

The maximum amount of time that a connection should be allowed to remain open while idle.

Currently has no effect if quarkus..async-client.use-idle-connection-reaper is false.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_CONNECTION_MAX_IDLE_TIME

Duration 

5S

quarkus.s3.async-client.use-idle-connection-reaper

Whether the idle connections in the connection pool should be closed.

When enabled, connections left idling for longer than quarkus..async-client.connection-max-idle-time will be closed. This will not close connections currently in use.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_USE_IDLE_CONNECTION_REAPER

boolean

true

quarkus.s3.async-client.tcp-keep-alive

Configure whether to enable or disable TCP KeepAlive. Applicable only to netty-nio client.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_TCP_KEEP_ALIVE

boolean

false

AWS CRT-based HTTP client specific configurations

Type

Default

quarkus.s3.async-client.crt.connection-max-idle-time

The maximum amount of time that a connection should be allowed to remain open while idle.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_CRT_CONNECTION_MAX_IDLE_TIME

Duration 

60S

quarkus.s3.async-client.crt.max-concurrency

The maximum number of allowed concurrent requests.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_CRT_MAX_CONCURRENCY

int

50

quarkus.s3.async-client.crt.connection-acquisition-timeout

The amount of time to wait when initially establishing a connection before giving up and timing out.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_CRT_CONNECTION_ACQUISITION_TIMEOUT

Duration 

10S

quarkus.s3.async-client.crt.proxy.enabled

Enable HTTP proxy

Environment variable: QUARKUS_S3_ASYNC_CLIENT_CRT_PROXY_ENABLED

boolean

false

quarkus.s3.async-client.crt.proxy.endpoint

The endpoint of the proxy server that the SDK should connect through.

Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_CRT_PROXY_ENDPOINT

URI

quarkus.s3.async-client.crt.proxy.username

The username to use when connecting through a proxy.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_CRT_PROXY_USERNAME

string

quarkus.s3.async-client.crt.proxy.password

The password to use when connecting through a proxy.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_CRT_PROXY_PASSWORD

string

quarkus.s3.async-client.crt.tcp-keep-alive.enabled

Configure whether to enable or disable TCP KeepAlive.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_CRT_TCP_KEEP_ALIVE_ENABLED

boolean

false

quarkus.s3.async-client.crt.tcp-keep-alive.keep-alive-interval

Time between TCP keepalive packets being sent to the peer.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_CRT_TCP_KEEP_ALIVE_KEEP_ALIVE_INTERVAL

Duration 

75MS

quarkus.s3.async-client.crt.tcp-keep-alive.keep-alive-timeout

Time to wait for a keepalive response before considering the connection timed out.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_CRT_TCP_KEEP_ALIVE_KEEP_ALIVE_TIMEOUT

Duration 

7200MS

quarkus.s3.async-client.crt.tcp-keep-alive.keep-alive-probes

Number of keepalive probes allowed to fail before the connection is considered lost.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_CRT_TCP_KEEP_ALIVE_KEEP_ALIVE_PROBES

int

9

quarkus.s3.async-client.protocol

The HTTP protocol to use.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_PROTOCOL

http1-1, http2

http1-1

quarkus.s3.async-client.ssl-provider

The SSL Provider to be used in the Netty client.

Default is OPENSSL if available, JDK otherwise.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_SSL_PROVIDER

jdk, openssl, openssl-refcnt

quarkus.s3.async-client.http2.max-streams

The maximum number of concurrent streams for an HTTP/2 connection.

This setting is only respected when the HTTP/2 protocol is used.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_HTTP2_MAX_STREAMS

long

4294967295

quarkus.s3.async-client.http2.initial-window-size

The initial window size for an HTTP/2 stream.

This setting is only respected when the HTTP/2 protocol is used.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_HTTP2_INITIAL_WINDOW_SIZE

int

1048576

quarkus.s3.async-client.http2.health-check-ping-period

Sets the period that the Netty client will send PING frames to the remote endpoint to check the health of the connection. To disable this feature, set a duration of 0.

This setting is only respected when the HTTP/2 protocol is used.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_HTTP2_HEALTH_CHECK_PING_PERIOD

Duration 

5

quarkus.s3.async-client.proxy.enabled

Enable HTTP proxy.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_PROXY_ENABLED

boolean

false

quarkus.s3.async-client.proxy.endpoint

The endpoint of the proxy server that the SDK should connect through.

Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_PROXY_ENDPOINT

URI

quarkus.s3.async-client.proxy.non-proxy-hosts

The hosts that the client is allowed to access without going through the proxy.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_PROXY_NON_PROXY_HOSTS

list of string

quarkus.s3.async-client.tls-key-managers-provider.type

TLS key managers provider type.

Available providers:

  • none - Use this provider if you don’t want the client to present any certificates to the remote TLS host.

  • system-property - Provider checks the standard javax.net.ssl.keyStore, javax.net.ssl.keyStorePassword, and javax.net.ssl.keyStoreType properties defined by the JSSE.

  • file-store - Provider that loads the key store from a file.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_TLS_KEY_MANAGERS_PROVIDER_TYPE

none, system-property, file-store

system-property

quarkus.s3.async-client.tls-key-managers-provider.file-store.path

Path to the key store.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_TLS_KEY_MANAGERS_PROVIDER_FILE_STORE_PATH

path

quarkus.s3.async-client.tls-key-managers-provider.file-store.type

Key store type.

See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_TLS_KEY_MANAGERS_PROVIDER_FILE_STORE_TYPE

string

quarkus.s3.async-client.tls-key-managers-provider.file-store.password

Key store password

Environment variable: QUARKUS_S3_ASYNC_CLIENT_TLS_KEY_MANAGERS_PROVIDER_FILE_STORE_PASSWORD

string

quarkus.s3.async-client.tls-trust-managers-provider.type

TLS trust managers provider type.

Available providers:

  • trust-all - Use this provider to disable the validation of servers certificates and therefore trust all server certificates.

  • system-property - Provider checks the standard javax.net.ssl.keyStore, javax.net.ssl.keyStorePassword, and javax.net.ssl.keyStoreType properties defined by the JSSE.

  • file-store - Provider that loads the key store from a file.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_TLS_TRUST_MANAGERS_PROVIDER_TYPE

trust-all, system-property, file-store

system-property

quarkus.s3.async-client.tls-trust-managers-provider.file-store.path

Path to the key store.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_TLS_TRUST_MANAGERS_PROVIDER_FILE_STORE_PATH

path

quarkus.s3.async-client.tls-trust-managers-provider.file-store.type

Key store type.

See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_TLS_TRUST_MANAGERS_PROVIDER_FILE_STORE_TYPE

string

quarkus.s3.async-client.tls-trust-managers-provider.file-store.password

Key store password

Environment variable: QUARKUS_S3_ASYNC_CLIENT_TLS_TRUST_MANAGERS_PROVIDER_FILE_STORE_PASSWORD

string

quarkus.s3.async-client.event-loop.override

Enable the custom configuration of the Netty event loop group. This option is only available when using Quarkus 3.x. With Quarkus 4, the AWS SDK always uses its own event loop.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_EVENT_LOOP_OVERRIDE

boolean

quarkus.s3.async-client.event-loop.number-of-threads

Number of threads to use for the event loop group.

If not set, the default Netty thread count is used (which is double the number of available processors unless the io.netty.eventLoopThreads system property is set).

Environment variable: QUARKUS_S3_ASYNC_CLIENT_EVENT_LOOP_NUMBER_OF_THREADS

int

quarkus.s3.async-client.event-loop.thread-name-prefix

The thread name prefix for threads created by this thread factory used by event loop group.

The prefix will be appended with a number unique to the thread factory and a number unique to the thread.

If not specified it defaults to aws-java-sdk-NettyEventLoop

Environment variable: QUARKUS_S3_ASYNC_CLIENT_EVENT_LOOP_THREAD_NAME_PREFIX

string

quarkus.s3.async-client.advanced.use-future-completion-thread-pool

Whether the default thread pool should be used to complete the futures returned from the HTTP client request.

When disabled, HTTP attempt completion is not offloaded to the Quarkus worker pool. Vert.x context propagation, when applicable, independently dispatches the final result to a Vert.x event loop.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_ADVANCED_USE_FUTURE_COMPLETION_THREAD_POOL

boolean

true

quarkus.s3.async-client.advanced.vertx-context-propagation

Whether the final results of async calls made from a Vert.x event loop are delivered on the caller’s context.

When enabled, a call made from a Vert.x event loop is completed on the caller’s context. Calls made from workers (including @Blocking endpoints), virtual threads or other threads keep the SDK’s completion behavior, as configured by use-future-completion-thread-pool.

When disabled, the SDK completion behavior is kept, including the use-future-completion-thread-pool setting.

This only applies when the Quarkus Vert.x extension is present.

Environment variable: QUARKUS_S3_ASYNC_CLIENT_ADVANCED_VERTX_CONTEXT_PROPAGATION

boolean

true
About the Duration format

To write duration values, use the standard java.time.Duration format. See the Duration#parse() Java API documentation for more information.

You can also use a simplified format, starting with a number:

  • If the value is only a number, it represents time in seconds.

  • If the value is a number followed by ms, it represents time in milliseconds.

In other cases, the simplified format is translated to the java.time.Duration format for parsing:

  • If the value is a number followed by h, m, or s, it is prefixed with PT.

  • If the value is a number followed by d, it is prefixed with P.
About the MemorySize format

A size configuration option recognizes strings in this format (shown as a regular expression): [0-9]+[KkMmGgTtPpEeZzYy]?.

If no suffix is given, assume bytes.