Overview

This document describes how to configure the Flipt server.

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 as of v1.28.0. 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.

Remote Configuration

As of v1.41.0, 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 (eg: s3://bucket-name/path/to/config.yml)
• Azure Blob Storage (eg: azblob://container-name/path/to/config.yml)
• Google Cloud Storage (eg: 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
• 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 Installation 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

Property	Description	Default	Since
ui.default_theme	Sets the default UI theme for users	system	v1.27.0
cors.enabled	Enable CORS support	false	v0.7.0
cors.allowed_origins	Sets Access-Control-Allow-Origin header on server	”*” (all domains)	v0.7.0
meta.check_for_updates	Enable check for newer versions of Flipt on startup	true	v0.17.0
meta.telemetry_enabled	Enable anonymous telemetry data (see Telemetry)	true	v1.8.0
meta.state_directory	Directory on the host to store local state	$HOME/.config/flipt	v1.8.0
diagnostics.profiling.enabled	Enable profiling endpoints for pprof	true	v1.29.0

Logging

Property	Description	Default	Since
log.level	Level at which messages are logged (debug, info, warn, error, fatal, panic)	info
log.grpc_level	Level at which gRPC messages are logged (debug, info, warn, error, fatal, panic)	error	v1.12.0
log.file	File to log to instead of STDOUT		v0.10.0
log.encoding	Encoding to use for logging (json, console)	console	v1.12.0
log.keys.time	Structured logging key used when outputting log timestamp	T	v1.18.1
log.keys.level	Structured logging key used when outputting log level	L	v1.18.1
log.keys.message	Structured logging key used when outputting log message	M	v1.18.1

Server

Property	Description	Default	Since
server.protocol	http or https	http	v0.8.0
server.host	The host address on which to serve the Flipt application	0.0.0.0
server.http_port	The HTTP port on which to serve the Flipt REST API and UI	8080
server.https_port	The HTTPS port on which to serve the Flipt REST API and UI	443	v0.8.0
server.grpc_port	The port on which to serve the Flipt GRPC server	9000
server.grpc_conn_max_idle_time	Maximum amount of time a GRPC connection can be idle	unlimited	v1.35.0
server.grpc_conn_max_age	Maximum amount of time a GRPC connection can live	unlimited	v1.35.0
server.grpc_conn_max_age_grace	Maximum amount of time a GRPC connection can live for outstanding RPCs after exceeding grpc_conn_max_age	unlimited	v1.35.0
server.cert_file	Path to the certificate file (if protocol is set to https)		v0.8.0
server.cert_key	Path to the certificate key file (if protocol is set to https)		v0.8.0

Authentication

Property	Description	Default	Since
authentication.required	Enable or disable authentication validation on requests	false	v1.15.0
authentication.exclude.management	Exclude authentication for /api/v1 API prefix	false	v1.24.0
authentication.exclude.metadata	Exclude authentication for /meta API prefix	false	v1.24.0
authentication.exclude.evaluation	Exclude authentication for /evaluation/v1 API prefix	false	v1.24.0
authentication.session.domain	Public domain on which Flipt instance is hosted		v1.17.0
authentication.session.secure	Configures the Secure property on created session cookies	false	v1.17.0
authentication.session.token_lifetime	Configures the lifetime of the session token (login duration)	24h	v1.17.0
authentication.session.state_lifetime	Configures the lifetime of state parameters during OAuth flow	10m	v1.17.0
authentication.session.csrf.key	Secret credential used to sign CSRF prevention tokens		v1.17.0

Authentication Methods: Token

Property	Description	Default	Since
authentication.methods.token.enabled	Enable static token creation	false	v1.15.0
authentication.methods.token.cleanup.interval	Interval between deletion of expired tokens	1h	v1.16.0
authentication.methods.token.cleanup.grace_period	How long an expired token can exist until considered deletable	30m	v1.16.0
authentication.methods.token.bootstrap.token	The static token to use for bootstrapping		v1.19.0
authentication.methods.token.bootstrap.expiration	How long after creation until the static bootstrap token expires		v1.19.0

Authentication Methods: OIDC

Property	Description	Default	Since
authentication.methods.oidc.enabled	Enable OIDC authentication	false	v1.17.0
authentication.methods.oidc.cleanup.interval	Interval between deletion of expired tokens	1h	v1.17.0
authentication.methods.oidc.cleanup.grace_period	How long an expired token can exist until considered deletable	30m	v1.17.0
authentication.methods.oidc.providers.[provider].issuer_url	Provider specific OIDC issuer URL (see your providers docs)		v1.17.0
authentication.methods.oidc.providers.[provider].client_id	Provider specific OIDC client ID (see your providers docs)		v1.17.0
authentication.methods.oidc.providers.[provider].client_secret	Provider specific OIDC client secret (see your providers docs)		v1.17.0
authentication.methods.oidc.providers.[provider].redirect_address	Public URL on which this Flipt instance is reachable		v1.17.0
authentication.methods.oidc.providers.[provider].scopes	Scopes to request from the provider		v1.17.0
authentication.methods.oidc.providers.[provider].use_pkce	Option for enabling PKCE for OIDC authentication flow	false	v1.26.0
authentication.methods.oidc.email_matches	List of email addresses (regex) of users allowed to authenticate		v1.24.0

Authentication Methods: GitHub

Property	Description	Default	Since
authentication.methods.github.enabled	Enable GitHub authentication	false	v1.26.0
authentication.methods.github.cleanup.interval	Interval between deletion of expired tokens	1h	v1.26.0
authentication.methods.github.cleanup.grace_period	How long an expired token can exist until considered deletable	30m	v1.26.0
authentication.methods.github.client_id	GitHub client ID		v1.26.0
authentication.methods.github.client_secret	GitHub client secret		v1.26.0
authentication.methods.github.redirect_address	Public URL on which this Flipt instance is reachable		v1.26.0
authentication.methods.github.scopes	Scopes to request from GitHub		v1.26.0
authentication.methods.github.allowed_organizations	List of GitHub organizations allowed to authenticate		v1.33.0
authentication.methods.github.allowed_teams	Map of GitHub organizations to teams that users must be members of		v1.39.0

Authentication Methods: Kubernetes

Property	Description	Default	Since
authentication.methods.kubernetes.enabled	Enable Kubernetes service account token authentication	false	v1.19.0
authentication.methods.kubernetes.cleanup.interval	Interval between deletion of expired tokens	1h	v1.19.0
authentication.methods.kubernetes.cleanup.grace_period	How long an expired token can exist until considered deletable	30m	v1.19.0
authentication.methods.kubernetes.discovery_url	Kubernetes API server URL for OIDC configuration discovery	https://kubernetes.default.svc.cluster.local	v1.19.0
authentication.methods.kubernetes.ca_path	Kubernetes API CA certification path	/var/run/secrets/kubernetes.io/serviceaccount/ca.crt	v1.19.0
authentication.methods.kubernetes.service_account_token_path	Path to Flipt service account token	/var/run/secrets/kubernetes.io/serviceaccount/token	v1.19.0

Authentication Methods: JWT

Property	Description	Default	Since
authentication.methods.jwt.enabled	Enable JWT authentication	false	v1.35.0
authentication.methods.jwt.jwks_url	URL to retrieve JWKS for JWT validation		v1.35.0
authentication.methods.jwt.public_key_file	Path to public key file for JWT validation		v1.35.0
authentication.methods.jwt.validate_claims.issuer	The issuer claim to validate on JWT tokens		v1.35.0
authentication.methods.jwt.validate_claims.audiences	The audience claim (list) to validate on JWT tokens		v1.35.0

Database

Property	Description	Default	Since
db.url	URL to access Flipt database	file:/(OS Dependent)/flipt/flipt.db	v1.26.0 *OS Dependent
db.protocol	Protocol for Flipt database (URL takes precedence)		v0.18.0
db.host	Host to access Flipt database (URL takes precedence)		v0.18.0
db.port	Port to access Flipt database (URL takes precedence)		v0.18.0
db.name	Name of Flipt database (URL takes precedence)		v0.18.0
db.user	User to access Flipt database (URL takes precedence)		v0.18.0
db.password	Password to access Flipt database (URL takes precedence)		v0.18.0
db.max_idle_conn	The maximum number of connections in the idle connection pool	2	v0.17.0
db.max_open_conn	The maximum number of open connections to the database	unlimited	v0.17.0
db.conn_max_lifetime	Sets the maximum amount of time in which a connection can be reused	unlimited	v0.17.0
db.prepared_statements_enabled	Enable or disable prepared statements for database queries	true	v1.23.1

Storage

Property	Description	Default	Since
storage.type	The type of storage to use (database, local, git, object)	database	v1.25.0
storage.read_only	Enable read-only mode for storage	false	v1.25.0

Storage Local

Property	Description	Default	Since
storage.local.path	The path to the local storage directory		v1.25.0

Storage Git

Property	Description	Default	Since
storage.git.repository	The URL of the git repository to use		v1.25.0
storage.git.ref	The git ref to use	main	v1.25.0
storage.git.poll_interval	The interval to poll the git repository and ref for changes	30s	v1.25.0
storage.git.authentication.basic.username	The username to use for basic authentication		v1.25.0
storage.git.authentication.basic.password	The password to use for basic authentication		v1.25.0
storage.git.authentication.token	The access token to use for authentication		v1.25.0
storage.git.authentication.ssh.password	Password used to generate the SSH key pair		v1.30.0
storage.git.authentication.ssh.private_key_path	Path to private key on the filesystem		v1.30.0
storage.git.authentication.ssh.private_key_bytes	(Alternative) Raw private key bytes		v1.30.0
storage.git.authentication.ssh.insecure_ignore_host_key	Skip verifying the known hosts key (avoid in production)	false	v1.30.0

Storage Object

Property	Description	Default	Since
storage.object.type	The type of object storage to use (s3)	s3	v1.25.0

Storage Object: S3

Property	Description	Default	Since
storage.object.s3.region	The AWS region to use for S3 object storage		v1.25.0
storage.object.s3.bucket	The S3 bucket to use for object storage		v1.25.0
storage.object.s3.prefix	The S3 prefix to use for object storage		v1.25.0
storage.object.s3.endpoint	The S3 endpoint to use for object storage		v1.25.0
storage.object.s3.poll_interval	The interval to poll S3 for changes	30s	v1.25.0

Storage OCI

Property	Description	Default	Since
storage.oci.repository	The target bundle repository (with optional registry)		v1.31.0
storage.oci.authentication.username	The username to use for authentication		v1.31.0
storage.oci.authentication.password	The password to use for authentication		v1.31.0
storage.oci.bundles_directory	The directory in which to store local bundles	$config/flipt/bundles	v1.31.0
storage.oci.poll_interval	The interval to poll the registry for changes	30s	v1.31.0
storage.oci.manifest_verison	The OCI manifest version to use	1.1	v1.39.1
storage.oci.authentication.type	The type to use for authentication	static	v1.40.0

Cache

Property	Description	Default	Since
cache.enabled	Enable caching of data	false	v1.10.0
cache.ttl	Time to live for cached data	60s	v1.10.0
cache.backend	The backend to use for caching (options: memory, redis)	memory	v1.10.0

Cache: Memory

Property	Description	Default	Since
cache.memory.eviction_interval	Interval at which expired items are evicted from the in-memory cache	5m	v0.12.0

Cache: Redis

Property	Description	Default	Since
cache.redis.host	Host to access the Redis database	localhost	v1.10.0
cache.redis.port	Port to access the Redis database	6379	v1.10.0
cache.redis.db	Redis database to use	0	v1.10.0
cache.redis.username	Username to access the Redis database		v1.40.1
cache.redis.password	Password to access the Redis database		v1.10.0
cache.redis.require_tls	Require TLS to access the Redis database	false	v1.25.0
cache.redis.pool_size	Max number of socket connections per CPU	10	v1.25.0
cache.redis.min_idle_conn	Minimum number of idle connections in the pool	0	v1.25.0
cache.redis.conn_max_idle_time	Maximum amount of time a connection can be idle	30m	v1.25.0
cache.redis.net_timeout	Network timeout for Redis connections	0	v1.25.0

Audit Events

Property	Description	Default	Since
audit.buffer.capacity	Max capacity of buffer to send events to sinks	2	v1.21.0
audit.buffer.flush_period	Duration to wait before sending events to sinks	2m	v1.21.0
audit.events	Type of events user would like to receive on sinks	[”:“]	v1.27.0

Audit Events: Log File

Property	Description	Default	Since
audit.sinks.log.enabled	Enable log file sink	false	v1.21.0
audit.sinks.log.file	File path to write audit events to. Required if log file sink is enabled		v1.21.0

Audit Events: Webhook

Property	Description	Default	Since
audit.sinks.webhook.enabled	Enable webhook sink	false	v1.27.0
audit.sinks.webhook.url	URL to send audit events to		v1.27.0
audit.sinks.webhook.signing_secret	Signing secret to use for verification of origin on webhook server		v1.27.0
audit.sinks.webhook.max_backoff_duration	Max exponential backoff duration for sending webhook upon failure	15s	v1.27.0
audit.sinks.webhook.templates[]	List of webhook templates for Flipt to send audit events to		v1.28.0

Analytics

Property	Description	Default	Since
analytics.buffer.flush_period	Duration to wait before sending events to sinks	10s	v1.37.0

Analytics: Clickhouse

Property	Description	Default	Since
analytics.storage.clickhouse.enabled	Enable Clickhouse support	false	v1.37.0
analytics.storage.clickhouse.url	URL to connect to clickhouse server		v1.37.0

Tracing

Property	Description	Default	Since
tracing.enabled	Enable tracing support	false	v1.18.2
tracing.exporter	The exporter to use (jaeger, zipkin, otlp)	jaeger	v1.18.2

Tracing: Jaeger

Property	Description	Default	Since
tracing.jaeger.host	The UDP host destination to report spans	localhost	v0.17.0
tracing.jaeger.port	The UDP port destination to report spans	6831	v0.17.0

Tracing: Zipkin

Property	Description	Default	Since
tracing.zipkin.endpoint	The Zipkin API endpoint to report spans	http://localhost:9411/api/v2/spans	v1.18.2

Tracing: OTLP

Property	Description	Default	Since
tracing.otlp.endpoint	The OTLP receiver address (supports: grpc, http, https)	grpc://localhost:4317	v1.18.2
tracing.otlp.headers	Additional 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.