Flipt server can be configured in two ways.

Configuration precedence is as follows:

  1. Environment Variables
  2. Configuration File

Configuration File

The default way that Flipt is configured is with the use of a configuration file default.yml.

This file is read when Flipt starts up and configures several important properties for the server.

You can generate a default configuration file by running flipt config init. See the CLI documentation for more information.

The server will check in a few different locations for server configuration (in order):

  1. --config flag as an override
  2. {{ USER_CONFIG_DIR }}/flipt/config.yml (the USER_CONFIG_DIR value is based on your architecture and specified in the Go documentation)
  3. /etc/flipt/config/default.yml

We provide both a JSON schema and a Cue schema that you can use to validate your configuration file and it’s properties.

You can edit any of these properties to your liking, and on restart Flipt will pick up the new changes.

Environment Substitution

The configuration file also supports environment variable substitution as of v1.45.0.

This allows you to use environment variables in your configuration file. For example, you can use the FLIPT_CUSTOM_DB_URL environment variable in the configuration file like this:

db:
  url: ${FLIPT_CUSTOM_DB_URL}

This will replace ${FLIPT_CUSTOM_DB_URL} with the value of the FLIPT_CUSTOM_DB_URL environment variable. The format for environment variable substitution is ${ENV_VAR}.

This can be used to provide sensitive information to Flipt without storing it in the configuration file. For example, you can use environment variables to store the database URL, API keys, or other sensitive information without having to conform to the pre-defined Flipt environment variable format.

Remote Configuration

