Quarkus Opensearch Extension

The quarkus-opensearch extension allows you to connect to an OpenSearch cluster using the clients provided by the OpenSearch project.

OpenSearch 3.x Support

This version supports OpenSearch 3.x which requires:

  • JDK 21 minimum - OpenSearch 3.0 requires Java 21 as the minimum runtime

  • OpenSearch Java Client only - The deprecated REST clients have been removed

If you need OpenSearch 2.x support, use an earlier version of this extension.

OpenSearch Clients

OpenSearch Java Client

This is the recommended and only supported OpenSearch client for OpenSearch 3.x. The OpenSearch Java client lets you interact with OpenSearch through Java methods and data structures, and provides both synchronous and asynchronous client implementations.

Installation

OpenSearch Java client

The java client does not have any dependencies on the REST client. All clients are sharing most of the configuration properties. The AWS related configuration properties quarkus.opensearch.aws.* are only applicable to this java client.

If you want to use this client all you need to do is add the io.quarkiverse.opensearch:quarkus-opensearch-java-client extension first to your build file.

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

<dependency>
    <groupId>io.quarkiverse.opensearch</groupId>
    <artifactId>quarkus-opensearch-java-client</artifactId>
    <version>3.2.2</version>
</dependency>

Transport Provider (Required)

The Java client requires a transport provider to communicate with OpenSearch. You must add one of the following transport dependencies based on your deployment target.

Apache HttpClient5 Transport (Recommended)

Use this transport for:

  • Local development with Dev Services

  • Self-hosted OpenSearch clusters

  • Any non-AWS deployment

<dependency>
  <groupId>io.quarkiverse.opensearch</groupId>
  <artifactId>quarkus-opensearch-transport-apache</artifactId>
</dependency>

AWS SDK2 Transport

Use this transport only when connecting to AWS OpenSearch Service or AWS OpenSearch Serverless. This transport requires the quarkus.opensearch.aws.service configuration property to be set.

<dependency>
  <groupId>io.quarkiverse.opensearch</groupId>
  <artifactId>quarkus-opensearch-transport-aws</artifactId>
</dependency>
# Required for AWS transport to activate
quarkus.opensearch.aws.service=es    # or 'aoss' for OpenSearch Serverless
quarkus.opensearch.aws.region=us-west-2

Using Both Transports

If you deploy to AWS but also use Dev Services for local development, you can include both transport dependencies. The appropriate transport will be selected automatically based on your configuration:

  • When quarkus.opensearch.aws.service is set → AWS transport is used

  • When quarkus.opensearch.aws.service is not set → Apache transport is used

<!-- For local development and Dev Services -->
<dependency>
  <groupId>io.quarkiverse.opensearch</groupId>
  <artifactId>quarkus-opensearch-transport-apache</artifactId>
</dependency>

<!-- For AWS deployment -->
<dependency>
  <groupId>io.quarkiverse.opensearch</groupId>
  <artifactId>quarkus-opensearch-transport-aws</artifactId>
</dependency>
# Only set AWS config in production profile
%prod.quarkus.opensearch.aws.service=es
%prod.quarkus.opensearch.aws.region=us-west-2
%prod.quarkus.opensearch.hosts=search-mydomain.us-west-2.es.amazonaws.com

If no matching transport provider is found, the application will fail at runtime with a detailed error message explaining which providers are available and what configuration is needed.

Configuring Additional Named Clients

This extension supports defining and injecting multiple named OpenSearch clients, useful when your application needs to connect to different OpenSearch clusters (e.g., for analytics, logging, or operational data).

A named client can be configured using quarkus.opensearch."client-name".*.

Example: Default and Additional Client
# Default client (unnamed)
quarkus.opensearch.hosts=localhost:9200

# Additional client named "analytics"
quarkus.opensearch.analytics.hosts=analytics-cluster.internal:9200
quarkus.opensearch.analytics.username=some-user
quarkus.opensearch.analytics.password=some-password
quarkus.opensearch.analytics.aws.region=us-west-2
Injecting the Default Client

