flagd Provider

The flagd provider connects to a flagd instance and evaluates feature flags in-process. Flag definitions are synced from flagd over gRPC and evaluated locally, so no network call is made during flag evaluation.

This extension depends on:

Component Version Source

flagd core

2.0.0

open-feature/java-sdk-contrib

Installation

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

Configuration

By default, the provider connects to localhost:8015. To connect to a different flagd instance:

quarkus.openfeature.flagd.url=flagd.example.com:8015

For named domains:

quarkus.openfeature."experimentation".flagd.url=flagd-experiments.example.com:8015

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.flagd.trust-store.pem.certs=ca.pem

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

See the Quarkus TLS registry documentation for all available options.

Authentication

The flagd sync protocol does not define an authentication mechanism. To secure the connection, use TLS and network-level controls.

Offline mode

For testing or development without a running flagd instance, the provider can read flags from a local JSON file:

quarkus.openfeature.flagd.offline-path=/path/to/flags.json

In offline mode, no gRPC connection is made and flag values are static.

Selector

If your flagd instance serves multiple flag sources, you can use a selector to filter to a specific one:

quarkus.openfeature.flagd.selector=flagSetId=my-flags

Provider ID

To identify this client to the flagd server:

quarkus.openfeature.flagd.provider-id=my-service

The server may use this ID to uniquely identify the client, for example in telemetry, and filter flag configurations that it can expose to the client.

Note that this value is sent in the gRPC request for synchronization and is not related to flagd providers.

Evaluation context

The evaluation context is passed directly to the flagd evaluation engine for use in targeting rules.

Dev Services

In dev and test mode, a flagd container is started automatically if no quarkus.openfeature.flagd.url is configured and Docker is available. If no flag definition file is found, flagd starts with an empty configuration.

To provide flag definitions to the dev service, place a flags.json file in src/main/resources:

{
  "flags": {
    "welcome-banner": {
      "state": "ENABLED",
      "variants": {
        "on": true,
        "off": false
      },
      "defaultVariant": "on"
    }
  }
}

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

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

Changes to the flag definition file are detected during live reload and the application is restarted automatically. The flagd container picks up the updated file through its own file watcher.

Connection lifecycle

The provider maintains a persistent gRPC streaming connection to flagd. On connection loss, it automatically attempts to reconnect. 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 a fatal gRPC status (such as PERMISSION_DENIED or UNAUTHENTICATED). The provider will not attempt to reconnect.

The grace period is configurable:

quarkus.openfeature.flagd.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.flagd.url

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

flagd server URL.

Environment variable: QUARKUS_OPENFEATURE_FLAGD_URL

string

localhost:8015

quarkus.openfeature.flagd.tls-configuration-name

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

TLS configuration name from the Quarkus TLS registry.

Environment variable: QUARKUS_OPENFEATURE_FLAGD_TLS_CONFIGURATION_NAME

string

quarkus.openfeature.flagd.stream-deadline

quarkus.openfeature."domain-name".flagd.stream-deadline

Idle timeout for the gRPC streaming connection. If no data is received within this period, the stream is closed and a reconnect is attempted.

Environment variable: QUARKUS_OPENFEATURE_FLAGD_STREAM_DEADLINE

Duration 

10M

quarkus.openfeature.flagd.grace-period

quarkus.openfeature."domain-name".flagd.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_FLAGD_GRACE_PERIOD

Duration 

1M

quarkus.openfeature.flagd.provider-id

quarkus.openfeature."domain-name".flagd.provider-id

Unique identifier for this client, sent to flagd for telemetry, monitoring, and routing purposes.

Environment variable: QUARKUS_OPENFEATURE_FLAGD_PROVIDER_ID

string

quarkus.openfeature.flagd.selector

quarkus.openfeature."domain-name".flagd.selector

Selector for filtering which flag source to sync when flagd serves multiple flag sources.

Environment variable: QUARKUS_OPENFEATURE_FLAGD_SELECTOR

string

quarkus.openfeature.flagd.offline-path

quarkus.openfeature."domain-name".flagd.offline-path

Path to a JSON flag definition file for offline mode. When set, the provider reads flags from this file instead of connecting to a flagd instance.

Environment variable: QUARKUS_OPENFEATURE_FLAGD_OFFLINE_PATH

string

quarkus.openfeature.flagd.use-quarkus-jackson

quarkus.openfeature."domain-name".flagd.use-quarkus-jackson

Whether to use the Quarkus-managed ObjectMapper from the quarkus-jackson extension. When false, the provider creates its own ObjectMapper instance.

Environment variable: QUARKUS_OPENFEATURE_FLAGD_USE_QUARKUS_JACKSON

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.