Configure the relay proxy

Getting Started

The configuration of the relay proxy is based on a configuration file that you have to provide.

The only mandatory information you need to start the server is to provide where to retrieve your feature flags configuration.

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

Global configuration

Use environment variables.

You can override file configurations using environment variables.

Note that all environment variables should be uppercase. If you want to replace a nested fields, please use _ to separate each field (ex: RETRIEVER_KIND).

In case of an array of string, you can add multiple values separated by a comma ( ex: AUTHORIZEDKEYS_EVALUATION=my-first-key,my-second-key).

Field name	Type	Default	Description
retriever	retriever	none	(mandatory) This is the configuration on how to retrieve the configuration of the files. Note: this field is mandatory only if retrievers is not set.
retrievers	[]retriever	none	(mandatory) Exactly the same things as retriever except that you can provide more than 1 retriever. Note: this field is mandatory only if retriever is not set.
listen	int	1031	This is the port used by the relay proxy when starting the HTTP server.
pollingInterval	int	60000	This is the time interval in millisecond when the relay proxy is reloading the configuration file. The minimum time accepted is 1000 millisecond.
enablePollingJitter	boolean	false	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. We ensure a deviation that is maximum ±10% of your polling interval. Default: false
DisableNotifierOnInit	boolean	false	If true, the relay proxy will not call any notifier when the flags are loaded 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. Default: false
hideBanner	boolean	false	Should we display the beautiful go-feature-flag banner when starting the relay proxy
enableSwagger	boolean	false	Enables Swagger for testing the APIs directly. If you are enabling Swagger you will have to provide the host configuration and the Swagger UI will be available at http://<host>:<listen>/swagger/.
host	string	localhost	This is the DNS you will use to access the relay proxy. This field is used by Swagger to query the API at the right place.
restApiTimeout	int	5000	Timeout in milliseconds for API calls.
logLevel	string	info	The log level to use for the relay proxy. Available values are ERROR, WARN, INFO, DEBUG.
fileFormat	string	yaml	This is the format of your go-feature-flag configuration file. Acceptable values are yaml, json, toml.
startWithRetrieverError	boolean	false	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.
exporter	exporter	none	Exporter is the configuration used to export data.
notifier	notifier	none	Notifiers is the configuration on where to notify a flag change.
authorizedKeys	authorizedKeys	none	List of authorized API keys.
evaluationContextEnrichment	object	none	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. If in the evaluation context you have a field with the same name, it will be override by the evaluationContextEnrichment.
openTelemetryOtlpEndpoint	string	none	Endpoint of your OpenTelemetry OTLP collector, used to send traces to it and you will be able to forward them to your OpenTelemetry solution with the appropriate provider.
kafka	object	none	Settings for the Kafka exporter. Mandatory when using the 'kafka' exporter type, and ignored otherwise.
projectID	string	none	ID of GCP project. Mandatory when using PubSub exporter.
topic	string	none	Name of PubSub topic on which messages will be published. Mandatory when using PubSub exporter.
persistentFlagConfigurationFile	string	none	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. 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. (example: /tmp/goff_persist_conf.yaml)
startAsAwsLambda	boolean	false	If set GO Feature Flag 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).
awsLambdaAdapter	string	APIGatewayV2	This param is used only if startAsAwsLambda is true. This parameter allow you to decide which type of AWS lambda handler you wan to use. Accepted values are APIGatewayV2, APIGatewayV1, ALB.

type authorizedKeys

To be able to control who can access your relay proxy, you can set a list of authorized keys.