If you’re using only a single OpenSearch cluster, you can inject the default client without any qualifiers:

import jakarta.inject.Inject;
import org.opensearch.client.opensearch.OpenSearchClient;

public class MyService {

    @Inject
    OpenSearchClient defaultClient;

    public void run() {
        // Use the defaultClient to interact with OpenSearch
    }
}
Injecting Named Clients in Your Code

To use a named client in your application, inject it using the @OpenSearchClientName qualifier:

import jakarta.inject.Inject;
import io.quarkiverse.opensearch.OpenSearchClientName;
import org.opensearch.client.opensearch.OpenSearchClient;

public class ReportService {

    @Inject
    @OpenSearchClientName("analytics")
    OpenSearchClient analyticsClient;

    public void runQuery() {
        // Use the analyticsClient to run a search
    }
}

The @OpenSearchClientName("<client-name>") injection is only supported for the OpenSearch Java Client module.

OpenSearch REST High-Level Client

The REST High-Level Client depends on the REST client and does not require any additional configuration.

If you want to use this client all you need to do is add the io.quarkiverse.opensearch:quarkus-opensearch-rest-high-level-client extension first to your build file.

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

<dependency>
    <groupId>io.quarkiverse.opensearch</groupId>
    <artifactId>quarkus-opensearch-rest-high-level-client</artifactId>
    <version>3.2.2</version>
</dependency>

OpenSearch REST Low-Level Client

If you want to use this extension, you need to add the io.quarkiverse.opensearch:quarkus-opensearch-rest-client extension first to your build file.

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

<dependency>
    <groupId>io.quarkiverse.opensearch</groupId>
    <artifactId>quarkus-opensearch-rest-client</artifactId>
    <version>3.2.2</version>
</dependency>

Configuring Opensearch

The main property to configure is the URL to connect to the Opensearch cluster.

For a typical clustered Opensearch service, a sample configuration would look like the following:

# configure the Elasticsearch client for a cluster of two nodes
quarkus.opensearch.hosts = opensearch-01:9200,opensearch-02:9200

In this case, we are using a single instance running on localhost:

# configure the Opensearch client for a single instance on localhost
quarkus.opensearch.hosts = localhost:9200

If you need a more advanced configuration, you can find the comprehensive list of supported configuration properties at the end of this guide.

SSL/TLS Configuration

When connecting to OpenSearch over HTTPS, you can configure TLS settings using the Quarkus TLS registry. This is the recommended approach for managing SSL/TLS configuration.

Basic HTTPS Connection

For HTTPS connections with valid certificates trusted by the JVM:

quarkus.opensearch.hosts=opensearch.example.com:9200
quarkus.opensearch.protocol=https
quarkus.opensearch.username=admin
quarkus.opensearch.password=admin

Using a Custom Trust Store

To use a custom trust store (e.g., for self-signed certificates):

quarkus.opensearch.hosts=opensearch.example.com:9200
quarkus.opensearch.protocol=https
quarkus.opensearch.tls.tls-configuration-name=opensearch-tls

# Define the TLS configuration
quarkus.tls.opensearch-tls.trust-store.p12.path=/path/to/truststore.p12
quarkus.tls.opensearch-tls.trust-store.p12.password=changeit

Disabling SSL Verification (Development Only)

Disabling SSL verification should only be used in development environments. Never disable SSL verification in production.

For development environments where you don’t have valid certificates:

quarkus.opensearch.hosts=opensearch.example.com:9200
quarkus.opensearch.protocol=https
quarkus.opensearch.tls.tls-configuration-name=opensearch-dev

# Trust all certificates and disable hostname verification
quarkus.tls.opensearch-dev.trust-all=true
quarkus.tls.opensearch-dev.hostname-verification-algorithm=NONE

You can scope this to development mode only using profiles:

# Production uses proper certificates
%prod.quarkus.opensearch.protocol=https

