Flipt server can be configured in two ways.
Configuration precedence is as follows:
- Environment Variables
- 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):
--config flag as an override{{ USER_CONFIG_DIR }}/flipt/config.yml (the USER_CONFIG_DIR value is based on your architecture and specified in the Go documentation)/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 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
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.
