Skip to main content
Version: v1.19.0

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 also override these file configuration by 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).

Field nameTypeDefaultDescription
retrieverretrievernone(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[]retrievernone(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.
listenint1031This is the port used by the relay proxy when starting the HTTP server.
pollingIntervalint60000This is the time interval in millisecond when the relay proxy is reloading the configuration file.
The minimum time accepted is 1000 millisecond.
enablePollingJitterbooleanfalseSet 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 + or - 10% of your polling interval.
Default: false
hideBannerbooleanfalseShould we display the beautiful go-feature-flag banner when starting the relay proxy
enableSwaggerbooleanfalseDo you want to enable swagger to test 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/.
hoststringlocalhostThis 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.
restApiTimeoutint5000Timeout in millisecond we are accepting to wait in our APIs.
debugbooleanfalseIf true you will have more logs in the output that will help you to better understand what happen. If an error happen in the API the error will be also shown in the body.
fileFormatstringyamlThis is the format of your go-feature-flag configuration file. Acceptable values are yaml, json, toml.
startWithRetrieverErrorbooleanfalseBy default the relay proxy will crash if he 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.
exporterexporternoneExporter is the configuration on how to export data.
notifiernotifiernoneNotifiers is the configuration on where to notify a flag change.
apiKeys[]stringnoneList of authorized API keys. 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.
evaluationContextEnrichmentObjectnoneIt 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, ...

All those 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 overriden by the evaluationContextEnrichment.

type retriever

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

S3

Field nameTypeDefaultDescription
kindstringnone(mandatory) Value should be s3.
This field is mandatory and describe which retriever you are using.
bucketstringnone(mandatory) This is the name of your S3 bucket (ex: my-featureflag-bucket).
itemstringnone(mandatory) Path to the file inside the bucket (ex: config/flag/my-flags.yaml).

GitHub

Field nameTypeDefaultDescription
kindstringnone(mandatory) Value should be github.
This field is mandatory and describe which retriever you are using.
repositorySlugstringnone(mandatory) The repository slug of the GitHub repository where your file is located (ex: thomaspoignant/go-feature-flag).
pathstringnone(mandatory) Path to the file inside the repository (ex: config/flag/my-flags.yaml).
branchstringmainThe branch we should check in the repository.
tokenstringnoneGithub token used to access a private repository, you need the repo permission (how to create a GitHub token).
timeoutstring10000Timeout in millisecond used when calling GitHub.

GitLab

Field nameTypeDefaultDescription
kindstringnone(mandatory) Value should be gitlab.
This field is mandatory and describe which retriever you are using.
repositorySlugstringnone(mandatory) The repository slug of the Gitlab repository where your file is located (ex: thomaspoignant/go-feature-flag).
pathstringnone(mandatory) Path to the file inside the repository (ex: config/flag/my-flags.yaml).
baseUrlstringhttps://gitlab.comThe base URL of your Gitlab instance.
branchstringmainThe branch we should check in the repository.
tokenstringnoneGitlab personal access token used to access a private repository (Create a personal access token).
timeoutstring10000Timeout in millisecond used when calling Gitlab.

File

Field nameTypeDefaultDescription
kindstringnone(mandatory) Value should be file.
This field is mandatory and describe which retriever you are using.
pathstringnone(mandatory) Path to the file in your local computer (ex: /goff/my-flags.yaml).

HTTP

Field nameTypeDefaultDescription
kindstringnone(mandatory) Value should be http.
This field is mandatory and describe which retriever you are using.
urlstringnone(mandatory) Location where to retrieve the file.
methodstringGETThe HTTP Method you are using to call the HTTP endpoint.
bodystringnoneThe HTTP Body you are using to call the HTTP endpoint.
headersmap[string][]stringnoneThe HTTP headers used to call when calling the HTTP endpoint (useful for authorization).
timeoutstring10000Timeout in millisecond used when calling the HTTP endpoint.

Google Storage

Field nameTypeDefaultDescription
kindstringnone(mandatory) Value should be googleStorage.
This field is mandatory and describe which retriever you are using.
bucketstringnone(mandatory) This is the name of your Google Storage bucket (ex: my-featureflag-bucket).
objectstringnone(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 nameTypeDefaultDescription
kindstringnone(mandatory) Value should be configmap.
This field is mandatory and describe which retriever you are using.
namespacestringnone(mandatory) This is the name of the namespace where your configmap is located (ex: default).
configmapstringnone(mandatory) Name of the configmap we should read (ex: feature-flag).
keystringnone(mandatory) Name of the key in the configmap which contains the flag.

type exporter

Webhook

Field nameTypeDefaultDescription
kindstringnone(mandatory) Value should be webhook.
This field is mandatory and describe which retriever you are using.
endpointUrlstringnone(mandatory) EndpointURL of your webhook.
flushIntervalint60000The interval in millisecond between 2 calls to the webhook (if the maxEventInMemory is reached before the flushInterval we will call the webhook before).
maxEventInMemoryint100000If we hit that limit we will call the webhook.
secretstringnoneSecret used to sign your request body and fill the X-Hub-Signature-256 header.
See signature section for more details.
metamap[string]stringnoneAdd all the information you want to see in your request.
headersmap[string][]stringnoneAdd all the headers you want to add while calling the endpoint

File

Field nameTypeDefaultDescription
kindstringnone(mandatory) Value should be file.
This field is mandatory and describe which retriever you are using.
outputDirstringnone(mandatory) OutputDir is the location of the directory where to store the exported files. It should finish with a /.
flushIntervalint60000The interval in millisecond between 2 calls to the webhook (if the maxEventInMemory is reached before the flushInterval we will call the webhook before).
maxEventInMemoryint100000If we hit that limit we will call the webhook.
formatstringJSONFormat is the output format you want in your exported file. Available format: JSON, CSV, Parquet.
filenamestringflag-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}
csvTemplatestring{{ .Kind}};{{ .ContextKind}};{{ .UserKey}};{{ .CreationDate}};{{ .Key}};{{ .Variation}};{{ .Value}};{{ .Default}};{{ .Source}}\nCsvTemplate is used if your output format is CSV.
This field will be ignored if you are using another format 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.
parquetCompressionCodecstringSNAPPYParquetCompressionCodec is the parquet compression codec for better space efficiency. Available options

Log

Field nameTypeDefaultDescription
kindstringnone(mandatory) Value should be log.
This field is mandatory and describe which retriever you are using.
flushIntervalint60000The interval in millisecond between 2 calls to the webhook (if the maxEventInMemory is reached before the flushInterval we will call the webhook before).
maxEventInMemoryint100000If we hit that limit we will call the webhook.
logFormatstring[{{ .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 nameTypeDefaultDescription
kindstringnone(mandatory) Value should be s3.
This field is mandatory and describe which retriever you are using.
bucketstringnone(mandatory) Name of your S3 Bucket.
flushIntervalint60000The interval in millisecond between 2 calls to the webhook (if the maxEventInMemory is reached before the flushInterval we will call the webhook before).
maxEventInMemoryint100000If we hit that limit we will call the webhook.
formatstringJSONFormat is the output format you want in your exported file. Available format: JSON, CSV, Parquet.
filenamestringflag-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}
csvTemplatestring{{ .Kind}};{{ .ContextKind}};{{ .UserKey}};{{ .CreationDate}};{{ .Key}};{{ .Variation}};{{ .Value}};{{ .Default}};{{ .Source}}\nCsvTemplate is used if your output format is CSV.
This field will be ignored if you are using another format 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.
pathstringbucket root levelThe location of the directory in S3.
parquetCompressionCodecstringSNAPPYParquetCompressionCodec is the parquet compression codec for better space efficiency. Available options

Google Storage

Field nameTypeDefaultDescription
kindstringnone(mandatory) Value should be s3.
This field is mandatory and describe which retriever you are using.
bucketstringnone(mandatory) Name of your Google Cloud Storage Bucket.
flushIntervalint60000The interval in millisecond between 2 calls to the webhook (if the maxEventInMemory is reached before the flushInterval we will call the webhook before).
maxEventInMemoryint100000If we hit that limit we will call the webhook.
formatstringJSONFormat is the output format you want in your exported file. Available format: JSON, CSV, Parquet.
filenamestringflag-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}
csvTemplatestring{{ .Kind}};{{ .ContextKind}};{{ .UserKey}};{{ .CreationDate}};{{ .Key}};{{ .Variation}};{{ .Value}};{{ .Default}};{{ .Source}}\nCsvTemplate is used if your output format is CSV.
This field will be ignored if you are using another format 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.
pathstringbucket root levelThe location of the directory in S3.
parquetCompressionCodecstringSNAPPYParquetCompressionCodec is the parquet compression codec for better space efficiency. Available options

SQS

Field nameTypeDefaultDescription
kindstringnone(mandatory) Value should be sqs.
This field is mandatory and describe which retriever you are using.
queueUrlstringnone(mandatory) URL of your SQS queue.
You can find it in your AWS console.

type notifier

Slack

Field nameTypeDefaultDescription
kindstringnone(mandatory) Value should be slack.
This field is mandatory and describe which retriever you are using.
slackWebhookUrlstringnone(mandatory) The complete URL of your incoming webhook configured in Slack.

Webhook

Field nameTypeDefaultDescription
kindstringnone(mandatory) Value should be webhook.
This field is mandatory and describe which retriever you are using.
endpointUrlstringnone(mandatory) The complete URL of your API (we will send a POST request to this URL, see format
secretstringnoneSecret used to sign your request body and fill the X-Hub-Signature-256 header.
See signature section for more details.
metamap[string]stringnoneAdd all the information you want to see in your request.
headersmap[string][]stringnoneAdd all the headers you want to add while calling the endpoint

Get the latest GO Feature Flag updates