# Development trusts all certificates
%dev.quarkus.opensearch.tls.tls-configuration-name=dev-tls
%dev.quarkus.tls.dev-tls.trust-all=true
%dev.quarkus.tls.dev-tls.hostname-verification-algorithm=NONE

The legacy quarkus.opensearch.ssl.* properties are deprecated and will be removed in a future version. Please migrate to the Quarkus TLS registry configuration shown above.

mTLS with Certificate Reload

For environments using mutual TLS (mTLS) with automatic certificate rotation (e.g., Kubernetes with cert-manager), you can configure automatic certificate reload:

quarkus.opensearch.hosts=opensearch.example.com:9200
quarkus.opensearch.protocol=https
quarkus.opensearch.tls.tls-configuration-name=opensearch-mtls

# Client certificate (mTLS)
quarkus.tls.opensearch-mtls.key-store.p12.path=/certs/client.p12
quarkus.tls.opensearch-mtls.key-store.p12.password=${KEYSTORE_PASSWORD}

# Trust store for server certificate
quarkus.tls.opensearch-mtls.trust-store.pem.certs=/certs/ca.pem

# Automatic reload every 5 minutes
quarkus.tls.opensearch-mtls.reload-period=5m

When certificates are rotated (e.g., by cert-manager), the extension automatically picks up the new certificates without requiring an application restart. New connections will use the updated certificates.

For programmatic certificate reload, you can call:

import io.quarkiverse.opensearch.transport.apache.ApacheHttpTransportProvider;

// Trigger immediate reload of all certificates
int reloadedCount = ApacheHttpTransportProvider.reloadAllCertificates();

Per-Request Transport Options

The extension provides an SPI (Service Provider Interface) for injecting per-request transport options into OpenSearch requests. This is useful for:

  • OIDC/OAuth2 token propagation - Pass bearer tokens to OpenSearch Security plugin

  • Multi-tenant headers - Inject tenant identifiers for Document Level Security (DLS)

  • Request tracing - Add correlation IDs and tracing headers

  • Custom authentication - Implement custom authentication schemes

Implementing a Transport Options Provider

Create a CDI bean that implements OpenSearchTransportOptionsProvider and annotate it with @OpenSearchTransportOptionsConfig:

import java.util.Optional;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

import org.opensearch.client.transport.TransportOptions;

import io.quarkus.security.identity.SecurityIdentity;
import io.quarkiverse.opensearch.transport.OpenSearchTransportOptionsConfig;
import io.quarkiverse.opensearch.transport.spi.OpenSearchTransportOptionsProvider;

@ApplicationScoped
@OpenSearchTransportOptionsConfig  // Required qualifier
public class OidcTokenProvider implements OpenSearchTransportOptionsProvider {

    @Inject
    SecurityIdentity securityIdentity;

    @Override
    public Optional<TransportOptions> getTransportOptions(String clientName) {
        if (securityIdentity.isAnonymous()) {
            return Optional.empty();
        }

        var credential = securityIdentity.getCredential(
                io.quarkus.oidc.AccessTokenCredential.class);
        if (credential == null) {
            return Optional.empty();
        }

        return Optional.of(TransportOptions.builder()
                .addHeader("Authorization", "Bearer " + credential.getToken())
                .build());
    }

    @Override
    public int priority() {
        return 10; // Lower number = higher priority
    }
}

The @OpenSearchTransportOptionsConfig qualifier is required for the provider to be discovered.

Using the Request-Scoped Client

To use per-request transport options, inject OpenSearchRequestScopedClient instead of the regular OpenSearchClient:

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

import org.opensearch.client.opensearch.OpenSearchClient;
import org.opensearch.client.opensearch.core.SearchResponse;

import io.quarkiverse.opensearch.client.runtime.OpenSearchRequestScopedClient;

@Path("/search")
public class SearchResource {

    @Inject
    OpenSearchRequestScopedClient requestScopedClient;