Flipt supports fetching configuration from a remote source. This is useful for managing configuration across multiple instances of Flipt. The remote configuration source can be a URL to a configuration file stored in one of the following object storage services:

  • S3 (e.g.: s3://bucket-name/path/to/config.yml)
  • Azure Blob Storage (e.g.: azblob://container-name/path/to/config.yml)
  • Google Cloud Storage (e.g.: googlecloud://bucket-name/path/to/config.yml)

To load Flipt configuration from a remote source, replace the config.yml file with the URL to the remote configuration file in the --config flag when starting Flipt.

flipt --config s3://bucket-name/path/to/config.yml

For authenticating with the object storage service, you can use the following environment variables depending on the service:

  • AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
  • AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_KEY or AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_CLIENT_SECRET
  • GOOGLE_APPLICATION_CREDENTIALS

These environment variables are used by the underlying object storage client libraries to authenticate with the object storage service and are the same values used in our object storage configuration.

Environment Variables

All options in the configuration file can be overridden using environment variables using the syntax:

FLIPT_<SectionName>_<KeyName>

Environment variables MUST have FLIPT_ prefix and be in UPPER_SNAKE_CASE format.

Using environment variables to override defaults is especially helpful when running with Docker as described in the Docker documentation.

Keys should be uppercase and . should be replaced by _. For example, given these configuration settings:

server:
  grpc_port: 9000

db:
  url: file:/var/opt/flipt/flipt.db

You can override them using:

export FLIPT_SERVER_GRPC_PORT=9001
export FLIPT_DB_URL="postgres://postgres@localhost:5432/flipt?sslmode=disable"

Multiple Values

Some configuration options can have a list of values. For example, the cors.allowed_origins option can have multiple origins.

In this case, you can use a space separated list of values for the environment variable override:

export FLIPT_CORS_ALLOWED_ORIGINS="http://localhost:3000 http://localhost:3001"

Configuration Parameters

PropertyDescriptionDefaultSince
cors.enabledEnable CORS supportfalsev0.7.0
cors.allowed_originsSets Access-Control-Allow-Origin header on server”*” (all domains)v0.7.0
meta.check_for_updatesEnable check for newer versions of Flipt on startuptruev0.17.0
meta.telemetry_enabledEnable anonymous telemetry data (see Telemetry)truev1.8.0
meta.state_directoryDirectory on the host to store local state$HOME/.config/fliptv1.8.0
diagnostics.profiling.enabledEnable profiling endpoints for pproftruev1.29.0

User Interface

PropertyDescriptionDefaultSince
ui.default_themeSets the default UI theme for userssystemv1.27.0
ui.topbar.colorSets the color of the top menu bar (hex value)v1.44.0

Logging

PropertyDescriptionDefaultSince
log.levelLevel at which messages are logged (debug, info, warn, error, fatal, panic)info
log.grpc_levelLevel at which gRPC messages are logged (debug, info, warn, error, fatal, panic)errorv1.12.0
log.fileFile to log to instead of STDOUTv0.10.0
log.encodingEncoding to use for logging (json, console)consolev1.12.0
log.keys.timeStructured logging key used when outputting log timestampTv1.18.1
log.keys.levelStructured logging key used when outputting log levelLv1.18.1
log.keys.messageStructured logging key used when outputting log messageMv1.18.1

Server

PropertyDescriptionDefaultSince
server.protocolhttp or httpshttpv0.8.0
server.hostThe host address on which to serve the Flipt application0.0.0.0
server.http_portThe HTTP port on which to serve the Flipt REST API and UI8080
server.https_portThe HTTPS port on which to serve the Flipt REST API and UI443v0.8.0
server.grpc_portThe port on which to serve the Flipt GRPC server9000
server.grpc_conn_max_idle_timeMaximum amount of time a GRPC connection can be idleunlimitedv1.35.0
server.grpc_conn_max_ageMaximum amount of time a GRPC connection can liveunlimitedv1.35.0
server.grpc_conn_max_age_graceMaximum amount of time a GRPC connection can live for outstanding RPCs after exceeding grpc_conn_max_age unlimitedv1.35.0
server.cert_filePath to the certificate file (if protocol is set to https)v0.8.0
server.cert_keyPath to the certificate key file (if protocol is set to https)v0.8.0

Authentication

PropertyDescriptionDefaultSince
authentication.requiredEnable or disable authentication validation on requestsfalsev1.15.0
authentication.exclude.managementExclude authentication for /api/v1 API prefixfalsev1.24.0
authentication.exclude.metadataExclude authentication for /meta API prefixfalsev1.24.0
authentication.exclude.evaluationExclude authentication for /evaluation/v1 API prefixfalsev1.24.0
authentication.exclude.ofrepExclude authentication for /ofrep API prefixfalsev1.46.0
authentication.session.domainPublic domain on which Flipt instance is hostedv1.17.0
authentication.session.secureConfigures the Secure property on created session cookiesfalsev1.17.0
authentication.session.token_lifetimeConfigures the lifetime of the session token (login duration)24hv1.17.0
authentication.session.state_lifetimeConfigures the lifetime of state parameters during OAuth flow10mv1.17.0
authentication.session.csrf.keySecret credential used to sign CSRF prevention tokensv1.17.0

Authentication Methods: Token

PropertyDescriptionDefaultSince
authentication.methods.token.enabledEnable static token creationfalsev1.15.0
authentication.methods.token.cleanup.intervalInterval between deletion of expired tokens1hv1.16.0
authentication.methods.token.cleanup.grace_periodHow long an expired token can exist until considered deletable30mv1.16.0
authentication.methods.token.bootstrap.tokenThe static token to use for bootstrappingv1.19.0
authentication.methods.token.bootstrap.expirationHow long after creation until the static bootstrap token expiresv1.19.0

Authentication Methods: OIDC

PropertyDescriptionDefaultSince
authentication.methods.oidc.enabledEnable OIDC authenticationfalsev1.17.0
authentication.methods.oidc.cleanup.intervalInterval between deletion of expired tokens1hv1.17.0
authentication.methods.oidc.cleanup.grace_periodHow long an expired token can exist until considered deletable30mv1.17.0
authentication.methods.oidc.providers.[provider].issuer_urlProvider specific OIDC issuer URL (see your providers docs)v1.17.0
authentication.methods.oidc.providers.[provider].client_idProvider specific OIDC client ID (see your providers docs)v1.17.0
authentication.methods.oidc.providers.[provider].client_secretProvider specific OIDC client secret (see your providers docs)v1.17.0
authentication.methods.oidc.providers.[provider].redirect_addressPublic URL on which this Flipt instance is reachablev1.17.0
authentication.methods.oidc.providers.[provider].scopesScopes to request from the providerv1.17.0
authentication.methods.oidc.providers.[provider].use_pkceOption for enabling PKCE for OIDC authentication flowfalsev1.26.0
authentication.methods.oidc.email_matchesList of email addresses (regex) of users allowed to authenticatev1.24.0

Authentication Methods: GitHub

PropertyDescriptionDefaultSince
authentication.methods.github.enabledEnable GitHub authenticationfalsev1.26.0
authentication.methods.github.cleanup.intervalInterval between deletion of expired tokens1hv1.26.0
authentication.methods.github.cleanup.grace_periodHow long an expired token can exist until considered deletable30mv1.26.0
authentication.methods.github.client_idGitHub client IDv1.26.0
authentication.methods.github.client_secretGitHub client secretv1.26.0
authentication.methods.github.redirect_addressPublic URL on which this Flipt instance is reachablev1.26.0
authentication.methods.github.scopesScopes to request from GitHubv1.26.0
authentication.methods.github.allowed_organizationsList of GitHub organizations allowed to authenticatev1.33.0
authentication.methods.github.allowed_teamsMap of GitHub organizations to teams that users must be members ofv1.39.0
authentication.methods.github.server_urlGitHub Server URL (to support GHES)https://github.comv1.43.0
authentication.methods.github.api_urlGitHub API URL (to support GHES)https://api.github.comv1.43.0

Authentication Methods: Kubernetes

PropertyDescriptionDefaultSince
authentication.methods.kubernetes.enabledEnable Kubernetes service account token authenticationfalsev1.19.0
authentication.methods.kubernetes.cleanup.intervalInterval between deletion of expired tokens1hv1.19.0
authentication.methods.kubernetes.cleanup.grace_periodHow long an expired token can exist until considered deletable30mv1.19.0
authentication.methods.kubernetes.discovery_urlKubernetes API server URL for OIDC configuration discoveryhttps://kubernetes.default.svc.cluster.localv1.19.0
authentication.methods.kubernetes.ca_pathKubernetes API CA certification path/var/run/secrets/kubernetes.io/serviceaccount/ca.crtv1.19.0
authentication.methods.kubernetes.service_account_token_pathPath to Flipt service account token/var/run/secrets/kubernetes.io/serviceaccount/tokenv1.19.0

Authentication Methods: JWT

PropertyDescriptionDefaultSince
authentication.methods.jwt.enabledEnable JWT authenticationfalsev1.35.0
authentication.methods.jwt.jwks_urlURL to retrieve JWKS for JWT validationv1.35.0
authentication.methods.jwt.public_key_filePath to public key file for JWT validationv1.35.0
authentication.methods.jwt.validate_claims.issuerThe issuer claim to validate on JWT tokensv1.35.0
authentication.methods.jwt.validate_claims.audiencesThe audience claim (list) to validate on JWT tokensv1.35.0
authentication.methods.jwt.validate_claims.subjectThe subject claim to validate on JWT tokensv1.41.0

Authorization

PropertyDescriptionDefaultSince
authorization.requiredEnable or disable authorization validation on requestsfalsev1.43.0
authorization.backendThe backend to use for authorization policies (local, bundle, object)localv1.45.0

Authorization Backend: Local

PropertyDescriptionDefaultSince
authorization.local.policy.pathPath to the local policy filev1.45.0
authorization.local.policy.poll_intervalInterval to poll the policy file for changes5mv1.45.0
authorization.local.data.pathPath to the local data filev1.45.0
authorization.local.data.poll_intervalInterval to poll the data file for changes30sv1.45.0

Authorization Backend: Bundle

PropertyDescriptionDefaultSince
authorization.bundle.configurationConfiguration for the bundle servicev1.45.0

Authorization Backend: Object

PropertyDescriptionDefaultSince
authorization.object.typeThe type of object store (s3)s3v1.45.0
Authorization Backend Object: S3
PropertyDescriptionDefaultSince
authorization.object.s3.regionThe AWS region to use for S3 object storagev1.45.0
authorization.object.s3.bucketThe S3 bucket to use for object storagev1.45.0
authorization.object.s3.prefixThe S3 prefix to use for object storagev1.45.0
authorization.object.s3.endpointThe S3 endpoint to use for object storagev1.45.0

Database

PropertyDescriptionDefaultSince
db.urlURL to access Flipt databasefile:/(OS Dependent)/flipt/flipt.dbv1.26.0 *OS Dependent
db.protocolProtocol for Flipt database (URL takes precedence)v0.18.0
db.hostHost to access Flipt database (URL takes precedence)v0.18.0
db.portPort to access Flipt database (URL takes precedence)v0.18.0
db.nameName of Flipt database (URL takes precedence)v0.18.0
db.userUser to access Flipt database (URL takes precedence)v0.18.0
db.passwordPassword to access Flipt database (URL takes precedence)v0.18.0
db.max_idle_connThe maximum number of connections in the idle connection pool2v0.17.0
db.max_open_connThe maximum number of open connections to the databaseunlimitedv0.17.0
db.conn_max_lifetimeSets the maximum amount of time in which a connection can be reusedunlimitedv0.17.0
db.prepared_statements_enabledEnable or disable prepared statements for database queriestruev1.23.1

Storage

PropertyDescriptionDefaultSince
storage.typeThe type of storage to use (database, local, git, object)databasev1.25.0
storage.read_onlyEnable read-only mode for storagefalsev1.25.0

Storage Local

PropertyDescriptionDefaultSince
storage.local.pathThe path to the local storage directoryv1.25.0

Storage Git

PropertyDescriptionDefaultSince
storage.git.repositoryThe URL of the git repository to usev1.25.0
storage.git.refThe git ref to usemainv1.25.0
storage.git.ref_typeHow to parse the git ref (static, semver)staticv1.41.0
storage.git.poll_intervalThe interval to poll the git repository and ref for changes30sv1.25.0
storage.git.directoryThe root directory to search in the repositoryv1.40.0
storage.git.authentication.basic.usernameThe username to use for basic authenticationv1.25.0
storage.git.authentication.basic.passwordThe password to use for basic authenticationv1.25.0
storage.git.authentication.token.access_tokenThe access token to use for authenticationv1.25.0
storage.git.authentication.ssh.passwordPassword used to generate the SSH key pairv1.30.0
storage.git.authentication.ssh.private_key_pathPath to private key on the filesystemv1.30.0
storage.git.authentication.ssh.private_key_bytes(Alternative) Raw private key bytesv1.30.0
storage.git.authentication.ssh.insecure_ignore_host_keySkip verifying the known hosts key (avoid in production)falsev1.30.0
storage.git.backend.typeThe backend to use for git repository storage (options: memory, local)memoryv1.43.0
storage.git.backend.pathThe path to the local storage directory for git backendv1.43.0

Storage Object

PropertyDescriptionDefaultSince
storage.object.typeThe type of object storage to use (s3, azblob, googlecloud )s3v1.25.0
Storage Object: S3
PropertyDescriptionDefaultSince
storage.object.s3.regionThe AWS region to use for S3 object storagev1.25.0
storage.object.s3.bucketThe S3 bucket to use for object storagev1.25.0
storage.object.s3.prefixThe S3 prefix to use for object storagev1.25.0
storage.object.s3.endpointThe S3 endpoint to use for object storagev1.25.0
storage.object.s3.poll_intervalThe interval to poll S3 for changes30sv1.25.0
Storage Object: Azure Blob
PropertyDescriptionDefaultSince
storage.object.azblob.endpointThe Azure Blob Store endpoint to use for object storagev1.34.0
storage.object.azblob.containerThe Azure Blob Store container to use for object storagev1.34.0
storage.object.azblob.poll_intervalThe interval to poll Azure Blob Store for changes30sv1.34.0
Storage Object: Google Cloud Storage
PropertyDescriptionDefaultSince
storage.object.googlecloud.bucketThe Google Cloud Storage bucket to use for object storagev1.35.0
storage.object.googlecloud.prefixThe Google Cloud Storage prefix to use for object storagev1.35.0
storage.object.googlecloud.poll_intervalThe interval to poll Google Cloud Storage for changes30sv1.35.0

Storage OCI

PropertyDescriptionDefaultSince
storage.oci.repositoryThe target bundle repository (with optional registry)v1.31.0
storage.oci.authentication.usernameThe username to use for authenticationv1.31.0
storage.oci.authentication.passwordThe password to use for authenticationv1.31.0
storage.oci.bundles_directoryThe directory in which to store local bundles$config/flipt/bundlesv1.31.0
storage.oci.poll_intervalThe interval to poll the registry for changes30sv1.31.0
storage.oci.manifest_verisonThe OCI manifest version to use1.1v1.39.1
storage.oci.authentication.typeThe type to use for authenticationstaticv1.40.0

Cache

PropertyDescriptionDefaultSince
cache.enabledEnable caching of datafalsev1.10.0
cache.ttlTime to live for cached data60sv1.10.0
cache.backendThe backend to use for caching (options: memory, redis)memoryv1.10.0

Cache: Memory

PropertyDescriptionDefaultSince
cache.memory.eviction_intervalInterval at which expired items are evicted from the in-memory cache5mv0.12.0

Cache: Redis

PropertyDescriptionDefaultSince
cache.redis.hostHost to access the Redis databaselocalhostv1.10.0
cache.redis.portPort to access the Redis database6379v1.10.0
cache.redis.dbRedis database to use0v1.10.0
cache.redis.usernameUsername to access the Redis databasev1.40.1
cache.redis.passwordPassword to access the Redis databasev1.10.0
cache.redis.require_tlsRequire TLS to access the Redis databasefalsev1.25.0
cache.redis.pool_sizeMax number of socket connections per CPU10v1.25.0
cache.redis.min_idle_connMinimum number of idle connections in the pool0v1.25.0
cache.redis.conn_max_idle_timeMaximum amount of time a connection can be idle30mv1.25.0
cache.redis.net_timeoutNetwork timeout for Redis connections0v1.25.0
cache.redis.ca_cert_pathPath to custom certificate authority (CA) certificatev1.43.0
cache.redis.ca_cert_bytes(Alternative) Raw certificate authority (CA) certificate bytesv1.43.0
cache.redis.insecure_skip_tlsSkip verifying the server’s certificate chain (avoid in production)falsev1.43.0

Audit Events

PropertyDescriptionDefaultSince
audit.buffer.capacityMax capacity of buffer to send events to sinks2v1.21.0
audit.buffer.flush_periodDuration to wait before sending events to sinks2mv1.21.0
audit.eventsType of events user would like to receive on sinks[”:“]v1.27.0

Audit Events: Log

PropertyDescriptionDefaultSince
audit.sinks.log.enabledEnable log sinkfalsev1.21.0
audit.sinks.log.fileFile path to write audit events to instead of STDOUTv1.21.0
audit.sinks.log.encodingEncoding to use for logging (json, console)inheritv1.44.0

Audit Events: Webhook

PropertyDescriptionDefaultSince
audit.sinks.webhook.enabledEnable webhook sinkfalsev1.27.0
audit.sinks.webhook.urlURL to send audit events tov1.27.0
audit.sinks.webhook.signing_secretSigning secret to use for verification of origin on webhook serverv1.27.0
audit.sinks.webhook.max_backoff_durationMax exponential backoff duration for sending webhook upon failure15sv1.27.0
audit.sinks.webhook.templates[]List of webhook templates for Flipt to send audit events tov1.28.0

Audit Events: Kafka

PropertyDescriptionDefaultSince
audit.sinks.kafka.enabledEnable Kafka sinkfalsev1.46.0
audit.sinks.kafka.topicKafka topic to send audit events tov1.46.0
audit.sinks.kafka.bootstrap_serversKafka bootstrap serversv1.46.0
audit.sinks.kafka.encodingEncoding to use for events in Kafka (protobuf, avro)protobufv1.46.0
audit.sinks.kafka.schema_registry.urlURL to the schema registry for encodingv1.46.0
audit.sinks.kafka.require_tlsRequire TLS to access the Kafka brokerfalsev1.46.0
audit.sinks.kafka.insecure_skip_tlsSkip verifying the server’s certificate chainfalsev1.46.0
audit.sinks.kafka.authentication.usernameSASL/SCRAM username to access the Kafka brokerv1.46.0
audit.sinks.kafka.authentication.passwordSASL/SCRAM password to access the Kafka brokerv1.46.0

Analytics

PropertyDescriptionDefaultSince
analytics.buffer.flush_periodDuration to wait before sending events to sinks10sv1.37.0

Analytics: Clickhouse

PropertyDescriptionDefaultSince
analytics.storage.clickhouse.enabledEnable Clickhouse supportfalsev1.37.0
analytics.storage.clickhouse.urlURL to connect to clickhouse serverv1.37.0

Analytics: Prometheus

PropertyDescriptionDefaultSince
analytics.storage.prometheus.enabledEnable Prometheus supportfalsev1.52.0
analytics.storage.prometheus.urlURL to connect to prometheus serverv1.52.0
analytics.storage.prometheus.headersAdditional headers to send with Prometheus requests (map[string]string)v1.52.1

Metrics

PropertyDescriptionDefaultSince
metrics.enabledEnable metrics supporttruev1.41.0
metrics.exporterThe exporter to use (prometheus, otlp)prometheusv1.41.0

Metrics: OTLP

PropertyDescriptionDefaultSince
metrics.otlp.endpointThe OTLP receiver address (supports: grpc, http, https)grpc://localhost:4317v1.41.0
metrics.otlp.headersAdditional headers to send with OTLP requests (map[string]string)v1.41.0

Tracing

PropertyDescriptionDefaultSince
tracing.enabledEnable tracing supportfalsev1.18.2
tracing.exporterThe exporter to use (jaeger, zipkin, otlp)jaegerv1.18.2
tracing.sampling_ratioThe sampling ratio to use for exporting spans1.0v1.41.0
tracing.propagatorsThe propagators to use for tracing (tracecontext, b3, jaeger, etc)tracecontext, baggagev1.41.0

Tracing: Jaeger

PropertyDescriptionDefaultSince
tracing.jaeger.hostThe UDP host destination to report spanslocalhostv0.17.0
tracing.jaeger.portThe UDP port destination to report spans6831v0.17.0

Tracing: Zipkin

PropertyDescriptionDefaultSince
tracing.zipkin.endpointThe Zipkin API endpoint to report spanshttp://localhost:9411/api/v2/spansv1.18.2

Tracing: OTLP

PropertyDescriptionDefaultSince
tracing.otlp.endpointThe OTLP receiver address (supports: grpc, http, https)grpc://localhost:4317v1.18.2
tracing.otlp.headersAdditional headers to send with OTLP requests (map[string]string)v1.28.0

Deprecations

From time to time configuration options will need to be deprecated and eventually removed. Deprecated configuration options will be removed after ~6 months from the time they were deprecated.

All deprecated configuration options will be removed from the documentation, however, they will still work as expected until they’re removed. A warning will be logged in the Flipt logs when a deprecated configuration option is used.

All deprecated options are listed in the DEPRECATIONS file in the Flipt repository as well as the CHANGELOG.

Experiments

From time to time, Flipt may introduce new features that are not considered fully supported. These features are considered experimental and may change or be removed in future releases.

We put experimental features behind a configuration setting that can be enabled in the configuration file. To enable experimental features, set the experimental.{feature}.enabled configuration option to true.

experimental:
  foo:
    enabled: true

See the Experimental documentation for more information on the current experimental features and how to enable them.