Field name	Type	Default	Description
evaluation	[]string	none	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>. Note: there will be no authorization when this config is not set.
admin	[]string	none	You need to set API keys in this field if you want to access the /v1/admin/* endpoints. If no api key is configured the endpoint will be unreachable. Each request will need to provide one of authorized key inside Authorization header with format Bearer <api-key>.

type retriever

go-feature-flag supports different kind of retriever types such as S3, Google store, etc ... In this section we will present all the available retriever configurations available.

S3

If you are using the S3 provider, the easiest way to provide credentials is to set environment variables. It will be used by GO Feature Flag to identify to your S3 bucket.

export AWS_SECRET_ACCESS_KEY=xxxx
export AWS_ACCESS_KEY_ID=xxx
export AWS_DEFAULT_REGION=eu-west-1

Field name	Type	Default	Description
kind	string	none	(mandatory) Value should be s3. This field is mandatory and describes which retriever you are using.
bucket	string	none	(mandatory) This is the name of your S3 bucket (ex: my-featureflag-bucket).
item	string	none	(mandatory) Path to the file inside the bucket (ex: config/flag/my-flags.yaml).

GitHub

tip

GitHub has rate limits, be sure to correctly set your PollingInterval to avoid reaching the limit.

If the rate limit is reached, the retriever will return an error and will stop polling until GitHub allows it again.

Field name	Type	Default	Description
kind	string	none	(mandatory) Value should be github. This field is mandatory and describes which retriever you are using.
repositorySlug	string	none	(mandatory) The repository slug of the GitHub repository where your file is located (ex: thomaspoignant/go-feature-flag).
path	string	none	(mandatory) Path to the file inside the repository (ex: config/flag/my-flags.yaml).
branch	string	main	The branch we should check in the repository.
token	string	none	Github token used to access a private repository, you need the repo permission (how to create a GitHub token).
timeout	string	10000	Timeout in millisecond used when calling GitHub.

GitLab

Field name	Type	Default	Description
kind	string	none	(mandatory) Value should be gitlab. This field is mandatory and describes which retriever you are using.
repositorySlug	string	none	(mandatory) The repository slug of the GitLab repository where your file is located (ex: thomaspoignant/go-feature-flag).
path	string	none	(mandatory) Path to the file inside the repository (ex: config/flag/my-flags.yaml).
baseUrl	string	https://gitlab.com	The base URL of your GitLab instance.
branch	string	main	The branch we should check in the repository.
token	string	none	GitLab personal access token used to access a private repository (Create a personal access token).
timeout	string	10000	Timeout in millisecond used when calling GitLab.

File

Field name	Type	Default	Description
kind	string	none	(mandatory) Value should be file. This field is mandatory and describes which retriever you are using.
path	string	none	(mandatory) Path to the file in your local computer (ex: /goff/my-flags.yaml).

HTTP

Field name	Type	Default	Description
kind	string	none	(mandatory) Value should be http. This field is mandatory and describes which retriever you are using.
url	string	none	(mandatory) Location to retrieve the file.
method	string	GET	The HTTP Method you are using to call the HTTP endpoint.
body	string	none	The HTTP Body you are using to call the HTTP endpoint.
headers	map[string][]string	none	The HTTP headers used when calling the HTTP endpoint (useful for authorization).
timeout	string	10000	Timeout in millisecond when calling the HTTP endpoint.

Google Storage

Field name	Type	Default	Description
kind	string	none	(mandatory) Value should be googleStorage. This field is mandatory and describes which retriever you are using.
bucket	string	none	(mandatory) This is the name of your Google Storage bucket (ex: my-featureflag-bucket).
object	string	none	(mandatory) Path to the file inside the bucket (ex: config/flag/my-flags.yaml).

Kubernetes ConfigMap

Note that relay proxy is only supporting this while running inside the kubernetes cluster.

Field name	Type	Default	Description
kind	string	none	(mandatory) Value should be configmap. This field is mandatory and describes which retriever you are using.
namespace	string	none	(mandatory) This is the name of the namespace where your configmap is located (ex: default).
configmap	string	none	(mandatory) Name of the configmap we should read (ex: feature-flag).
key	string	none	(mandatory) Name of the key in the configmap which contains the flag.

MongoDB

To understand the format in which a flag needs to be configured in MongoDB, check the example available.

Field name	Type	Default	Description
kind	string	none	(mandatory) Value should be mongodb. This field is mandatory and describes which retriever you are using.
uri	string	none	(mandatory) This is the MongoDB URI used in order to connect to the MongoDB instance.
database	string	none	(mandatory) Name of the database where flags are stored.
collection	string	none	(mandatory) Name of the collection where flags are stored.

Redis

To understand the format in which a flag needs to be configured in Redis, check the doc available.

Field name	Type	Default	Description
kind	string	none	(mandatory) Value should be redis. This field is mandatory and describes which retriever you are using.
options	object	none	(mandatory) Options used to connect to your redis instance. All the options from the go-redis SDK are available (check redis.Options)
prefix	string	none	Prefix used before your flag name in the Redis DB.

type exporter

Webhook

Field name	Type	Default	Description
kind	string	none	(mandatory) Value should be webhook. This field is mandatory and describes which retriever you are using.
endpointUrl	string	none	(mandatory) EndpointURL of your webhook.
flushInterval	int	60000	The interval in millisecond between 2 calls to the webhook (if the maxEventInMemory is reached before the flushInterval we will call the webhook before).
maxEventInMemory	int	100000	If we hit that limit we will call the webhook.
secret	string	none	Secret used to sign your request body and fill the X-Hub-Signature-256 header. See signature section for more details.
meta	map[string]string	none	Add all the information you want to see in your request.
headers	map[string][]string	none	Add all the headers you want to add while calling the endpoint

File

Field name	Type	Default	Description
kind	string	none	(mandatory) Value should be file. This field is mandatory and describes which retriever you are using.
outputDir	string	none	(mandatory) OutputDir is the location of the directory where to store the exported files.
flushInterval	int	60000	The interval in millisecond between 2 calls to the webhook (if the maxEventInMemory is reached before the flushInterval we will call the webhook before).
maxEventInMemory	int	100000	If we hit that limit we will call the webhook.
format	string	JSON	Format is the output format you want in your exported file. Available format: JSON, CSV, Parquet.
filename	string	flag-variation-{{ .Hostname}}-{{ .Timestamp}}.{{ .Format}}	You can use a templated config to define the name of your exported files. Available replacements are {{ .Hostname}}, {{ .Timestamp}} and {{ .Format}
csvTemplate	string	{{ .Kind}};{{ .ContextKind}};{{ .UserKey}};{{ .CreationDate}};{{ .Key}};{{ .Variation}};{{ .Value}};{{ .Default}};{{ .Source}}\n	CsvTemplate is used if your output format is CSV. This field will be ignored if you are using format other than CSV. You can decide which fields you want in your CSV line with a go-template syntax, please check internal/exporter/feature_event.go to see the fields available.
parquetCompressionCodec	string	SNAPPY	ParquetCompressionCodec is the parquet compression codec for better space efficiency. Available options

Log

Field name	Type	Default	Description
kind	string	none	(mandatory) Value should be log. This field is mandatory and describes which retriever you are using.
flushInterval	int	60000	The interval in millisecond between 2 calls to the webhook (if the maxEventInMemory is reached before the flushInterval, we will call the webhook before).
maxEventInMemory	int	100000	If we hit that limit we will call the webhook.
logFormat	string	[{{ .FormattedDate}}] user="{{ .UserKey}}", flag="{{ .Key}}", value="{{ .Value}}"	LogFormat is the template configuration of the output format of your log. You can use all the key from the exporter.FeatureEvent + a key called FormattedDate that represent the date with the RFC 3339 Format.

S3

Field name	Type	Default	Description
kind	string	none	(mandatory) Value should be s3. This field is mandatory and describes which retriever you are using.
bucket	string	none	(mandatory) Name of your S3 Bucket.
flushInterval	int	60000	The interval in millisecond between 2 calls to the webhook (if the maxEventInMemory is reached before the flushInterval we will call the webhook before).
maxEventInMemory	int	100000	If we hit that limit we will call the webhook.
format	string	JSON	Format is the output format you want in your exported file. Available format: JSON, CSV, Parquet.
filename	string	flag-variation-{{ .Hostname}}-{{ .Timestamp}}.{{ .Format}}	You can use a config template to define the name of your exported files. Available replacements are {{ .Hostname}}, {{ .Timestamp}} and {{ .Format}
csvTemplate	string	{{ .Kind}};{{ .ContextKind}};{{ .UserKey}};{{ .CreationDate}};{{ .Key}};{{ .Variation}};{{ .Value}};{{ .Default}};{{ .Source}}\n	CsvTemplate is used if your output format is CSV. This field will be ignored if you are using format other than CSV. You can decide which fields you want in your CSV line with a go-template syntax, please check internal/exporter/feature_event.go to see what are the fields available.
path	string	bucket root level	The location of the directory in S3.
parquetCompressionCodec	string	SNAPPY	ParquetCompressionCodec is the parquet compression codec for better space efficiency. Available options

Google Storage

Field name	Type	Default	Description
kind	string	none	(mandatory) Value should be s3. This field is mandatory and describes which retriever you are using.
bucket	string	none	(mandatory) Name of your Google Cloud Storage Bucket.
flushInterval	int	60000	The interval in millisecond between 2 calls to the webhook (if the maxEventInMemory is reached before the flushInterval we will call the webhook before).
maxEventInMemory	int	100000	If we hit that limit we will call the webhook.
format	string	JSON	Format is the output format you want in your exported file. Available format: JSON, CSV, Parquet.
filename	string	flag-variation-{{ .Hostname}}-{{ .Timestamp}}.{{ .Format}}	You can use a templated config to define the name of your exported files. Available replacement are {{ .Hostname}}, {{ .Timestamp}} and {{ .Format}
csvTemplate	string	{{ .Kind}};{{ .ContextKind}};{{ .UserKey}};{{ .CreationDate}};{{ .Key}};{{ .Variation}};{{ .Value}};{{ .Default}};{{ .Source}}\n	CsvTemplate is used if your output format is CSV. This field will be ignored if you are using format other than CSV. You can decide which fields you want in your CSV line with a go-template syntax, please check internal/exporter/feature_event.go to see what are the fields available.
path	string	bucket root level	The location of the directory in S3.
parquetCompressionCodec	string	SNAPPY	ParquetCompressionCodec is the parquet compression codec for better space efficiency. Available options

SQS

Field name	Type	Default	Description
kind	string	none	(mandatory) Value should be sqs. This field is mandatory and describes which retriever you are using.
queueUrl	string	none	(mandatory) URL of your SQS queue. You can find it in your AWS console.

Kafka

Field name	Type	Default	Description
kafka.topic	string	none	(mandatory) Kafka topic to bind to.
kafka.addresses	[]string	none	(mandatory) List of bootstrap addresses for the Kafka cluster.
kafka.config	object	see description	This field allows fine tuning of the Kafka reader. This object should contain the Sarama configuration that the reader will use. On empty, a sensible default is created using sarama.NewConfig()

Google PubSub

Field name	Type	Default	Description
projectID	string	none	(mandatory) Value should be ID of GCP project you are using.
topic	string	none	(mandatory) Topic name on which messages will be published.

type notifier

Slack

Field name	Type	Default	Description
kind	string	none	(mandatory) Value should be slack. This field is mandatory and describe which retriever you are using.
slackWebhookUrl	string	none	(mandatory) The complete URL of your incoming webhook configured in Slack.

Webhook

Field name	Type	Default	Description
kind	string	none	(mandatory) Value should be webhook. This field is mandatory and describes which retriever you are using.
endpointUrl	string	none	(mandatory) The complete URL of your API (we will send a POST request to this URL, see format
secret	string	none	Secret used to sign your request body and fill the X-Hub-Signature-256 header. See signature section for more details.
meta	map[string]string	none	Add all the information you want to see in your request.
headers	map[string][]string	none	Add all the headers you want to add while calling the endpoint