    @GET
    public String search() throws Exception {
        // Client automatically includes headers from all registered providers
        OpenSearchClient client = requestScopedClient.getClient();

        SearchResponse<MyDocument> response = client.search(s -> s
                .index("my-index")
                .query(q -> q.matchAll(m -> m)),
                MyDocument.class);

        return "Found " + response.hits().total().value() + " documents";
    }
}

For named clients:

// Get a specific named client with per-request options
OpenSearchClient analyticsClient = requestScopedClient.getClient("analytics");
OpenSearchAsyncClient asyncClient = requestScopedClient.getAsyncClient("analytics");

Multiple Providers

You can register multiple providers. They are invoked in priority order (lower number = higher priority) and their transport options are merged:

// Provider 1: Authentication (priority 10 - runs first)
@ApplicationScoped
@OpenSearchTransportOptionsConfig
public class AuthProvider implements OpenSearchTransportOptionsProvider {
    @Override
    public Optional<TransportOptions> getTransportOptions(String clientName) {
        return Optional.of(TransportOptions.builder()
                .addHeader("Authorization", "Bearer " + getToken())
                .build());
    }

    @Override
    public int priority() { return 10; }
}

// Provider 2: Tenant headers (priority 50)
@ApplicationScoped
@OpenSearchTransportOptionsConfig
public class TenantProvider implements OpenSearchTransportOptionsProvider {
    @Inject
    SecurityIdentity identity;

    @Override
    public Optional<TransportOptions> getTransportOptions(String clientName) {
        String tenant = identity.getAttribute("tenant_id");
        return Optional.of(TransportOptions.builder()
                .addHeader("X-Tenant-Id", tenant != null ? tenant : "default")
                .build());
    }

    @Override
    public int priority() { return 50; }
}

// Provider 3: Tracing (priority 100 - runs last)
@ApplicationScoped
@OpenSearchTransportOptionsConfig
public class TracingProvider implements OpenSearchTransportOptionsProvider {
    @Override
    public Optional<TransportOptions> getTransportOptions(String clientName) {
        return Optional.of(TransportOptions.builder()
                .addHeader("X-Request-Id", UUID.randomUUID().toString())
                .build());
    }

    @Override
    public int priority() { return 100; }
}

Client-Specific Options

Providers can return different options based on the client name:

@ApplicationScoped
@OpenSearchTransportOptionsConfig
public class ClientSpecificProvider implements OpenSearchTransportOptionsProvider {

    @Override
    public Optional<TransportOptions> getTransportOptions(String clientName) {
        return switch (clientName) {
            case "analytics" -> Optional.of(TransportOptions.builder()
                    .addHeader("X-Priority", "low")
                    .setParameter("timeout", "60s")
                    .build());
            case "search" -> Optional.of(TransportOptions.builder()
                    .addHeader("X-Priority", "high")
                    .build());
            default -> Optional.empty(); // No options for other clients
        };
    }
}

When to Use Request-Scoped vs Regular Client

Use Case Client Reason

Static credentials (username/password)

@Inject OpenSearchClient

Credentials don’t change per request

OIDC token propagation

@Inject OpenSearchRequestScopedClient

Token is different for each user/request

Multi-tenant applications

@Inject OpenSearchRequestScopedClient

Tenant context changes per request

Background jobs (no user context)

@Inject OpenSearchClient

No request context available

Request tracing/correlation

@Inject OpenSearchRequestScopedClient

Headers are request-specific

Dev Services

Quarkus supports a feature called Dev Services that allows you to start various containers without any config. In the case of Opensearch, this support extends to the default Opensearch connection. What that means practically is that, if you have not configured quarkus.opensearch.hosts, Quarkus will automatically start an Opensearch container when running tests or dev mode, and automatically configure the connection.

When running the production version of the application, the Opensearch connection needs to be configured as usual, so if you want to include a production database config in your application.properties and continue to use Dev Services we recommend that you use the %prod. profile to define your Opensearch settings.

Extension Configuration Reference

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

Configuration property

Type

Default

quarkus.opensearch.health.enabled

Whether a health check is published in case the smallrye-health extension is present.

