Unleash Provider

The Unleash provider connects to an Unleash instance and evaluates feature flags in-process. Flag definitions are polled from the Unleash API over HTTP and evaluated locally using the Yggdrasil engine (a native Rust library), so no network call is made during flag evaluation.

This extension depends on:

Component Version Source

Yggdrasil engine (native)

1.0.1

Unleash/yggdrasil

Installation

<dependency>
    <groupId>io.quarkiverse.openfeature</groupId>
    <artifactId>quarkus-openfeature-unleash</artifactId>
    <version>1.0.0.Alpha1</version>
</dependency>

Configuration

By default, the provider connects to http://localhost:4242/api. To connect to a different Unleash instance:

quarkus.openfeature.unleash.url=https://unleash.example.com/api

For named domains:

quarkus.openfeature."experimentation".unleash.url=https://unleash-experiments.example.com/api

TLS

The provider uses the Quarkus TLS registry for TLS configuration. First, configure a named TLS configuration in application.properties, then reference it:

quarkus.tls.unleash.trust-store.pem.certs=ca.pem

quarkus.openfeature.unleash.tls-configuration-name=unleash

See the Quarkus TLS registry documentation for all available options.

Authentication

The Unleash server requires a backend token to access the API. Without a valid token, API requests are rejected and the provider enters the FATAL state.

The Unleash dev service configures the token automatically — no manual configuration is needed. Without dev services, configure the API key explicitly:

quarkus.openfeature.unleash.api-key=default:production.some-secret

Setting api-key directly in configuration is suitable for development and testing. For production, use a credentials provider such as Vault:

quarkus.openfeature.unleash.credentials-provider=unleash-token
quarkus.openfeature.unleash.credentials-provider-name=vault-credentials-provider

Evaluation context

All fields of the Unleash context come from the OpenFeature context attributes. Some may be provided through other means, but a context attribute is always preferred.

Field Origin

appName

Evaluation context attribute appName, or configuration

environment

Evaluation context attribute environment, or configuration

userId

Targeting key from the evaluation context

sessionId

Evaluation context attribute sessionId

remoteAddress

Evaluation context attribute remoteAddress

currentTime

Evaluation context attribute currentTime, or current time

properties

All other evaluation context attributes

The appName defaults to the Quarkus application name (quarkus.application.name), but may be reconfigured. The environment may also be configured:

quarkus.openfeature.unleash.app-name=my-app
quarkus.openfeature.unleash.environment=production

Dev Services

In dev and test mode, an Unleash server container (with a PostgreSQL database) is started automatically if no quarkus.openfeature.unleash.url is configured and Docker is available. If no flag definition file is found, Unleash starts with an empty configuration.

To provide flag definitions to the dev service, place an unleash.json file in src/main/resources. This file uses the standard Unleash export/import JSON format:

{
  "features": [
    {"name": "welcome-banner", "type": "release", "project": "default"}
  ],
  "featureStrategies": [
    {
      "name": "default",
      "featureName": "welcome-banner",
      "parameters": {}
    }
  ],
  "featureEnvironments": [
    {"enabled": true, "featureName": "welcome-banner", "environment": "development", "name": "welcome-banner"}
  ]
}

The dev service picks up this file automatically. You can also configure a different path:

quarkus.openfeature.unleash.devservices.path=my-flags.json

Changes to the flag definition file are detected during live reload and the Unleash container is restarted automatically.

Connection lifecycle

The provider polls the Unleash API for the full flag configuration on a regular interval. On connection loss, it automatically retries with a shorter interval. The provider lifecycle follows the OpenFeature specification:

READY

The provider has received flag data and is serving evaluations.

STALE

The connection was lost. The provider continues serving cached flag values while reconnecting.

ERROR

The provider did not reconnect within the grace period (default 1 minute).

FATAL

The server returned an authentication error (HTTP 401 or 403). The provider will not attempt to reconnect.

The grace period is configurable:

quarkus.openfeature.unleash.grace-period=10m

Configuration Reference

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

Configuration property

Type

Default

quarkus.openfeature.unleash.url

quarkus.openfeature."domain-name".unleash.url

Unleash API URL.

Environment variable: QUARKUS_OPENFEATURE_UNLEASH_URL

string

http://localhost:4242/api

quarkus.openfeature.unleash.api-key

quarkus.openfeature."domain-name".unleash.api-key

Backend token for authentication with Unleash.

Environment variable: QUARKUS_OPENFEATURE_UNLEASH_API_KEY

string

quarkus.openfeature.unleash.poll-interval

quarkus.openfeature."domain-name".unleash.poll-interval

Interval between synchronization polls. When a successful poll finishes, the next poll is scheduled in this interval. In case the poll is unsuccessful, retry happens on an internally managed schedule.

Environment variable: QUARKUS_OPENFEATURE_UNLEASH_POLL_INTERVAL

Duration 

1M

quarkus.openfeature.unleash.credentials-provider

quarkus.openfeature."domain-name".unleash.credentials-provider

The credentials provider name. This is the key used to look up credentials in the credentials provider.

Environment variable: QUARKUS_OPENFEATURE_UNLEASH_CREDENTIALS_PROVIDER

string

quarkus.openfeature.unleash.credentials-provider-name

quarkus.openfeature."domain-name".unleash.credentials-provider-name

The credentials provider bean name.

This is a bean name (as in @Named) of a bean that implements CredentialsProvider. It is used to select the credentials provider bean when multiple exist. This is unnecessary when there is only one credentials provider available.

For Vault, the credentials provider bean name is vault-credentials-provider.

Environment variable: QUARKUS_OPENFEATURE_UNLEASH_CREDENTIALS_PROVIDER_NAME

string

quarkus.openfeature.unleash.tls-configuration-name

quarkus.openfeature."domain-name".unleash.tls-configuration-name

TLS configuration name from the Quarkus TLS registry.

Environment variable: QUARKUS_OPENFEATURE_UNLEASH_TLS_CONFIGURATION_NAME

string

quarkus.openfeature.unleash.grace-period

quarkus.openfeature."domain-name".unleash.grace-period

Grace period before transitioning from STALE to ERROR after a connection loss. During this period, the provider continues serving cached flag values while attempting to reconnect. If the connection is restored within the grace period, the provider transitions back to READY without emitting an ERROR event.

Environment variable: QUARKUS_OPENFEATURE_UNLEASH_GRACE_PERIOD

Duration 

1M

quarkus.openfeature.unleash.app-name

quarkus.openfeature."domain-name".unleash.app-name

Application name passed to the Unleash context for evaluation.

Environment variable: QUARKUS_OPENFEATURE_UNLEASH_APP_NAME

string

${quarkus.application.name}

quarkus.openfeature.unleash.environment

quarkus.openfeature."domain-name".unleash.environment

Environment passed to the Unleash context for evaluation.

Environment variable: QUARKUS_OPENFEATURE_UNLEASH_ENVIRONMENT

string
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.