Version: v1.46.0

🔧 Configuration

Overview

In this page, you will find all the configuration options available for the relay-proxy.

The GO Feature Flag relay-proxy is highly configurable and can be adapted to your needs. Despite that you can start with a minimum configuration and fine tune it later.

Configuration file

The configuration of the relay proxy is based on a configuration file that you have to provide. The configuration of the relay proxy is based on a configuration file that you have to provide. This is a yaml file and usage is to call it goff-proxy.yaml but you can name it as you will.

You can provide the configuration file with the option --config=/path_to_your_file.yaml when launching the relay proxy.

go-feature-flag --config=/goff-proxy.yaml

info

By default, if you omit the --config option, the relay proxy will look for a configuration file named goff-proxy.yaml in (int this order):

./ (the current directory)
/goff/
/etc/opt/goff/

Configuration Patterns

One set of feature flags

Use one set of feature flags for all your applications. This is the default way of using GO Feature Flag, it requires a minimum configuration and is easy to setup

Get started

Use multiple flag sets

Separate your feature flags into different flag sets to give ownership to different teams or different usage, useful for multi-tenant applications or when you have different teams.

Get started

Getting Started

The minimum configuration to start the relay proxy is to provide where to retrieve your feature flags configuration.

goff-proxy.yaml
retrievers:
  - kind: file
    path: /goff/flags.yaml # Location of your feature flag files

All the other options are optional and can be added to the configuration file to fine-tune the relay proxy.

Environment variables

The primary way to configure the relay proxy is through a configuration file, but you can also use environment variables if you prefer.
You can override file configurations using environment variables.

Here are some things to know when you are using environment variables:

To set an option, the environment variable should have the same name as the configuration option in uppercase.
For example, to set the listen option, you can set the LISTEN environment variable.
```
export LISTEN=8080
```
If you want to set a nested field, you can use _ to separate each field.
For example, to set the retrievers option, you can set the RETRIEVERS environment variable.
```
export RETRIEVER_KIND=github
```
If you want to set an array of string, you can add multiple values separated by a comma.
```
export AUTHORIZEDKEYS_EVALUATION=my-first-key,my-second-key
```
If you are modifying an array of objects, you can use the index to set the value.
```
export RETRIEVERS_0_KIND=github
```

info

If you want to avoid any collision with existing environment variables that are not specifically related to the relay proxy, you can prefix your environment variables.

You can configure the prefix using the envVariablePrefix field in your configuration file.

Configuration Options

`retrievers`

This is the configuration on how to retrieve the configuration of the files.

option name: retrievers
type: []retriever
default: none
mandatory:
You can have multiple retrievers at the same time, check "Using multiple retrievers" to see how it works.
Configuration of a retriever depends on the one you are choosing. Check the list of retrievers and go on the detail page of your choice to configure it.

example goff-proxy.yaml
retrievers:
  - kind: file
    path: /goff/my-flags.yaml
  - kind: s3
    bucket: my-featureflag-bucket
    item: flag/flags.goff.yaml

`startWithRetrieverError`

By default, the relay proxy will crash if it is not able to retrieve the flags from the configuration.

If you don't want your relay proxy to crash, you can set startWithRetrieverError to true. Until the flag is retrievable the relay proxy will only answer with default values.

option name: startWithRetrieverError
type: boolean
default: false
mandatory:

`persistentFlagConfigurationFile`

If set, GO Feature Flag will store the flags configuration in this file to be able to serve the flags even if none of the retrievers is available during starting time.

info

By default, the flag configuration is not persisted and stays on the retriever system. By setting a file here, you ensure that GO Feature Flag will always start with a configuration but which can be out-dated.

option name: persistentFlagConfigurationFile
type: string
default: none
mandatory:
example: /tmp/goff_persist_conf.yaml

`fileFormat`

This is the format of your flag configuration file.

option name: fileFormat
type: string
Acceptable values are :yaml, json, toml.
default: yaml
mandatory:

`pollingInterval`

This is the time interval in millisecond when the relay proxy is reloading the configuration file.

option name: pollingInterval
type: int
default: 60000
The minimum time accepted is 1000 millisecond (1 second).
If you set a negative value, the polling will be disabled.
mandatory:

`enablePollingJitter`