Environment variable: QUARKUS_OPENSEARCH_HEALTH_ENABLED

boolean

true

quarkus.opensearch.devservices.enabled

If Dev Services for OpenSearch has been explicitly enabled or disabled. Dev Services are generally enabled by default, unless there is an existing configuration present. For OpenSearch, Dev Services starts a server unless quarkiverse.opensearch.hosts is set.

Environment variable: QUARKUS_OPENSEARCH_DEVSERVICES_ENABLED

boolean

quarkus.opensearch.devservices.port

Optional fixed port the dev service will listen to.

If not defined, the port will be chosen randomly.

Environment variable: QUARKUS_OPENSEARCH_DEVSERVICES_PORT

int

quarkus.opensearch.devservices.image-name

The OpenSearch container image to use. Defaults to the opensearch image provided by OpenSearch.

Environment variable: QUARKUS_OPENSEARCH_DEVSERVICES_IMAGE_NAME

string

docker.io/opensearchproject/opensearch:3.3.2

quarkus.opensearch.devservices.java-opts

The value for the OPENSEARCH_JAVA_OPTS env variable. Defaults to setting the heap to 512MB min - 1GB max.

Environment variable: QUARKUS_OPENSEARCH_DEVSERVICES_JAVA_OPTS

string

-Xms512m -Xmx1g

quarkus.opensearch.devservices.shared

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

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

Container sharing is only used in dev mode.

Environment variable: QUARKUS_OPENSEARCH_DEVSERVICES_SHARED

boolean

true

quarkus.opensearch.devservices.service-name

The value of the quarkus-dev-service-opensearch 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 OpenSearch looks for a container with the quarkus-dev-service-opensearch 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-opensearch label set to the specified value.

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

Environment variable: QUARKUS_OPENSEARCH_DEVSERVICES_SERVICE_NAME

string

opensearch

quarkus.opensearch.hosts

quarkus.opensearch."client-name".hosts

The list of hosts of the OpenSearch servers, when accessing AWS OpenSearch set to AWS endpoint name. Host Example: opensearch-01:9200,opensearch-02:9200 AWS Endpoint Example: search-domain-name-identifier.region.es.amazonaws.com

Environment variable: QUARKUS_OPENSEARCH_HOSTS

list of string

quarkus.opensearch.protocol

quarkus.opensearch."client-name".protocol

The protocol to use when contacting OpenSearch servers. Set to "https" to enable SSL/TLS.

Environment variable: QUARKUS_OPENSEARCH_PROTOCOL

string

http

quarkus.opensearch.username

quarkus.opensearch."client-name".username

The username for basic HTTP authentication.

Environment variable: QUARKUS_OPENSEARCH_USERNAME

string

quarkus.opensearch.password

quarkus.opensearch."client-name".password

The password for basic HTTP authentication.

Environment variable: QUARKUS_OPENSEARCH_PASSWORD

string

quarkus.opensearch.connection-timeout

quarkus.opensearch."client-name".connection-timeout

The connection timeout.

Environment variable: QUARKUS_OPENSEARCH_CONNECTION_TIMEOUT

Duration 

15S

quarkus.opensearch.thread-timeout

quarkus.opensearch."client-name".thread-timeout

The connection timeout.

Environment variable: QUARKUS_OPENSEARCH_THREAD_TIMEOUT

Duration 

30S

quarkus.opensearch.socket-timeout

quarkus.opensearch."client-name".socket-timeout

The socket timeout.

Environment variable: QUARKUS_OPENSEARCH_SOCKET_TIMEOUT

Duration 

30S

quarkus.opensearch.max-connections

quarkus.opensearch."client-name".max-connections

The maximum number of connections to all the OpenSearch servers.

Environment variable: QUARKUS_OPENSEARCH_MAX_CONNECTIONS

int

20

quarkus.opensearch.max-connections-per-route

quarkus.opensearch."client-name".max-connections-per-route

The maximum number of connections per OpenSearch server.

