Flipt Provider

The Flipt provider connects to a Flipt instance and evaluates feature flags in-process. Flag definitions are synced from Flipt over HTTP streaming and evaluated locally using a compiled WebAssembly engine, so no network call is made during flag evaluation.

This provider requires Flipt v2. It is not compatible with Flipt v1.

This extension depends on:

Component Version Source

Flipt engine (WASM)

0.3.0

flipt-io/flipt-client-sdks

Installation

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

Configuration

By default, the provider connects to http://localhost:8080. To connect to a different Flipt instance:

quarkus.openfeature.flipt.url=https://flipt.example.com

For named domains:

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

Environments and namespaces

Flipt organizes flags into environments and namespaces. Both default to default and may be reconfigured:

quarkus.openfeature.flipt.environment=production
quarkus.openfeature.flipt.namespace=my-team

See Flipt Concepts for more information about environments and namespaces.

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

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

See the Quarkus TLS registry documentation for all available options.

Authentication

The provider supports authentication using client tokens:

quarkus.openfeature.flipt.auth-type=client-token
quarkus.openfeature.flipt.auth-token=my-secret-token

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

quarkus.openfeature.flipt.auth-type=client-token
quarkus.openfeature.flipt.credentials-provider=flipt-token
quarkus.openfeature.flipt.credentials-provider-name=vault-credentials-provider
Flipt also supports JWT authentication, where tokens are issued by an external identity provider such as Keycloak. This requires dynamic token acquisition and refresh, which is not yet supported. If you need JWT authentication with Flipt, please open an issue.

Git reference

When using Flipt’s git-based storage, you can pin flag evaluation to a specific git reference:

quarkus.openfeature.flipt.reference=main

Evaluation context

The OpenFeature targeting key maps to the Flipt entity ID. All other context attributes are passed through to the evaluation engine as generic context properties.

Dev Services

In dev and test mode, a Flipt container is started automatically if no quarkus.openfeature.flipt.url is configured and Docker is available. The container uses the memory storage backend and flag definitions are imported via the Flipt v2 API on startup. If no flag definition file is found, Flipt starts with an empty configuration.

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

namespace: default
flags:
  - key: welcome-banner
    name: Welcome Banner
    type: BOOLEAN_FLAG_TYPE
    enabled: true
    rollouts:
      - threshold:
          percentage: 100
          value: true
  - key: greeting
    name: Greeting
    type: VARIANT_FLAG_TYPE
    enabled: true
    variants:
      - key: hello
      - key: howdy
    rules:
      - segment: beta-users
        distributions:
          - variant: howdy
            rollout: 100
segments:
  - key: beta-users
    name: Beta Users
    match_type: ANY_MATCH_TYPE
    constraints:
      - type: STRING_COMPARISON_TYPE
        property: userType
        operator: eq
        value: beta

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

quarkus.openfeature.flipt.devservices.path=my-flags.yml

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

Evaluation concurrency

Flag evaluation runs locally in a WebAssembly engine. Each engine instance can only evaluate one flag at a time, so a pool of engine instances is maintained. The pool size controls the maximum number of concurrent flag evaluations; the default is 16. If all instances are in use, an evaluation request waits up to 100 milliseconds for an instance to become available. If no instance is available within that time, the default value is returned. To increase the pool size:

quarkus.openfeature.flipt.wasm-instances=32

Connection lifecycle

The provider maintains a persistent HTTP streaming connection to Flipt. 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 an authentication error (HTTP 401 or 403). The provider will not attempt to reconnect.

The grace period is configurable:

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

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

Flipt server URL.

Environment variable: QUARKUS_OPENFEATURE_FLIPT_URL

string

http://localhost:8080

quarkus.openfeature.flipt.environment

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

Flipt environment.

Environment variable: QUARKUS_OPENFEATURE_FLIPT_ENVIRONMENT

string

default

quarkus.openfeature.flipt.namespace

quarkus.openfeature."domain-name".flipt.namespace

Flipt namespace.

Environment variable: QUARKUS_OPENFEATURE_FLIPT_NAMESPACE

string

default

quarkus.openfeature.flipt.auth-type

quarkus.openfeature."domain-name".flipt.auth-type

Authentication type.

Environment variable: QUARKUS_OPENFEATURE_FLIPT_AUTH_TYPE

none, client-token

none

quarkus.openfeature.flipt.auth-token

quarkus.openfeature."domain-name".flipt.auth-token

Authentication token value. For development and testing only. For production, use a credentials provider instead.

Environment variable: QUARKUS_OPENFEATURE_FLIPT_AUTH_TOKEN

string

quarkus.openfeature.flipt.credentials-provider

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

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

Environment variable: QUARKUS_OPENFEATURE_FLIPT_CREDENTIALS_PROVIDER

string

quarkus.openfeature.flipt.credentials-provider-name

quarkus.openfeature."domain-name".flipt.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_FLIPT_CREDENTIALS_PROVIDER_NAME

string

quarkus.openfeature.flipt.tls-configuration-name

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

TLS configuration name from the Quarkus TLS registry.

Environment variable: QUARKUS_OPENFEATURE_FLIPT_TLS_CONFIGURATION_NAME

string

quarkus.openfeature.flipt.reference

quarkus.openfeature."domain-name".flipt.reference

Git reference for versioned flag state. When set, Flipt returns flags at this specific reference.

Environment variable: QUARKUS_OPENFEATURE_FLIPT_REFERENCE

string

quarkus.openfeature.flipt.grace-period

quarkus.openfeature."domain-name".flipt.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_FLIPT_GRACE_PERIOD

Duration 

1M

quarkus.openfeature.flipt.wasm-instances

quarkus.openfeature."domain-name".flipt.wasm-instances

Number of WASM engine instances in the evaluation pool. Each engine can evaluate one flag at a time, so this controls the maximum concurrency of flag evaluations.

Environment variable: QUARKUS_OPENFEATURE_FLIPT_WASM_INSTANCES

int

16

quarkus.openfeature.flipt.use-quarkus-jackson

quarkus.openfeature."domain-name".flipt.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_FLIPT_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.