Set to true if you want to avoid having true periodicity when retrieving your flags. It is useful to avoid having spike on your flag configuration storage in case your application is starting multiple instance at the same time.

info

We ensure a deviation that is maximum ±10% of your polling interval.

option name: enablePollingJitter
type: boolean
default: false
mandatory:

`listen`

This is the port used by the relay proxy when starting the HTTP server.

option name: listen
type: int
default: 1031
mandatory:

`monitoringPort`

If set the monitoring endpoints will be served on this specific port.

Check "Use specific port for the monitoring" to have more information.

option name: monitoringPort
type: int
default: none
mandatory:

`logLevel`

The log level to use for the relay proxy.

Check "Logging" to have more information.

option name: logLevel
type: string
default: INFO
Acceptable values are ERROR, WARN, INFO, DEBUG.
mandatory:

`logFormat`

The format to use for structured logs from the relay proxy.

Check "Logging" to have more information.

option name: logFormat
type: string
default: json
Acceptable values are json and logfmt.
mandatory:

`enablePprof`

This param is used to enable pprof endpoints if you wish to enable profiling.

Check "Profiling" to have more information.

option name: enablePprof
type: boolean
default: false
mandatory:

`exporters`

Exporters is the configuration used to define how to export the data from GO Feature Flag.

option name: exporters
type: []exporter
default: none
mandatory:
You can have multiple exporters at the same time, it will export the data to all the exporters you have configured in parallel.
Configuration of an exporter depends on the one you are choosing. Check the list of exporters and go on the detail page of your choice to configure it.

example goff-proxy.yaml
exporters:
  - kind: s3
    bucket: evaluation-data-bucket
  - kind: kafka
    kafka:
      topic: "go-feature-flag-events"

`notifiers`

Notifiers is the configuration on where to notify a flag changes.

option name: notifiers
type: []notifier
default: none
mandatory:
Configuration of a notifier depends on the one you are choosing. Check the list of notifiers and go on the detail page of your choice to configure it.

`disableNotifierOnInit`

If disableNotifierOnInit is set to true, the relay proxy will not call any notifier when the flags are loaded for the 1st time (during initialization). This is useful if you do not want a Slack/Webhook notification saying that the flags have been added every time you start the proxy.

option name: disableNotifierOnInit
type: boolean
default: false
mandatory:

`startAsAwsLambda`

Allow to start the relay-proxy as a AWS Lambda, it means that it will start the server to receive request in the AWS format (see awsLambdaAdapter to set the request/response format you are using). Notifiers is the configuration on where to notify a flag changes.

option name: startAsAwsLambda
type: boolean
default: false
mandatory:

`awsLambdaAdapter`

This parameter allow you to decide which type of AWS lambda handler you want to use.

option name: awsLambdaAdapter
type: string
default: APIGatewayV2
Acceptable values are APIGatewayV2, APIGatewayV1, ALB.
mandatory:
This param is used only if startAsAwsLambda is true.

`awsApiGatewayBasePath`

Specifies the base path prefix for AWS API Gateway deployments when using non-root routes. The relay proxy will strip this base path from incoming requests before processing them. This is useful when deploying behind paths like /api or /dev/feature-flags.

option name: awsApiGatewayBasePath
type: string
default: none
mandatory:
This param is used only if startAsAwsLambda is true.

Example: If set to /api/feature-flags, requests to /api/feature-flags/health will be processed as /health.

`debug`

If debug is set to true, we will set the log level to debug and set some components in debug mode (labstack/echo, pprof etc ...).

option name: debug
type: boolean
default: false
mandatory:

`hideBanner`

hideBanner can be used to hide the startup banner.

option name: hideBanner
type: boolean
default: false
mandatory:

`enableSwagger`

Enables Swagger for testing the APIs directly. If you are enabling Swagger you will have to provide the host configuration.

option name: enableSwagger
type: boolean
default: false
mandatory:
The Swagger UI will be available at http://<host>:<listen>/swagger/.

`host`

host is the DNS you will use to access the relay proxy.

option name: host
type: string
default: localhost
mandatory:
This field is used by Swagger to query the API at the right place.

`disableVersionHeader`

If disableVersionHeader is set to true, the relay proxy will not add the header x-gofeatureflag-version with the GO Feature Flag version in the HTTP response.

