Skip to main content
Version: v1.52.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):

  1. ./ (the current directory)
  2. /goff/
  3. /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 logLevel option, you can set the LOGLEVEL environment variable.

    export LOGLEVEL=debug

  • If you want to set a nested field, you can use _ to separate each field.
    For example, to set the server.port option, you can set the SERVER_PORT environment variable.

    export SERVER_PORT=8080

  • 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​

server​

This is the configuration related to the server behavior of the relay proxy. It allows the internal server behaviors such as your execution mode, monitoring port, etc ...

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:

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:
  • When in DEBUG mode, the relay proxy will log the request body and response body, for large payloads this can be a lot of data and can impact the performance this is the reason why we truncate the body if it is larger than 8KiB.

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:

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:

swagger​

Configuration related to the swagger behavior of the relay proxy.

  • option name: swagger
  • type: swagger
  • default: none
  • mandatory:

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:
tip

Runtime updates: API keys can be updated at runtime without restarting the relay proxy.
When the configuration file changes, the relay proxy automatically detects and applies the new API key configuration.
This works in both default mode and flagset mode.

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
server:
  mode: http
  port: 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_SERVER_PORT=8080
  • option name: envVariablePrefix
  • type: string
  • default: empty string
  • mandatory:

enableBulkMetricFlagNames​

Enables per-flag metrics for bulk evaluation endpoints. This adds flag_name labels to the all_flags_evaluations_total_with_flag metric.

info

When enabled, this option provides more granular metrics by including the flag name in the metric labels for bulk evaluation endpoints. This can be useful for monitoring and alerting on specific flags, but may increase the cardinality of your metrics.

  • option name: enableBulkMetricFlagNames
  • type: boolean
  • default: false
  • 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 X-API-Key header.

  • 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 X-API-Key header.

  • 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 serverConfig​

Configuration related to the server behavior of the relay proxy.

server.mode​

The execution mode of the relay proxy, you can choose to start the relay-proxy in different modes depending how you want to call the APIs.

  • option name: mode
  • type: string
  • Acceptable values are :http, lambda, unixsocket.
  • default: http
  • mandatory:
  • http: Start the relay proxy as a HTTP server.
    lambda: Start the relay proxy as an AWS Lambda handler.
    unixsocket: Start the relay proxy and listen on a Unix socket, you have to set the unixSocketPath field to define where the socket file will be created.

server.unixSocketPath​

The path where the Unix socket file will be created when the relay proxy is started in unixsocket mode. If used in combination with server.monitoringPort monitoring endpoints will be served via http on the provided port.

  • option name: unixSocketPath
  • type: string
  • default: none
  • mandatory:
  • This field is mandatory if the mode is set to unixsocket.

server.host​

The server host used by the relay proxy to bind the HTTP server.

  • option name: host
  • type: string
  • default: 0.0.0.0
  • mandatory:
  • This field is used only in http mode.

server.port​

The server port used by the relay proxy to bind the HTTP server.

  • option name: port
  • type: int
  • default: 1031
  • mandatory:
  • This field is used only in http mode.

server.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:
  • This field is used only in http mode.

server.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 server.mode is set to lambda.

server.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 server.mode is set to lambda.

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

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:
warning

If you want to update API keys at runtime without restarting the relay proxy, you must provide a name for your flag set.
Without a name (or using default as the name), a UUID is generated and runtime API key updates will not work.

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.

flagSet.exporters​

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

flagSet.notifiers​

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

flagSet.fileFormat​

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

flagSet.pollingInterval​

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

flagSet.startWithRetrieverError​

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

flagSet.enablePollingJitter​

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

flagSet.disableNotifierOnInit​

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

flagSet.evaluationContextEnrichment​

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

flagSet.persistentFlagConfigurationFile​

File path to persist flag configurations for this flag set.

flagSet.environment​

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

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:

type swagger​

Configuration related to the swagger behavior of the relay proxy.

swagger.enabled​

Enables Swagger for testing the APIs directly. If you are enabling Swagger you will have to provide the swagger.host configuration (default is localhost).

It will start the swagger server on the same port as the relay proxy and you can access it at http://<host>:<server.port>/swagger/.

  • option name: enabled
  • type: boolean
  • default: false
  • mandatory:

swagger.host​

The DNS used by the swagger configuration to access the relay proxy.

  • option name: host
  • type: string
  • default: localhost
  • mandatory:

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
server:
  mode: http
  port: 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:

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

Runtime API key updates​

GO Feature Flag supports updating API keys at runtime without restarting the relay proxy.
See the Runtime configuration updates section for detailed information about runtime updates in flagset mode.

warning

To enable runtime API key updates, your flag sets must have a name configured.
Without a name, a UUID is generated automatically and runtime updates won't work.

flagSets:
  - name: team-a  # ✅ Required for runtime API key updates
    apiKeys:
      - "team-a-api-key"
    # ...

Example: Multi-team setup​

goff-proxy.yaml
server:
  mode: http
  port: 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

Runtime configuration updates​

GO Feature Flag relay proxy supports updating certain configuration options at runtime without requiring a restart.
When the configuration file changes, the relay proxy automatically detects and applies the changes.

Default mode runtime updates​

In default mode (when not using flag sets), you can update the following configuration at runtime:

  • authorizedKeys.evaluation: API keys for evaluation endpoints
  • authorizedKeys.admin: API keys for admin endpoints
  • apiKeys: Deprecated field (still supported for backward compatibility)
warning

In default mode, only API keys can be updated at runtime.
All other configuration changes (retrievers, exporters, notifiers, polling intervals, etc.) are not supported and will be ignored with a warning log message.

Example:

goff-proxy.yaml
# Initial configuration
authorizedKeys:
  evaluation:
    - "key-1"
    - "key-2"
  admin:
    - "admin-key-1"

# Updated configuration (runtime update)
authorizedKeys:
  evaluation:
    - "key-1"
    - "key-2"
    - "key-3"  # ✅ New key added
  admin:
    - "admin-key-1"
    - "admin-key-2"  # ✅ New admin key added

Flagset mode runtime updates​

In flagset mode (when using flag sets), you can update API keys for each flag set at runtime.

Supported operations:

  • Adding new API keys to an existing flag set
  • Removing API keys from a flag set
  • Replacing API keys with new ones
warning

To enable runtime API key updates, your flag sets must have a name configured.
Without a name, a UUID is generated automatically and runtime updates won't work.

flagSets:
  - name: team-a  # ✅ Required for runtime API key updates
    apiKeys:
      - "team-a-api-key"
    # ...

How runtime updates work​

  1. The relay proxy detects the configuration file change
  2. It validates the new configuration (if the configuration is invalid, the relay proxy will not apply the changes)
  3. It updates the internal API key mappings
  4. New requests immediately use the updated routing
info

During the update, there is no downtime. Requests continue to be processed normally, and the new API key configuration takes effect immediately after the update is applied.