Environment variable: QUARKUS_OPENSEARCH_MAX_CONNECTIONS_PER_ROUTE

int

10

quarkus.opensearch.io-thread-counts

quarkus.opensearch."client-name".io-thread-counts

The number of IO thread. By default, this is the number of locally detected processors.

Thread counts higher than the number of processors should not be necessary because the I/O threads rely on non-blocking operations, but you may want to use a thread count lower than the number of processors.

Environment variable: QUARKUS_OPENSEARCH_IO_THREAD_COUNTS

int

quarkus.opensearch.aws.region

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

AWS Region

Environment variable: QUARKUS_OPENSEARCH_AWS_REGION

string

us-west-2

quarkus.opensearch.aws.service

quarkus.opensearch."client-name".aws.service

Set to "es" or "aoss" to use AWS OpenSearch Service. es : Amazon OpenSearch Service aoss : Amazon OpenSearch Serverless

Environment variable: QUARKUS_OPENSEARCH_AWS_SERVICE

string

quarkus.opensearch.aws.access-key-id

quarkus.opensearch."client-name".aws.access-key-id

AWS Secret Access Key for setting up StaticCredentialsProvider

Environment variable: QUARKUS_OPENSEARCH_AWS_ACCESS_KEY_ID

string

quarkus.opensearch.aws.access-key-secret

quarkus.opensearch."client-name".aws.access-key-secret

AWS Secret Access Key Secret for setting up StaticCredentialsProvider

Environment variable: QUARKUS_OPENSEARCH_AWS_ACCESS_KEY_SECRET

string

quarkus.opensearch.tls.tls-configuration-name

quarkus.opensearch."client-name".tls.tls-configuration-name

The name of the TLS configuration to use. This refers to a configuration group defined under quarkus.tls.*. If not set, no explicit TLS configuration will be applied beyond the default JDK behavior.

Environment variable: QUARKUS_OPENSEARCH_TLS_TLS_CONFIGURATION_NAME

string

required

quarkus.opensearch.discovery.enabled

quarkus.opensearch."client-name".discovery.enabled

Defines if automatic discovery is enabled.

Environment variable: QUARKUS_OPENSEARCH_DISCOVERY_ENABLED

boolean

false

quarkus.opensearch.discovery.refresh-interval

quarkus.opensearch."client-name".discovery.refresh-interval

Refresh interval of the node list.

Environment variable: QUARKUS_OPENSEARCH_DISCOVERY_REFRESH_INTERVAL

Duration 

5M

quarkus.opensearch.health-check.enabled

quarkus.opensearch."client-name".health-check.enabled

Whether this client should be included in health checks. When set to false, this client will be excluded from the OpenSearch health check endpoint.

Environment variable: QUARKUS_OPENSEARCH_HEALTH_CHECK_ENABLED

boolean

true

quarkus.opensearch.ssl.key-store-file

quarkus.opensearch."client-name".ssl.key-store-file

This property is deprecated since 2.0.0.

Optional keyStoreFile to be used when connecting to cluster nodes

Environment variable: QUARKUS_OPENSEARCH_SSL_KEY_STORE_FILE

string

quarkus.opensearch.ssl.key-store-password

quarkus.opensearch."client-name".ssl.key-store-password

This property is deprecated since 2.0.0.

Optional password for accessing keyStoreFile

Environment variable: QUARKUS_OPENSEARCH_SSL_KEY_STORE_PASSWORD

string

quarkus.opensearch.ssl.verify-hostname

quarkus.opensearch."client-name".ssl.verify-hostname

This property is deprecated since 2.0.0.

SSL Verify Hostname

Environment variable: QUARKUS_OPENSEARCH_SSL_VERIFY_HOSTNAME

boolean

true

quarkus.opensearch.ssl.verify

quarkus.opensearch."client-name".ssl.verify

This property is deprecated since 2.0.0.

Verify SSL Certificates

Environment variable: QUARKUS_OPENSEARCH_SSL_VERIFY

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.