option name: disableVersionHeader
type: boolean
default: false
mandatory:

`authorizedKeys`

List of authorized API keys.

info

If you don't set any API keys, the relay proxy will be fully open to all requests

option name: authorizedKeys
type: authorizedKeys
default: none
mandatory:

`evaluationContextEnrichment`

It is a free field that will be merged with the evaluation context sent during the evaluation.

It is useful to add common attributes to all the evaluations, such as a server version, environment, etc. These fields will be included in the custom attributes of the evaluation context.

warning

If in the evaluation context you have a field with the same name, it will be overridden by the evaluationContextEnrichment.

option name: evaluationContextEnrichment
type: object
default: none
mandatory:

`openTelemetryOtlpEndpoint`

Endpoint of your OpenTelemetry OTLP collector, used to send traces.

You will be able to forward those traces to your OpenTelemetry solution directly from the collector.

option name: openTelemetryOtlpEndpoint
type: string
default: none
mandatory:

`flagSets`

Flag sets allow you to organize your feature flags into separate groups, each with its own configuration, API keys, retrievers, exporters, and notifiers.

When you configure flag sets, the relay proxy operates in flag set mode instead of the default single configuration mode. Each flag set requires at least one API key and can have its own retrievers, exporters, and notifiers.

option name: flagSets
type: []flagSet
default: none
mandatory:
If flag sets are configured, the relay proxy will ignore the top-level retrievers, exporters, and notifiers configuration.

example goff-proxy.yaml
listen: 1031
flagSets:
  - name: teamA
    apiKeys:
      - "team-a-api-key"
    retrievers:
      - kind: file
        path: /flags/team-a-flags.yaml
    exporter:
      kind: log

  - name: teamB
    apiKeys:
      - "team-b-api-key"
    retrievers:
      - kind: s3
        bucket: my-feature-flag-bucket
        item: team-b/flags.yaml
    exporters:
      - kind: s3
        bucket: evaluation-data-bucket

`envVariablePrefix`

Prefix for your environment variables.
This useful if you want to avoid any collision with existing environment variables that are not specifically related to the relay proxy.

If you use this option you will have to prefix all your environment variables with the value you set here. For example if you want to override the port of the relay-proxy and the prefix is GOFF_.

export GOFF_LISTEN=8080

option name: envVariablePrefix
type: string
default: empty string
mandatory:

Configuration Types

type `authorizedKeys`

authorizedKeys is an object were it is possible to configure the list of API Keys that are accepted by the relay proxy.

`authorizedKeys.evaluation`

If set, we will check for each evaluation if an authorized key is provided.

Each request will need to provide one of authorized key inside Authorization header with format Bearer <api-key>.

option name: evaluation
type: []string
default: none
mandatory:

`authorizedKeys.admin`

You need to set API keys in this field if you want to access the /v1/admin/* endpoints.

Each request will need to provide one of authorized key inside Authorization header with format Bearer <api-key>.

option name: evaluation
type: []string
default: none
mandatory:
If no api key is configured the endpoint will be unreachable.

Example

goff-proxy.yaml
# ...
authorizedKeys:
  evaluation:
    - "my-first-key"
    - "my-second-key"
  admin:
    - "my-first-admin-key"
    - "my-second-admin-key"

type `retriever`

A retriever is the component in charge of loading your flag configuration from a remote source.

`retriever.kind`

Configuring a retriever always start by setting the kind of retriever you want to use. This is the only common param between all the retrievers.

option name: kind
type: string
default: none
mandatory:

info

To find the kind to use for your retriever and the rest of the options, check the list of retrievers and go on the detail page of your choice to configure it.

Available retrievers:

type `exporter`

An exporter is the component in charge of sending your evaluation data to a remote source.

example goff-proxy.yaml
# ...
exporters:
  - kind: s3
    bucket: evaluation-data-bucket
    flushInterval: 10000

info

Every exporter has its own configuration, check the list of exporters and go on the detail page of your choice to configure it.

Available exporters:

type `flagSet`

A flag set is a collection of flags that are used to evaluate features. It is used to group flags together and to apply the same configuration to them.

example goff-proxy.yaml
flagSets:
  - name: my-flagset
    apiKeys:
      - "my-api-key"
    retrievers:
      - kind: file
        path: /flags/my-flags.yaml
    exporters:
      - kind: s3
        bucket: my-evaluations
    notifiers:
      - kind: slack
        webhookUrl: "https://hooks.slack.com/services/..."

`flagSet.name`

The name of the flag set. This allows you to identify the flag set.

option name: name
type: string
default: auto-generated UUID
mandatory:

`flagSet.apiKeys`

The API keys for the flag set. This will add new API keys to the list of authorized keys for evaluation. This property is mandatory for every flag set, as it is used to filter the flags available.

option name: apiKeys
type: []string
default: none
mandatory:

`flagSet.retrievers`

Configuration for retrieving flag configurations. Supports the same options as the main configuration.

see retrievers

`flagSet.exporters`

Configuration for exporting evaluation data. Supports the same options as the main configuration.

see exporters

`flagSet.notifiers`

Configuration for flag change notifications. Supports the same options as the main configuration.

see notifiers

`flagSet.fileFormat`

The format of the flag configuration files (yaml, json, toml).

see fileFormat

`flagSet.pollingInterval`

The time interval in milliseconds when the relay proxy is reloading the configuration file.

see pollingInterval

`flagSet.startWithRetrieverError`

If true, the flag set will start even if the retriever fails initially.

see startWithRetrieverError

`flagSet.enablePollingJitter`

Set to true if you want to avoid having true periodicity when retrieving your flags.

see enablePollingJitter

`flagSet.disableNotifierOnInit`

Set to true if you do not want to call any notifier when the flags are loaded for the first time.

see disableNotifierOnInit

`flagSet.evaluationContextEnrichment`

Additional context data to merge with all evaluation requests for this flag set.

see evaluationContextEnrichment

`flagSet.persistentFlagConfigurationFile`

File path to persist flag configurations for this flag set.

see persistentFlagConfigurationFile

`flagSet.environment`

Environment identifier for this flag set (e.g., "dev", "staging", "prod").

see environment

type `notifier`

A notifier is the component in charge of sending a notification when a flag changes to a remote system.

example goff-proxy.yaml
# ...
notifiers:
  - kind: discord
    webhookUrl: "https://discord.com/api/webhooks/yyyy/xxxxxxx"
  - kind: slack
    webhookUrl: "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
# ...

info

Every notifier has its own configuration, check the list of notifiers and go on the detail page of your choice to configure it.

Available notifiers:

Use multiple flag sets

Flag sets allow you to organize your feature flags into separate groups, each with its own configuration, API keys, retrievers, exporters, and notifiers. This is particularly useful for:

Team isolation: Different teams can manage their own flags independently
Environment separation: Separate flags for different environments (dev, staging, prod)
Access control: Different API keys for different applications or teams
Independent configurations: Each flag set can have its own retrievers, exporters, and notifiers

How flag sets work

When you configure flag sets, the relay proxy operates in flag set mode instead of the default single configuration mode. In flag set mode:

Each flag set requires at least one API key
API keys are used to route requests to the appropriate flag set
Each flag set can have its own retrievers, exporters, and notifiers
There is no inheritance between flag sets - each is completely independent

Basic flag set configuration

goff-proxy.yaml
listen: 1031
flagSets:
  - name: teamA
    apiKeys:
      - "team-a-api-key-1"
      - "team-a-api-key-2"
    retrievers:
      - kind: file
        path: /path/to/team-a-flags.yaml
    exporter:
      kind: log

  - name: teamB
    apiKeys:
      - "team-b-api-key"
    retrievers:
      - kind: s3
        bucket: my-feature-flag-bucket
        item: team-b/flags.yaml
    exporters:
      - kind: s3
        bucket: evaluation-data-bucket
    notifiers:
      - kind: slack
        webhookUrl: "https://hooks.slack.com/services/..."

Flag set configuration options

warning

If you are using flag sets, all top level configuration options will be ignored.

Each flag set supports all the same configuration options as the main relay proxy configuration. You can find the list of options in the flag set types section.

Using flag sets with API keys

When using flag sets, all evaluation requests must include an API key.
You can do so by adding the API key in the initialization of your providers.

The relay proxy will:

Extract the API key from the Authorization header
Find the flag set associated with that API key
Route the evaluation request to that flag set
Return the evaluation result from that flag set's flags

Example: Multi-team setup

goff-proxy.yaml
listen: 1031
logLevel: INFO

flagSets:
  # Frontend team flags
  - name: frontend
    apiKeys:
      - "frontend-api-key"
    retrievers:
      - kind: file
        path: /flags/frontend-flags.yaml
    exporters:
      - kind: s3
        bucket: frontend-evaluations
    notifiers:
      - kind: slack
        webhookUrl: "https://hooks.slack.com/services/frontend-webhook"

  # Backend team flags
  - name: backend
    apiKeys:
      - "backend-api-key"
    retrievers:
      - kind: github
        repository: my-org/backend-flags
        path: flags.yaml
    exporters:
      - kind: kafka
        topic: backend-evaluations
    notifiers:
      - kind: discord
        webhookUrl: "https://discord.com/api/webhooks/backend-webhook"

  # Mobile team flags
  - name: mobile
    apiKeys:
      - "mobile-api-key"
    retrievers:
      - kind: s3
        bucket: mobile-feature-flags
        item: flags.yaml
    exporters:
      - kind: file
        outputDir: /logs/mobile-evaluations

Client SDKs

Server SDKs

Overview​

Configuration file​

Configuration Patterns​

One set of feature flags

Use multiple flag sets

Getting Started​

Environment variables​

Configuration Options​

retrievers​

startWithRetrieverError​

persistentFlagConfigurationFile​

fileFormat​

pollingInterval​

enablePollingJitter​

listen​

monitoringPort​

logLevel​

logFormat​

enablePprof​

exporters​

notifiers​

disableNotifierOnInit​

startAsAwsLambda​

awsLambdaAdapter​

awsApiGatewayBasePath​

debug​

hideBanner​

enableSwagger​

host​

disableVersionHeader​

authorizedKeys​

evaluationContextEnrichment​

openTelemetryOtlpEndpoint​

flagSets​

envVariablePrefix​

Configuration Types​

type authorizedKeys​

authorizedKeys.evaluation​

authorizedKeys.admin​

Example​

type retriever​

retriever.kind​

type exporter​

type flagSet​

flagSet.name​

flagSet.apiKeys​

flagSet.retrievers​

flagSet.exporters​

flagSet.notifiers​

flagSet.fileFormat​

flagSet.pollingInterval​

flagSet.startWithRetrieverError​

flagSet.enablePollingJitter​

flagSet.disableNotifierOnInit​

flagSet.evaluationContextEnrichment​

flagSet.persistentFlagConfigurationFile​

flagSet.environment​

type notifier​

Use multiple flag sets​

How flag sets work​

Basic flag set configuration​

Flag set configuration options​

Using flag sets with API keys​

Example: Multi-team setup​

Overview

Configuration file

Configuration Patterns

Getting Started

Environment variables

Configuration Options

`retrievers`

`startWithRetrieverError`

`persistentFlagConfigurationFile`

`fileFormat`

`pollingInterval`

`enablePollingJitter`

`listen`

`monitoringPort`

`logLevel`

`logFormat`

`enablePprof`

`exporters`

`notifiers`

`disableNotifierOnInit`

`startAsAwsLambda`

`awsLambdaAdapter`

`awsApiGatewayBasePath`

`debug`

`hideBanner`

`enableSwagger`

`host`

`disableVersionHeader`

`authorizedKeys`

`evaluationContextEnrichment`

`openTelemetryOtlpEndpoint`

`flagSets`

`envVariablePrefix`

Configuration Types

type `authorizedKeys`

`authorizedKeys.evaluation`

`authorizedKeys.admin`

Example

type `retriever`

`retriever.kind`

type `exporter`

type `flagSet`

`flagSet.name`

`flagSet.apiKeys`

`flagSet.retrievers`

`flagSet.exporters`

`flagSet.notifiers`

`flagSet.fileFormat`

`flagSet.pollingInterval`

`flagSet.startWithRetrieverError`

`flagSet.enablePollingJitter`

`flagSet.disableNotifierOnInit`

`flagSet.evaluationContextEnrichment`

`flagSet.persistentFlagConfigurationFile`

`flagSet.environment`

type `notifier`

Use multiple flag sets

How flag sets work

Basic flag set configuration

Flag set configuration options

Using flag sets with API keys

Example: Multi-team setup