diff --git a/website/versioned_docs/version-v1.13.0/_category_.json b/website/versioned_docs/version-v1.13.0/_category_.json new file mode 100644 index 00000000000..c640b3bdf2d --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/_category_.json @@ -0,0 +1,5 @@ +{ + "position": 0, + "collapsible": true, + "collapsed": false +} diff --git a/website/versioned_docs/version-v1.13.0/configure_flag/_category_.json b/website/versioned_docs/version-v1.13.0/configure_flag/_category_.json new file mode 100644 index 00000000000..93abd20b37d --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/configure_flag/_category_.json @@ -0,0 +1,10 @@ +{ + "position": 20, + "collapsible": true, + "collapsed": true, + "label": "Configure your feature flags", + "link": { + "type": "generated-index", + "title": "Configure your feature flags" + } +} diff --git a/website/versioned_docs/version-v1.13.0/configure_flag/export_flags_usage.mdx b/website/versioned_docs/version-v1.13.0/configure_flag/export_flags_usage.mdx new file mode 100644 index 00000000000..e09419d8642 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/configure_flag/export_flags_usage.mdx @@ -0,0 +1,63 @@ +--- +sidebar_position: 40 +description: How to export evaluation data? +--- +import {Cards} from '@site/src/components/doc/cards'; +import customlogo from '@site/static/docs/collectors/custom.png'; +import filelogo from '@site/static/docs/collectors/file.png'; +import googlelogo from '@site/static/docs/collectors/google.png'; +import loglogo from '@site/static/docs/collectors/log.png'; +import s3logo from '@site/static/docs/collectors/s3.png'; +import webhooklogo from '@site/static/docs/collectors/webhook.png'; + +# How to export evaluation data +GO Feature Flag allows for the collection of flag usage data. +During flag evaluation, the key, flag variation and other non-sensitive information used are collected and cached for a +configurable period of time. + +The usage data is then written to a file in a chosen format (`parquet`, `JSON` or `CSV`) at a specified interval and +exported to your desired location. This provides a single source for easy processing of the data. The feature can be +configured with options for file format, flush interval, and file location. + +To use, simply configure, use the feature flag as normal, and analyze the collected usage data. + +## Available exporters + + diff --git a/website/versioned_docs/version-v1.13.0/configure_flag/flag_format.mdx b/website/versioned_docs/version-v1.13.0/configure_flag/flag_format.mdx new file mode 100644 index 00000000000..da13507f0c0 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/configure_flag/flag_format.mdx @@ -0,0 +1,283 @@ +--- +sidebar_position: 20 +description: What is a flag and how you can create them. +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + +# How to configure a flag + +**GO Feature Flag** core feature is to centralize all your feature flags in a source file, and to avoid hosting and maintaining a backend server to manage them. + +Your file must be a valid `YAML`, `JSON` or `TOML` file with a list of flags +*(examples: [`YAML`](https://github.com/thomaspoignant/go-feature-flag/tree/main/testdata/flag-config.yaml), +[`JSON`](https://github.com/thomaspoignant/go-feature-flag/tree/main/testdata/flag-config.json), +[`TOML`](https://github.com/thomaspoignant/go-feature-flag/tree/main/testdata/flag-config.toml))*. + +:::tip +The easiest way to create your configuration file is to used +[**GO Feature Flag Editor** available at [https://editor.gofeatureflag.org](https://editor.gofeatureflag.org). + +If you prefer to do it manually please follow instruction bellow. +::: + +## Editor + +Creating the first version of the flag is not always pleasant, that's why we have created +[**GO Feature Flag Editor**](https://editor.gofeatureflag.org) a simple editor to create your files. + +## Example + +A flag configuration looks like: + + + + + +```yaml +# This is your configuration for your first flag +first-flag: + variations: # All possible return value for your feature flag + A: false + B: true + targeting: # If you want to target a subset of your users in particular + - query: key eq "random-key" + percentage: + A: 0 + B: 100 + defaultRule: # When no targeting match we use the defaultRule + variation: A + metadata: + issue_link: https://github.com/thomaspoignant/go-feature-flag/issues/XXX + description: this is my first feature flag + +# A second example of a flag configuration +second-flag: + variations: + A: "valueA" + B: "valueB" + defaultValue: "a default value" + targeting: + - name: legacyRuleV0 + query: key eq "not-a-key" + percentage: + A: 10 + B: 90 + defaultRule: + name: legacyDefaultRule + variation: defaultValue + version: "12" + experimentation: + start: 2021-03-20T00:00:00.1-05:00 + end: 2021-03-21T00:00:00.1-05:00 +``` + + + + +```json +{ + "first-flag": { + "variations": { + "A": false, + "B": true + }, + "targeting": [ + { + "query": "key eq \"random-key\"", + "percentage": { + "A": 0, + "B": 100 + } + } + ], + "defaultRule": { + "variation": "A" + }, + "metadata": { + "issue_link": "https://github.com/thomaspoignant/go-feature-flag/issues/XXX", + "description": "this is my first feature flag" + } + }, + + "second-flag": { + "variations": { + "A": "valueA", + "B": "valueB", + "defaultValue": "a default value" + }, + "targeting": [ + { + "name": "legacyRuleV0", + "query": "key eq \"not-a-key\"", + "percentage": { + "A": 10, + "B": 90 + } + } + ], + "defaultRule": { + "name": "legacyDefaultRule", + "variation": "defaultValue" + }, + "version": "12", + "experimentation": { + "start": "2021-03-20T05:00:00.100Z", + "end": "2021-03-21T05:00:00.100Z" + } + } +} +``` + + + + +```toml +[first-flag.variations] +A = false +B = true + +[[first-flag.targeting]] +query = 'key eq "random-key"' + + [first-flag.targeting.percentage] + A = 0 + B = 100 + +[first-flag.defaultRule] +variation = "A" + +[first-flag.metadata] +issue_link = "https://github.com/thomaspoignant/go-feature-flag/issues/XXX" +description = "this is my first feature flag" + +[second-flag] +version = "12" + + [second-flag.variations] + A = "valueA" + B = "valueB" + defaultValue = "a default value" + + [[second-flag.targeting]] + name = "legacyRuleV0" + query = 'key eq "not-a-key"' + + [second-flag.targeting.percentage] + A = 10 + B = 90 + + [second-flag.defaultRule] + name = "legacyDefaultRule" + variation = "defaultValue" + + [second-flag.experimentation] + start = 2021-03-20T05:00:00.100Z + end = 2021-03-21T05:00:00.100Z +``` + + + + +## Format details + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
flag-keyName of your flag.
It must be unique.
On the example the flag keys are test-flag and test-flag2.
variations +

Variations are all the variations available for this flag.

+

It is represented as a key/value element. The key is the name of the variation and the value could be any types available (string, float, int, map, array, bool).

+

You can have as many variation as needed.

+ 
# Some examples

+         variationString: test

+         variationBool: true

+         variationInt: 1000

+         variationFloat: 1000.23

+         variationArray: 
  - item1
  - item2

+         variationObj:
  item1: 123
  item2: this is a string
  item3: false

+
+
targeting
(optional)		 +

+ Targeting contains the list of rules you have to target a subset of your users. +
You can have as many target as needed. +

+

This field is an array and contains a list of rules.

+

See rules format to have more info on how to write a rule.

+
defaultRule +

DefaultRule is the rule that is applied if the user does not match in any targeting.

+

See rules format to have more info on how to write a rule.

+
trackEvents
(optional)		 +

false if you don't want to export the data in your data exporter.

+

Default: true

+
disable
(optional)		 +

true if the flag is disabled.

+

Default: false

+
version
(optional)		 +

The version is the version of your flag.
This string is used to display the information in the notifiers and data collection, you have to update it your self.

+

Default: ""

+
metadata
(optional)		 +

This field allows adding a wealth of information about a particular feature flag, such as a configuration URL or the originating Jira issue.

+
scheduledRollout
(optional)		 +

Scheduled allow to patch your flag over time.

+

You can add several steps that updates the flag, this is typically used if you want to gradually add more user in your flag.

+

See Scheduled rollout to have more info on how to use it.

+
experimentation
(optional)		 +

Experimentation allow you to configure a start date and an end date for your flag. When the experimentation is not running, the flag will serve the default value.

+

See Experimentation rollout to have more info on how to use it.

+
+ + + + +## Advanced configurations + +You can have advanced configurations for your flag to have specific behavior for them, such as: +- [Specific rollout strategies](../category/rollout-strategies/) +- [Don't track a flag](../go_module/data_collection/index.md#dont-track-a-flag) diff --git a/website/versioned_docs/version-v1.13.0/configure_flag/rollout/_category_.json b/website/versioned_docs/version-v1.13.0/configure_flag/rollout/_category_.json new file mode 100644 index 00000000000..2bcc953a6c4 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/configure_flag/rollout/_category_.json @@ -0,0 +1,11 @@ +{ + "position": 30, + "collapsible": true, + "collapsed": true, + "label": "Rollout strategies", + "link": { + "type": "generated-index", + "title": "Rollout strategies", + "description": "A critical part of every new feature release is orchestrating the actual launch schedule between Product, Engineering, and Marketing teams. Delivering powerful user experiences typically requires software teams to manage complex releases and make manual updates at inconvenient times. But it does’t have to, having a complex rollout strategy allows you to have lifecycle for your flags." + } +} diff --git a/website/versioned_docs/version-v1.13.0/configure_flag/rollout/canary.mdx b/website/versioned_docs/version-v1.13.0/configure_flag/rollout/canary.mdx new file mode 100644 index 00000000000..cca4d50e6be --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/configure_flag/rollout/canary.mdx @@ -0,0 +1,68 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Canary Release + +**Canary release** is a technique to reduce the risk of introducing a new software version in production by slowly rolling out the change to a small subset of users before rolling it out to the entire infrastructure and making it available to everybody. + +This is the easiest rollout strategy available. +You just have to select a percentage of your users in your flag, and the `True` behavior will apply to them. + +## Example + + + + +```yaml +canary-flag: + variations: + oldBehavior: false + canary: true + defaultRule: + # highlight-start + percentage: + oldBehavior: 99 + canary: 1 + # highlight-end +``` + + + + +```json + { + "canary-flag": { + "variations": { + "oldBehavior": false, + "canary": true + }, + "defaultRule": { +# highlight-start + "percentage": { + "oldBehavior": 99, + "canary": 1 + } +# highlight-end + } + } +} +``` + + + + + +```toml +[canary-flag.variations] +oldBehavior = false +canary = true + +# highlight-start +[canary-flag.defaultRule.percentage] +oldBehavior = 99 +canary = 1 +# highlight-end +``` + + + diff --git a/website/versioned_docs/version-v1.13.0/configure_flag/rollout/experimentation.mdx b/website/versioned_docs/version-v1.13.0/configure_flag/rollout/experimentation.mdx new file mode 100644 index 00000000000..7886b6cb023 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/configure_flag/rollout/experimentation.mdx @@ -0,0 +1,107 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Experimentation rollout / A/B Testing +An **experimentation rollout** is when your flag is configured to be served only for a determined time. + +1. It means that before the rollout start date, the `default` value is served to all users. +2. Between the dates the flag is evaluated. +3. After the end date the `default` value is served to all users. + +## Example + + + + +```yaml +experimentation-flag: + variations: + variationA: A + variationB: B + defaultRule: + percentage: + variationA: 50 + variationB: 50 + # highlight-start + experimentation: + start: 2021-03-20T00:00:00.1-05:00 + end: 2021-03-21T00:00:00.1-05:00 + # highlight-end +``` + + + + +```json +{ + "experimentation-flag": { + "variations": { + "variationA": "A", + "variationB": "B" + }, + "defaultRule": { + "percentage": { + "variationA": 50, + "variationB": 50 + } + }, +# highlight-start + "experimentation": { + "start": "2021-03-20T05:00:00.100Z", + "end": "2021-03-21T05:00:00.100Z" + }, +# highlight-end + } +} +``` + + + + +```toml +[experimentation-flag.variations] +variationA = "A" +variationB = "B" + +[experimentation-flag.defaultRule.percentage] +variationA = 50 +variationB = 50 + +# highlight-start +[experimentation-flag.experimentation] +start = 2021-03-20T05:00:00.100Z +end = 2021-03-21T05:00:00.100Z +# highlight-end +``` + + + + +Check this [example](https://github.com/thomaspoignant/go-feature-flag/tree/main/examples/rollout_experimentation) to see how it works. + +## Configuration fields + +:::info +The dates are in the format supported natively by your flag file format. +::: + +| Field | Description | +|-------------|-------------------------------------------------| +| **`start`** | The date the flag will be started to be served. | +| **`end`** | The date the flag will be stopped to be served. | + +## A/B testing + +:::info +A/B test is the shorthand for a simple controlled experiment. +As the name implies, two versions (A and B) of a single variable are compared, which are identical except for one variation that might affect a user's behavior. +A/B tests are widely considered the simplest form of controlled experiment. + +_**(source wikipedia)**_ +::: + +To have a proper A/B testing solution with the module you should use the experimentation rollout combined with the [export of your data](../../go_module/data_collection/). + +This combination will allow to have your experimentation running for a dedicated time, and you will have the data to knows exactly which user was on which version of the flag. + +To setup the duration of your A/B test you can use a tool [ab-test-duration-calculator](https://vwo.com/tools/ab-test-duration-calculator/) from vwo, that will help you to set up the test duration correctly. diff --git a/website/versioned_docs/version-v1.13.0/configure_flag/rollout/progressive.mdx b/website/versioned_docs/version-v1.13.0/configure_flag/rollout/progressive.mdx new file mode 100644 index 00000000000..e79e4ae9d9a --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/configure_flag/rollout/progressive.mdx @@ -0,0 +1,97 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Progressive rollout + +A **progressive rollout** allows you to increase the percentage of your flag over time. + +You can select a **release ramp** where the percentage of your flag will increase progressively between the start date +and the end date. + +## Example + + + + +```yaml +progressive-flag: + variations: + variationA: A + variationB: B + defaultRule: +# highlight-start + progressiveRollout: + initial: + variation: variationB + percentage: 0 + date: 2021-03-20T00:00:00.1-05:00 + end: + variation: variationB + percentage: 100 + date: 2021-03-21T00:00:00.1-05:00 +# highlight-end +``` + + + + +```json +{ + "progressive-flag": { + "variations": { + "variationA": "A", + "variationB": "B" + }, + "defaultRule": { +# highlight-start + "progressiveRollout": { + "initial": { + "variation": "variationB", + "percentage": 0, + "date": "2021-03-20T05:00:00.100Z" + }, + "end": { + "variation": "variationB", + "percentage": 100, + "date": "2021-03-21T05:00:00.100Z" + } + }, +# highlight-end + } + } +} +``` + + + + +```toml +[progressive-flag.variations] +variationA = "A" +variationB = "B" +# highlight-start +[progressive-flag.defaultRule.progressiveRollout.initial] +variation = "variationB" +percentage = 0 +date = 2021-03-20T05:00:00.100Z + +[progressive-flag.defaultRule.progressiveRollout.end] +variation = "variationB" +percentage = 100 +date = 2021-03-21T05:00:00.100Z +# highlight-end +``` + + + + +## Configuration fields + +:::info +The dates are in the format supported natively by your flag file format. +::: + +| Field | Description | +|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **`releaseRamp`** | It contains the time slot where we will progressively increase the percentage of the flag.

If you have no date in your `releaseRamp` we will not do any progressive rollout and use the top level percentage you have configured *(0% in our example)*.

| +| **`percentage`** | *(optional)*
It represents the ramp of progress, at which level the flag starts (`initial`) and at which level it ends (`end`).
**Default: `initial` = `0` and `end` = `100`** | diff --git a/website/versioned_docs/version-v1.13.0/configure_flag/rollout/scheduled.mdx b/website/versioned_docs/version-v1.13.0/configure_flag/rollout/scheduled.mdx new file mode 100644 index 00000000000..ebea39febb6 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/configure_flag/rollout/scheduled.mdx @@ -0,0 +1,138 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Scheduled rollout + +Scheduling introduces the ability for users to changes their flags for future points in time. +While this sounds deceptively straightforward, it unlocks the potential for users to create complex release strategies by scheduling the incremental steps in advance. + +For example, you may want to turn a feature ON for internal testing tomorrow and then enable it for your ‘beta’ user segment four days later. + +## Example + + + + +```yaml +scheduled-flag: + variations: + variationA: A + variationB: B + defaultRule: + name: legacyDefaultRule + percentage: + variationA: 100 + variationB: 0 +# highlight-start + scheduledRollout: + - date: 2020-04-10T00:00:00.1+02:00 + targeting: + - name: legacyRuleV0 + query: beta eq "true" + percentage: + variationA: 0 + variationB: 100 + + - date: 2022-05-12T15:36:00.1+02:00 + targeting: + - name: legacyRuleV0 + query: beta eq "false" +# highlight-end +``` + + + + +```json +{ + "scheduled-flag": { + "variations": { + "variationA": "A", + "variationB": "B" + }, + "defaultRule": { + "name": "legacyDefaultRule", + "percentage": { + "variationA": 100, + "variationB": 0 + } + }, + # highlight-start + "scheduledRollout": [ + { + "date": "2020-04-09T22:00:00.100Z", + "targeting": [ + { + "name": "legacyRuleV0", + "query": "beta eq \"true\"", + "percentage": { + "variationA": 0, + "variationB": 100 + } + } + ] + }, + { + "date": "2022-05-12T13:36:00.100Z", + "targeting": [ + { + "name": "legacyRuleV0", + "query": "beta eq \"false\"" + } + ] + } + ], + # highlight-end + } +} +``` + + + + +```toml +[scheduled-flag.variations] +variationA = "A" +variationB = "B" + +[scheduled-flag.defaultRule] +name = "legacyDefaultRule" + +[scheduled-flag.defaultRule.percentage] +variationA = 100 +variationB = 0 + +# highlight-start +[[scheduled-flag.scheduledRollout]] +date = 2020-04-09T22:00:00.100Z + +[[scheduled-flag.scheduledRollout.targeting]] +name = "legacyRuleV0" +query = 'beta eq "true"' + +[scheduled-flag.scheduledRollout.targeting.percentage] +variationA = 0 +variationB = 100 + +[[scheduled-flag.scheduledRollout]] +date = 2022-05-12T13:36:00.100Z + +[[scheduled-flag.scheduledRollout.targeting]] +name = "legacyRuleV0" +query = 'beta eq "false"' +# highlight-end +``` + + + + +## Configuration fields + +:::info +You can change any fields that are available on your flag. +Since your configuration has not been changed manually, it does not trigger any notifier. +::: + +| Field | Description | +|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **`steps`** | The only mandatory field in a **step** is the `date`.
**If no date is provided the step will be skipped.**

The other attributes of your `step` are what you want to update your flag, so every field available in the [flag format](../flag_format) can be updated.
The new value in a field will override the existing one. | diff --git a/website/versioned_docs/version-v1.13.0/configure_flag/rule_format.md b/website/versioned_docs/version-v1.13.0/configure_flag/rule_format.md new file mode 100644 index 00000000000..e86e20ded89 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/configure_flag/rule_format.md @@ -0,0 +1,149 @@ +--- +sidebar_position: 21 +description: How to create a rule to target specific users +--- + +# How to target specific users + +## Rule format + +A rule is a configuration that allows to serve a variation based on some conditions. + +### Format details + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
name
(optional)		Name of your rule.
This is needed when your are updating a rule using a scheduled rollout.
query +

+ Query represents an antlr query in the nikunjy/rules format. +
This field is mandatory in every rule used in the targeting field. +

+

See query format to have the syntax.

+

Note: if you use the field query in a defaultRule it will be ignored.

+
variation
(optional)		Name of the variation to return.
percentage
(optional)		 +

Represents the percentage we should give to each variation.

+ 
+            percentage:
  variationA: 10.59
  variationB: 9.41
  variationC: 80
+
+

The format is the name of the variation and the percentage for this one.

+

Note: if your total is not equals to 100% this rule will be considered as invalid.

+
progressiveRollout
(optional)		 +

Allow to ramp up the percentage of your flag over time.

+

You can decide at which percentage you starts with and at what percentage you ends with in your release ramp. + Before the start date we will serve the initial percentage and, after we will serve the end percentage. +

+

See progressive rollout to have more info on how to use it.

+
disable
(optional)		 +

Set to true if you want to disable the rule.

+

Default: true.

+
+ + +:::info +`variation`, `percentage` and `progressiveRollout` are optional but you **must have one of the 3**. + +If you have more than one field we will use the first one in that order +`progressiveRollout` > `percentage` > `variation`. +::: + +### Query format + +The rule format is based on the [`nikunjy/rules`](https://github.com/nikunjy/rules) library. + +All the operations can be written capitalized or lowercase (ex: `eq` or `EQ` can be used). +Logical Operations supported are `AND` `OR`. + +Compare Expression and their definitions (`a|b` means you can use either one of the two `a` or `b`): + +| Operator | Description | +|:----------:|-----------------------------| +| `eq`, `==` | equals to | +| `ne`, `!=` | not equals to | +| `lt`, `<` | less than | +| `gt`, `>` | greater than | +| `le`, `<=` | less than equal to | +| `ge`, `>=` | greater than equal to | +| `co` | contains | +| `sw` | starts with | +| `ew` | ends with | +| `in` | in a list | +| `pr` | present | +| `not` | not of a logical expression | + +#### Examples + +- Select a specific user: `key eq "example@example.com"` +- Select all identified users: `anonymous ne true` +- Select a user with a custom property: `userId eq "12345"` +- Select on multiple criteria: + *All users with ids finishing by `@test.com` that have the role `backend engineer` in the `pro` environment for the + company `go-feature-flag`* + + ```bash + (key ew "@test.com") and (role eq "backend engineer") and (env eq "pro") and (company eq "go-feature-flag") + ``` + +## Environments + +When you initialise `go-feature-flag` you can set an [environment](../go_module/configuration/#option_environment) for the instance of this SDK. + +```go linenums="1" +ffclient.Init(ffclient.Config{ + // ... + Environment: "prod", + // ... +}) +``` + +When an environment is set, it adds a new field in your user called **`env`** that you can use in your queries. +It means that you can decide to activate a flag only for some **environment**. + +**Example of flag configuration based on the environment:** + +```yaml +my-flag: + variations: + A: "A" + B: "B" + C: "C" + targeting: + - name: Target pre environment + query: env eq "pre" + variation: A + - name: Target pro environment + query: env eq "pro" + variation: B + defaultRule: + variation: C +``` diff --git a/website/versioned_docs/version-v1.13.0/configure_flag/store_your_flags.mdx b/website/versioned_docs/version-v1.13.0/configure_flag/store_your_flags.mdx new file mode 100644 index 00000000000..ac11bd41c60 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/configure_flag/store_your_flags.mdx @@ -0,0 +1,100 @@ +--- +sidebar_position: 10 +description: Where to store your configuration flag? +--- +import {Cards} from '@site/src/components/doc/cards'; +import httplogo from '@site/static/docs/retrievers/http.png'; +import customlogo from '@site/static/docs/retrievers/custom.png'; +import filelogo from '@site/static/docs/retrievers/file.png'; +import githublogo from '@site/static/docs/retrievers/github.png'; +import gitlablogo from '@site/static/docs/retrievers/gitlab.png'; +import googlelogo from '@site/static/docs/retrievers/google.png'; +import s3logo from '@site/static/docs/retrievers/s3.png'; +import k8slogo from '@site/static/docs/retrievers/k8s.png'; + +# Where to store your configuration flag +**GO Feature Flag** is a tool that makes it easy to implement feature flags in your application. One of the benefits of +using GO Feature Flag is that it is designed to be simple and lightweight. +To achieve this, the solution uses a file-based approach to configure your flags. + +When you use GO Feature Flag, you create one or more file(s) _(`YAML`, `TOML` or `JSON`)_ that contains your feature +flags and their values. You can then upload this file(s) where you want, and GO Feature Flag will use it. +The way the solution achieves this is through the use of retrievers, which allow you to load your feature flag +configuration file from various sources. + +**Retrievers** are a core concept in GO Feature Flag. They are responsible for loading your feature flag configuration +file from a specified location, such as a file on your local machine or a remote storage service. This allows you to +store your configuration file in a location that works best for your workflow. + +**GO Feature Flag** supports a variety of retrievers out of the box, including `S3`, `Google Cloud Storage`, `Github`, +`HTTP`, `Kubernetes config maps`, `Local file` ... +But you can also implement your own custom retriever if needed. + +Using retrievers in GO Feature Flag is straightforward. You simply specify which retriever to use in your configuration +file, along with any required configuration options. GO Feature Flag will then use the specified retriever to load your +configuration file and will evaluate your feature flags based on this configuration. + +## Available retrievers + + + +## Use multiple configuration flag files +Sometimes, you may need to store your feature flags in different locations. +In such cases, you can configure multiple retrievers to retrieve the flags from different sources within your GO Feature +Flag instance. + +To set this up, you need to configure the [`Retrievers`](../go_module/configuration#configuration-fields) field to +consume from different retrievers. +What this does is that it calls all the retrievers in parallel and applies them in the order you have provided. + +Keep in mind that if a flag is defined in multiple retrievers, it can be overridden by a later flag. For instance, +if you have a flag named _`my-feature-flag`_ in the first file and another flag with the same name in the second file, the second configuration will take precedence. diff --git a/website/versioned_docs/version-v1.13.0/faq.md b/website/versioned_docs/version-v1.13.0/faq.md new file mode 100644 index 00000000000..186c83e42c4 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/faq.md @@ -0,0 +1,61 @@ +--- +sidebar_position: 100 +--- +# Frequently Asked Questions + +### Why using feature flags? +This one of most common question I get. +Feature flags are a software development technique that turns certain functionality on and off during runtime, without +deploying new code. + +It allows you to decouple **deploy** and **release**, giving you better control and more experimentation over the full +lifecycle of features. + +--- + +### What is the lifecycle of a flag? +The lifecycle of your flags is key if you don't want to have un-used things everywhere in your code. + +1. Start by creating the flag in your configuration file *(with 0% to avoid affecting your users)*. +2. Evaluate the flag in your code *(see [variation](./go_module/target_user.md#variation))*. +3. Deploy your application with the variation check. +4. Start rolling out your flag. +5. When 100% of your users have access to the new feature, remove the call to the variation from your code base. +6. Deploy your application without the variation check. +7. Remove the flag from your configuration file. + +--- + +### What happen if my configuration file is not reachable/deleted? +If while you are on production for some reason your flag file becomes unreachable, we will be able to serve the users +based on the last version of the file we were able to read. We will continue to try reading the file based on +the `pollingInterval` you have configured. + +If you start a new instance, if the file is not reachable to module will fail to initialize except if you have set the +option `StartWithRetrieverError` in the config. With this option, we will serve the SDK default value *(the 3rd param +in your variation)* until the flag becomes available again. + +--- + +### What is the best rollout strategy? +The lib gives you a lot of strategies to rollout your flags, there is no better one, it always depends on the context +of your release. + +- If your release is not critical and, you just want an easy cut-off strategy, you can pass your flag from 0% to 100% for + all your users +- If you are scared that your infrastructure can be impacted by the new feature, a progressive rollout can help you to + impact users over time and to be able to check how your system handle it. +- If you want to impact only a subset of your users, you can put a rule on your flag. +- Etc ... + +You have an endless list of rollout strategies depending on what is your feature. + +--- + +### How we ensure that users affected by the feature flags are not always the same? + +To avoid always have the same users affected by a flag, the hash we compute that allows us to determine if the user is part of the percentage is not computed only based on the user key but a combination of the user key and the flag name. + +It guarantees that the user will be always in the same group but depending on the flag. + +--- diff --git a/website/versioned_docs/version-v1.13.0/getting_started/_category_.json b/website/versioned_docs/version-v1.13.0/getting_started/_category_.json new file mode 100644 index 00000000000..c813037664d --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/getting_started/_category_.json @@ -0,0 +1,12 @@ +{ + "position": 10, + "label":"Getting Started", + "collapsible": true, + "collapsed": true, + "link": { + "type": "generated-index", + "title": "Getting Started", + "description": "GO Feature Flag can be used in 2 different ways. You can use it as a GO module directly inside your code or by using an Open-feature SDK. To use the Open-feature SDKs you will need to deploy a relay proxy inside your architecture." + + } +} diff --git a/website/versioned_docs/version-v1.13.0/getting_started/using-go-module.md b/website/versioned_docs/version-v1.13.0/getting_started/using-go-module.md new file mode 100644 index 00000000000..0dd8a18a992 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/getting_started/using-go-module.md @@ -0,0 +1,62 @@ +--- +sidebar_position: 10 +description: Use the module in your GO application with nothing to install. +--- +# Using the GO module + +## Installation +```bash +go get github.com/thomaspoignant/go-feature-flag +``` + +## Create a feature flag configuration + +Create a new `YAML` file containing your first flag configuration. + +```yaml title="flag-config.yaml" +# 20% of the users will use the variation "my-new-feature" +test-flag: + variations: + my-new-feature: true + my-old-feature: false + defaultRule: + percentage: + my-new-feature: 20 + my-old-feature: 80 +``` + +This flag split the usage of this flag, 20% will use the variation `my-new-feature` and 80% the variation `my-old-feature`. + +## SDK Initialisation +First, you need to initialize the `ffclient` with the location of your backend file. +```go linenums="1" +err := ffclient.Init(ffclient.Config{ + PollingInterval: 3 * time.Second, + Retriever: &fileretriever.Retriever{ + Path: "flag-config.yaml", + }, +}) +defer ffclient.Close() +``` +*This example will load a file from your local computer and will refresh the flags every 3 seconds (if you omit the +PollingInterval, the default value is 60 seconds).* + +:::tip +This is a basic configuration to test locally, in production it is better to use a remote place to store your feature flag configuration file. + +Look at the list of available options in the [**Store your feature flag file** page](../go_module/store_file/). +::: + +## Evaluate your flags +Now you can evaluate your flags anywhere in your code. + +```go linenums="1" +user := ffcontext.NewEvaluationContext("user-unique-key") +hasFlag, _ := ffclient.BoolVariation("test-flag", user, false) +if hasFlag { + // flag "test-flag" is true for the user +} else { + // flag "test-flag" is false for the user +} +``` +You can find more examples in the [examples/](https://github.com/thomaspoignant/go-feature-flag/tree/main/examples) directory. diff --git a/website/versioned_docs/version-v1.13.0/getting_started/using-openfeature.md b/website/versioned_docs/version-v1.13.0/getting_started/using-openfeature.md new file mode 100644 index 00000000000..cca7d73b904 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/getting_started/using-openfeature.md @@ -0,0 +1,121 @@ +--- +sidebar_position: 20 +description: Deploy the relay proxy and use the OpenFeature SDKs +--- +# Using Open Feature SDKs + +:::note +OpenFeature provides a shared, standardized feature flagging client - _an SDK_ - which can be plugged into various 3rd-party feature flagging providers. +Whether you're using an open-source system or a commercial product, whether it's self-hosted or cloud-hosted, OpenFeature provides a consistent, unified API for developers to use feature flagging in their applications. +_[Documentation](https://docs.openfeature.dev)_ +::: + +GO Feature Flag believe in **OpenSource** and **standardization**, this is the reason why we decided not implementing any custom SDK and rely only on **Open Feature**. + +To be compatible with Open Feature, **GO Feature Flag** is providing a lightweight self-hosted API server *(called [relay proxy](../category/use-the-relay-proxy))* that is using the GO Feature Flag module internally. +When the **relay proxy** is running in your infrastructure, you can use the **Open Feature SDKs** in combination with **GO Feature Flag providers** to evaluate your flags. + +This schema is an overview on how **Open Feature** is working, you can have more information about all the concepts in the **[Open Feature documentation](https://docs.openfeature.dev)**. +![](/docs/openfeature/concepts.jpg) + +## Create a feature flag configuration + +Create a new `YAML` file containing your first flag configuration. + +```yaml title="flag-config.yaml" +# 20% of the users will use the variation "my-new-feature" +test-flag: + variations: + my-new-feature: true + my-old-feature: false + defaultRule: + percentage: + my-new-feature: 20 + my-old-feature: 80 +``` + +This flag split the usage of this flag, 20% will use the variation `my-new-feature` and 80% the variation `my-old-feature`. + +## Create a relay proxy configuration file + +Create a new `YAML` file containing the configuration of your relay proxy. + +```yaml title="goff-proxy.yaml" +listen: 1031 +pollingInterval: 1000 +startWithRetrieverError: false +retriever: + kind: file + path: /goff/flag-config.yaml +exporter: + kind: log +``` + +## Install the relay proxy + +And we will run the **relay proxy** locally to make the API available. +The default port will be `1031`. + +```shell +# Launch the container +docker run \ + -p 1031:1031 \ + -v $(pwd)/flag-config.yaml:/goff/flag-config.yaml \ + -v $(pwd)/goff-proxy.yaml:/goff/goff-proxy.yaml \ + thomaspoignant/go-feature-flag-relay-proxy:latest + +``` + +_If you don't want to use docker to install the **relay proxy** you can follow the [documentation](../relay_proxy/install_relay_proxy.md)_. + +## Use Open Feature SDK + +_In this example we are using the javascript SDK, but it is still relevant for all the languages_. + +### Install dependencies + +```shell +npm i @openfeature/js-sdk @openfeature/go-feature-flag-provider +``` + +### Init your Open Feature client + +In your app initialization your have to create a client using the Open Feature SDK and initialize it. + +```javascript +const {OpenFeature} = require("@openfeature/js-sdk"); +const {GoFeatureFlagProvider} = require("@openfeature/go-feature-flag-provider"); + + +// init Open Feature SDK with GO Feature Flag provider +const goFeatureFlagProvider = new GoFeatureFlagProvider({ + endpoint: 'http://localhost:1031/' // DNS of your instance of relay proxy +}); +OpenFeature.setProvider(goFeatureFlagProvider); +const featureFlagClient = OpenFeature.getClient('my-app') +``` + +### Evaluate your flag + +Now you can evaluate your flags anywhere in your code using this client. + +```javascript +// Context of your flag evaluation. +// With GO Feature Flag you MUST have a targetingKey that is a unique identifier of the user. +const userContext = { + targetingKey: '1d1b9238-2591-4a47-94cf-d2bc080892f1', // user unique identifier (mandatory) + firstname: 'john', + lastname: 'doe', + email: 'john.doe@gofeatureflag.org', + admin: true, // this field is used in the targeting rule of the flag "flag-only-for-admin" + // ... +}; + +const adminFlag = await featureFlagClient.getBooleanValue('flag-only-for-admin', false, userContext); +if (adminFlag) { + // flag "flag-only-for-admin" is true for the user + console.log("new feature"); +} else { + // flag "flag-only-for-admin" is false for the user +} +``` diff --git a/website/versioned_docs/version-v1.13.0/go_module/_category_.json b/website/versioned_docs/version-v1.13.0/go_module/_category_.json new file mode 100644 index 00000000000..215e2ea86ba --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/_category_.json @@ -0,0 +1,10 @@ +{ + "position": 40, + "label":"Use as a GO module", + "collapsible": true, + "collapsed": true, + "link": { + "type": "generated-index", + "title": "Use as a GO module" + } +} diff --git a/website/versioned_docs/version-v1.13.0/go_module/configuration.md b/website/versioned_docs/version-v1.13.0/go_module/configuration.md new file mode 100644 index 00000000000..cd1985c689a --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/configuration.md @@ -0,0 +1,99 @@ +--- +sidebar_position: 10 +description: How to configure the GO module to use it directly in your code. +--- + +# Configuration +`go-feature-flag` needs to be initialized to be used. +During the initialization you must give a [`ffclient.Config{}`](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag#Config) configuration object. + +[`ffclient.Config{}`](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag#Config) is the only location where you can put the configuration. + +## Configuration fields + +| Field | Description | +|---------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `Retriever` | The configuration retriever you want to use to get your flag file
*See [Store your flag file](./store_file/index.md) for the configuration details*.

*This field is optional if `Retrievers`* is configured. | +| `Retrievers` | `Retrievers` is exactly the same thing as `Retriever` but you can configure more than 1 source for your flags.
All flags are retrieved in parallel, but we are applying them in the order you provided them _(it means that a flag can be overridden by another flag)_.
*See [Store your flag file](./store_file/index.md) for the configuration details*.

*This field is optional if `Retrievers`* is configured. | +| `Context` | *(optional)*
The context used by the retriever.
Default: `context.Background()` | +| `Environment` | *(optional)*
The environment the app is running under, can be checked in feature flag rules.
Default: `""`
*Check [**"environments"** section](../configure_flag/flag_format/#environments) to understand how to use this parameter.* | +| `DataExporter` | *(optional)*
DataExporter defines how to export data on how your flags are used.
*see [export data section](data_collection/index.md) for more details*. | +| `FileFormat` | *(optional)*
Format of your configuration file. Available formats are `yaml`, `toml` and `json`, if you omit the field it will try to unmarshal the file as a `yaml` file.
Default: `YAML` | +| `Logger` | *(optional)*
Logger used to log what `go-feature-flag` is doing.
If no logger is provided the module will not log anything.
Default: No log | +| `Notifiers` | *(optional)*
List of notifiers to call when your flag file has been changed.
*See [notifiers section](./notifier/index.md) for more details*. | +| `PollingInterval` | (optional) Duration to wait before refreshing the flags.
The minimum polling interval is 1 second.
Default: 60 * time.Second | +| `EnablePollingJitter` | (optional) 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 + or - 10% of your polling interval.
Default: false | +| `StartWithRetrieverError` | *(optional)* If **true**, the SDK will start even if we did not get any flags from the retriever. It will serve only default values until the retriever returns the flags.
The init method will not return any error if the flag file is unreachable.
Default: **false** | +| `Offline` | *(optional)* If **true**, the SDK will not try to retrieve the flag file and will not export any data. No notification will be send neither.
Default: false | + +## Example +```go +ffclient.Init(ffclient.Config{ + PollingInterval: 3 * time.Second, + Logger: log.New(file, "/tmp/log", 0), + Context: context.Background(), + Environment: os.Getenv("MYAPP_ENV"), + Retriever: &fileretriever.Retriever{Path: "testdata/flag-config.yaml"}, + FileFormat: "yaml", + Notifiers: []notifier.Notifier{ + &webhooknotifier.Notifier{ + EndpointURL: " https://example.com/hook", + Secret: "Secret", + Meta: map[string]string{ + "app.name": "my app", + }, + }, + }, + DataExporter: ffclient.DataExporter{ + FlushInterval: 10 * time.Second, + MaxEventInMemory: 1000, + Exporter: &file.Exporter{ + OutputDir: "/output-data/", + }, + }, + StartWithRetrieverError: false, +}) +``` + +## Multiple configuration flag files +`go-feature-flag` comes ready to use out of the box by calling the `Init` function and, it will be available everywhere. +Since most applications will want to use a single central flag configuration, the package provides this. It is similar to a singleton. + +In all the examples above, they demonstrate using `go-feature-flag` in its singleton style approach. + +### Working with multiple go-feature-flag + +You can also create many `go-feature-flag` clients to use in your application. + +Each will have its own unique set of configurations and flags. Each can read from a different config file and from different places. +All the functions that `go-feature-flag` package supports are mirrored as methods on a [`GoFeatureFlag`](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag#GoFeatureFlag). + +#### Example + +```go linenums="1" +x, err := ffclient.New(Config{ Retriever: &httpretriever.Retriever{{URL: "http://example.com/flag-config.yaml",}}) +defer x.Close() + +y, err := ffclient.New(Config{ Retriever: &httpretriever.Retriever{{URL: "http://example.com/test2.yaml",}}) +defer y.Close() + +user := ffcontext.NewEvaluationContext("user-key") +x.BoolVariation("test-flag", user, false) +y.BoolVariation("test-flag", user, false) + +// ... +``` + +When working with multiple [`GoFeatureFlag`](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag#GoFeatureFlag), it is up to the user to keep track of the different [`GoFeatureFlag`](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag#GoFeatureFlag) instances. + +## Offline mode +In some situations, you might want to stop making remote calls and fall back to default values for your feature flags. +For example, if your software is both cloud-hosted and distributed to customers to run on-premise, it might make sense +to fall back to defaults when running on-premise. + +You can do this by setting `Offline` mode in the client's Config. + +## Advanced configuration + +- [Export data from your flag variations](./data_collection/index.md) +- [Be notified when your flags change](./notifier/index.md) diff --git a/website/versioned_docs/version-v1.13.0/go_module/data_collection/_category_.json b/website/versioned_docs/version-v1.13.0/go_module/data_collection/_category_.json new file mode 100644 index 00000000000..31a74b81af7 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/data_collection/_category_.json @@ -0,0 +1,5 @@ +{ + "position": 40, + "collapsible": true, + "collapsed": true +} diff --git a/website/versioned_docs/version-v1.13.0/go_module/data_collection/custom.md b/website/versioned_docs/version-v1.13.0/go_module/data_collection/custom.md new file mode 100644 index 00000000000..13922eb8232 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/data_collection/custom.md @@ -0,0 +1,24 @@ +--- +sidebar_position: 30 +--- + +# Custom exporter +To create a custom exporter you must have a `struct` that implements the [`exporter.Exporter`](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag/internal/exporter#Exporter) interface. + + +```go +type Exporter interface { + // Export will send the data to the exporter. + Export(context.Context, *log.Logger, []exporter.FeatureEvent) error + + // IsBulk return false if we should directly send the data as soon as it is produce + // and true if we collect the data to send them in bulk. + IsBulk() bool +} +``` +`Export` is called asynchronously with a list of `exporter.FeatureEvent` that have been collected. +It is your responsibility to store them where you want. + +`IsBulk` function should return `false` if the exporter can handle the results in stream mode. +If you decide to manage it in streaming mode, everytime we call a variation the `Export` function will be called +with only on event in the list. diff --git a/website/versioned_docs/version-v1.13.0/go_module/data_collection/file.md b/website/versioned_docs/version-v1.13.0/go_module/data_collection/file.md new file mode 100644 index 00000000000..9bcf78aeb1a --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/data_collection/file.md @@ -0,0 +1,38 @@ +--- +sidebar_position: 3 +--- + +# File Exporter +The file exporter will collect the data and create a new file in a specific folder everytime we send the data. +This file should be in the local instance. + +Check this [complete example](https://github.com/thomaspoignant/go-feature-flag/tree/main/examples/data_export_file) to see how to export the data in a file. + +## Configuration example +```go linenums="1" +ffclient.Config{ + // ... + DataExporter: ffclient.DataExporter{ + // ... + Exporter: &fileexporter.Exporter{ + OutputDir: "/output-data/", + Format: "csv", + FileName: "flag-variation-{{ .Hostname}}-{{ .Timestamp}}.{{ .Format}}", + CsvTemplate: "{{ .Kind}};{{ .ContextKind}};{{ .UserKey}};{{ .CreationDate}};{{ .Key}};{{ .Variation}};{{ .Value}};{{ .Default}}\n" + }, + }, + // ... +} +``` + +## Configuration fields + +| Field | Description | +|---|---| +|`OutputDir` | OutputDir is the location of the directory where to store the exported files.
It should finish with a `/`. | +|`Format` | _(Optional)_ Format is the output format you want in your exported file.
Available format: **`JSON`**, **`CSV`**, **`Parquet`**.
**Default: `JSON`** | +|`Filename` | _(Optional)_ Filename is the name of your output file.
You can use a templated config to define the name of your exported files.
Available replacement are `{{ .Hostname}}`, `{{ .Timestamp}}` and `{{ .Format}}`
**Default: `flag-variation-{{ .Hostname}}-{{ .Timestamp}}.{{ .Format}}`**| +|`CsvTemplate` | _(Optional)_ CsvTemplate 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](https://github.com/thomaspoignant/go-feature-flag/blob/main/internal/exporter/feature_event.go) to see what are the fields available.
**Default:** `{{ .Kind}};{{ .ContextKind}};{{ .UserKey}};{{ .CreationDate}};{{ .Key}};{{ .Variation}};{{ .Value}};{{ .Default}}\n` | +| `ParquetCompressionCodec` | _(Optional)_ ParquetCompressionCodec is the parquet compression codec for better space efficiency. [Available options](https://github.com/apache/parquet-format/blob/master/Compression.md)
**Default: `SNAPPY`** |` + +Check the [godoc for full details](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag/exporter/fileexporter). diff --git a/website/versioned_docs/version-v1.13.0/go_module/data_collection/google_cloud_storage.md b/website/versioned_docs/version-v1.13.0/go_module/data_collection/google_cloud_storage.md new file mode 100644 index 00000000000..0e1821453c8 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/data_collection/google_cloud_storage.md @@ -0,0 +1,46 @@ +--- +sidebar_position: 2 +--- + +# Google Cloud Storage Exporter + +The **Google Cloud Storage exporter** will collect the data and create a new file in a specific folder everytime we send the data. + +Everytime the `FlushInterval` or `MaxEventInMemory` is reached a new file will be added to S3. + +:::info +If for some reason the Google Cloud Storage upload failed, we will keep the data in memory and retry to add the next time we reach `FlushInterval` or `MaxEventInMemory`. +::: + +Check this [complete example](https://github.com/thomaspoignant/go-feature-flag/tree/main/examples/data_export_googlecloudstorage) to see how to export the data in S3. + +## Configuration example +```go linenums="1" +ffclient.Config{ + // ... + DataExporter: ffclient.DataExporter{ + // ... + Exporter: &gcstorageexporter.Exporter{ + Bucket: "test-goff", + Format: "json", + Path: "yourPath", + Filename: "flag-variation-{{ .Timestamp}}.{{ .Format}}", + Options: []option.ClientOption{}, // Your google cloud SDK options + }, + }, + // ... +} +``` + +## Configuration fields +| Field | Description | +|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `Bucket ` | Name of your Google Cloud Storage Bucket. | +| `CsvTemplate` | *(optional)* CsvTemplate 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](https://github.com/thomaspoignant/go-feature-flag/blob/main/internal/exporter/feature_event.go) to see what are the fields available.
**Default:** `{{ .Kind}};{{ .ContextKind}};{{ .UserKey}};{{ .CreationDate}};{{ .Key}};{{ .Variation}};{{ .Value}};{{ .Default}}\n` | +| `Filename` | *(optional)* Filename is the name of your output file. You can use a templated config to define the name of your exported files.
Available replacement are `{{ .Hostname}}`, `{{ .Timestamp}`} and `{{ .Format}}`
Default: `flag-variation-{{ .Hostname}}-{{ .Timestamp}}.{{ .Format}}` | +| `Format` | *(optional)* Format is the output format you want in your exported file. Available format are **`JSON`**, **`CSV`**, **`Parquet`**. *(Default: `JSON`)* | +| `Options` | *(optional)* An instance of `option.ClientOption` that configures your access to Google Cloud.
Check [this documentation for more info](https://cloud.google.com/docs/authentication). | +| `Path ` | *(optional)* The location of the directory in your bucket. | +| `ParquetCompressionCodec` | *(optional)* ParquetCompressionCodec is the parquet compression codec for better space efficiency. [Available options](https://github.com/apache/parquet-format/blob/master/Compression.md) *(Default: `SNAPPY`)* |` + +Check the [godoc for full details](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag/exporter/gcstorageexporter). diff --git a/website/versioned_docs/version-v1.13.0/go_module/data_collection/index.md b/website/versioned_docs/version-v1.13.0/go_module/data_collection/index.md new file mode 100644 index 00000000000..f2df3328876 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/data_collection/index.md @@ -0,0 +1,138 @@ +--- +sidebar_position: 0 +--- + +# Export data + +If you want to export data about how your flag are used, you can use the **`DataExporter`**. +It collects all the variations events and can save these events on several locations: + +- [File](file.md) *- create local files with the variation usages.* +- [Log](log.md) *- use your logger to write the variation usages.* +- [S3](s3.md) *- export your variation usages to S3.* +- [Webhook](webhook.md) *- export your variation usages by calling a webhook.* +- [Google Cloud Storage](google_cloud_storage.md) *- export your variation usages by calling a webhook.* + +If the existing exporter does not work with your system you can extend the system and use a [custom exporter](custom.md). + +## Data format + +Currently, we are supporting only feature events. +It represents individual flag evaluations and are considered "full fidelity" events. + +### Example + +```json linenums="1" +{ + "kind": "feature", + "contextKind": "anonymousUser", + "userKey": "ABCD", + "creationDate": 1618228297, + "key": "test-flag", + "variation": "Default", + "value": false, + "default": false +} +``` + +### Configuration fields + +| Field | Description | +|--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **`kind`** | The kind for a feature event is feature. A feature event will only be generated if the trackEvents attribute of the flag is set to true. | +| **`contextKind`** | The kind of context which generated an event. This will only be "**anonymousUser**" for events generated on behalf of an anonymous user or the reserved word "**user**" for events generated on behalf of a non-anonymous user | +| **`userKey`** | The key of the user object used in a feature flag evaluation. | +| **`creationDate`** | When the feature flag was requested at Unix epoch time in milliseconds. | +| **`key`** | The key of the feature flag requested. | +| **`variation`** | The variation of the flag requested. Available values are:
**True**: if the flag was evaluated to True
**False**: if the flag was evaluated to False
**Dafault**: if the flag was evaluated to Default
**SdkDefault**: if something wrong happened and the SDK default value was used. | +| **`value`** | The value of the feature flag returned by feature flag evaluation. | +| **`default`** | (Optional) This value is set to true if feature flag evaluation failed, in which case the value returned was the default value passed to variation. | + +Events are collected and send in bulk to avoid spamming your exporter *(see details in [how to configure data export](#how-to-configure-data-export)*) + +## How to configure data export? + +In your `ffclient.Config` add the `DataExporter` field and configure your export location. + +To avoid spamming your location everytime you have a variation called, `go-feature-flag` is storing in memory all the events and send them in bulk to the exporter. +You can decide the threshold on when to send the data with the properties `FlushInterval` and `MaxEventInMemory`. The first threshold hit will export the data. + +If there are some flags you don't want to export, you can use `trackEvents` fields on these specific flags to disable the data export *(see [flag file format](../../configure_flag/flag_format.mdx))*. + +### Example + +```go linenums="1" +ffclient.Config{ + // ... + DataExporter: ffclient.DataExporter{ + FlushInterval: 10 * time.Second, + MaxEventInMemory: 1000, + Exporter: &fileexporter.Exporter{ + OutputDir: "/output-data/", + }, + }, + // ... +} +``` + +### Configuration fields + +| Field | | Description | +|--------------------|----------------------------------------------------------------------------------------------------------------------------------------|-------------| +| `Exporter` | The configuration of the exporter you want to use. All the exporters are available in the `exporter` package. | +| `FlushInterval` | *(optional)*
Time to wait before exporting the data.
**Default: 60 seconds**. | +| `MaxEventInMemory` | *(optional)*
If `MaxEventInMemory` is reach before the `FlushInterval` a intermediary export will be done
**Default: 100000**. | + +## Don't track a flag + +By default, all flags are trackable, and their data are exported. + +If you want to exclude a specific flag from the data export, you can set the property `trackEvents` to `false` on your flag, and you will have no export for it. + +### YAML + +```yaml +test-flag: + percentage: 50 + true: "B" + false: "A" + default: "Default" + trackEvents: false +``` + +### JSON + +
+ JSON example + +```json +{ + "test-flag": { + "percentage": 50, + "true": "B", + "false": "A", + "default": "Default", + # highlight-next-line + "trackEvents": false + } +} +``` + +
+ +### TOML + +
+ TOML example + +```toml +[test-flag] +percentage = 50.0 +true = "B" +false = "A" +default = "Default" +# highlight-next-line +trackEvents = false +``` + +
diff --git a/website/versioned_docs/version-v1.13.0/go_module/data_collection/log.md b/website/versioned_docs/version-v1.13.0/go_module/data_collection/log.md new file mode 100644 index 00000000000..f4eec1f0ff1 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/data_collection/log.md @@ -0,0 +1,30 @@ +--- +sidebar_position: 5 +--- + +# Log Exporter +The log exporter is here mostly for backward compatibility *(originally every variation were logged, but it can be a lot of data for a default configuration)*. +It will use your logger `ffclient.Config.Logger` to log every variation changes. + +You can configure your output log with the `Format` field. +It uses a [go template](https://golang.org/pkg/text/template/) format. + +## Configuration example +```go linenums="1" +ffclient.Config{ + // ... + DataExporter: ffclient.DataExporter{ + Exporter: &logsexporter.Exporter{ + LogFormat: "[{{ .FormattedDate}}] user=\"{{ .UserKey}}\", flag=\"{{ .Key}}\", value=\"{{ .Value}}\"", + }, + }, + // ... +} +``` + +## Configuration fields +| Field | Description | +|-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `LogFormat` | *(optional)*
LogFormat is the [template](https://golang.org/pkg/text/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.

**Default: `[{{ .FormattedDate}}] user="{{ .UserKey}}", flag="{{ .Key}}", value="{{ .Value}}"`** | + +Check the [godoc for full details](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag/exporter/logsexporter). diff --git a/website/versioned_docs/version-v1.13.0/go_module/data_collection/s3.md b/website/versioned_docs/version-v1.13.0/go_module/data_collection/s3.md new file mode 100644 index 00000000000..4a9fa3aba01 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/data_collection/s3.md @@ -0,0 +1,53 @@ +--- +sidebar_position: 1 +--- + +# S3 Exporter + +The **S3 exporter** will collect the data and create a new file in a specific folder everytime we send the data. + +Everytime the `FlushInterval` or `MaxEventInMemory` is reached a new file will be added to S3. + +:::info +If for some reason the S3 upload failed, we will keep the data in memory and retry to add the next time we reach `FlushInterval` or `MaxEventInMemory`. +::: + +![export in S3 screenshot](/docs/data_collection/s3-exporter.png) + + +Check this [complete example](https://github.com/thomaspoignant/go-feature-flag/tree/main/examples/data_export_s3) to see how to export the data in S3. + +## Configuration example +```go +ffclient.Config{ + // ... + DataExporter: ffclient.DataExporter{ + // ... + Exporter: &s3exporter.Exporter{ + Format: "csv", + FileName: "flag-variation-{{ .Hostname}}-{{ .Timestamp}}.{{ .Format}}", + CsvTemplate: "{{ .Kind}};{{ .ContextKind}};{{ .UserKey}};{{ .CreationDate}};{{ .Key}};{{ .Variation}};{{ .Value}};{{ .Default}}\n", + Bucket: "my-bucket", + S3Path: "/go-feature-flag/variations/", + Filename: "flag-variation-{{ .Timestamp}}.{{ .Format}}", + AwsConfig: &aws.Config{ + Region: aws.String("eu-west-1"), + }, + }, + }, + // ... +} +``` + +## Configuration fields +| Field | Description | +|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `Bucket ` | Name of your S3 Bucket. | +| `AwsConfig ` | An instance of `aws.Config` that configure your access to AWS *(see [this documentation for more info](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html))*. | +| `CsvTemplate` | *(optional)* CsvTemplate 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](https://github.com/thomaspoignant/go-feature-flag/blob/main/internal/exporter/feature_event.go) to see what are the fields available.
**Default:** `{{ .Kind}};{{ .ContextKind}};{{ .UserKey}};{{ .CreationDate}};{{ .Key}};{{ .Variation}};{{ .Value}};{{ .Default}}\n` | +| `Filename` | *(optional)* Filename is the name of your output file. You can use a templated config to define the name of your exported files.
Available replacement are `{{ .Hostname}}`, `{{ .Timestamp}`} and `{{ .Format}}`
Default: `flag-variation-{{ .Hostname}}-{{ .Timestamp}}.{{ .Format}}` | +| `Format` | *(optional)* Format is the output format you want in your exported file. Available format are **`JSON`**, **`CSV`**, **`Parquet`**. *(Default: `JSON`)* | +| `S3Path ` | *(optional)* The location of the directory in S3. | +| `ParquetCompressionCodec` | *(optional)* ParquetCompressionCodec is the parquet compression codec for better space efficiency. [Available options](https://github.com/apache/parquet-format/blob/master/Compression.md) *(Default: `SNAPPY`)* |` + +Check the [godoc for full details](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag/exporter/s3exporter). diff --git a/website/versioned_docs/version-v1.13.0/go_module/data_collection/webhook.md b/website/versioned_docs/version-v1.13.0/go_module/data_collection/webhook.md new file mode 100644 index 00000000000..4578f85712d --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/data_collection/webhook.md @@ -0,0 +1,73 @@ +--- +sidebar_position: 4 +--- + +# Webhook Exporter + +The **Webhook exporter** will collect the data and send them via an HTTP POST request to the specified endpoint. +Everytime the `FlushInterval` or `MaxEventInMemory` is reached a new call is performed. + +!!! Info + If for some reason the call failed, we will keep the data in memory and retry to add the next time we reach `FlushInterval` or `MaxEventInMemory`. + +## Configuration example +```go linenums="1" +ffclient.Config{ + // ... + DataExporter: ffclient.DataExporter{ + // ... + Exporter: &webhookexporter.Exporter{ + EndpointURL: " https://webhook.url/", + Secret: "secret-for-signing", + Meta: map[string]string{ + "extraInfo": "info", + }, + Headers: map[string][]string{ + "Authorization": {"Bearer auth_token"}, + }, + }, + }, + // ... +} +``` +## Configuration fields +| Field | Description | +|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `EndpointURL ` | EndpointURL of your webhook | +| `Secret ` | *(optional)*
Secret used to sign your request body and fill the `X-Hub-Signature-256` header.
See [signature section](#signature) for more details. | +| `Meta` | *(optional)*
Add all the information you want to see in your request. | +| `Headers` | *(optional)*
the list of Headers to send to the endpoint | + + +## Webhook format +If you have configured a webhook, a `POST` request will be sent to the `EndpointURL` with a body in this format: + +```json +{ + "meta": { + "hostname": "server01", + // ... + }, + "events": [ + { + "kind": "feature", + "contextKind": "anonymousUser", + "userKey": "14613538188334553206", + "creationDate": 1618909178, + "key": "test-flag", + "variation": "Default", + "value": false, + "default": false + }, + // ... + ] +} +``` + +## Signature +This header **`X-Hub-Signature-256`** is sent if the webhook is configured with a **`secret`**. +This is the **HMAC hex digest** of the request body, and is generated using the **SHA-256** hash function and the **secret as the HMAC key**. + +:::caution +The recommendation is to always use the `Secret` and on your API/webhook always verify the signature key to be sure that you don't have a man in the middle attack. +::: diff --git a/website/versioned_docs/version-v1.13.0/go_module/notifier/_category_.json b/website/versioned_docs/version-v1.13.0/go_module/notifier/_category_.json new file mode 100644 index 00000000000..69bc4e31aa2 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/notifier/_category_.json @@ -0,0 +1,5 @@ +{ + "position": 50, + "collapsible": true, + "collapsed": true +} diff --git a/website/versioned_docs/version-v1.13.0/go_module/notifier/custom.md b/website/versioned_docs/version-v1.13.0/go_module/notifier/custom.md new file mode 100644 index 00000000000..f8e2ebcde23 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/notifier/custom.md @@ -0,0 +1,24 @@ +--- +sidebar_position: 30 +--- + +# Custom Notifier + +To create a custom notifier you must have a `struct` that implements the +[`notifier.Notifier`](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag/notifier/notifier) interface. + +In parameter you will receive a `notifier.DiffCache` struct that will tell you what has changed in your flag configuration. + +```go +import ( + ffclient "github.com/thomaspoignant/go-feature-flag" + "github.com/thomaspoignant/go-feature-flag/notifier/notifier" + "sync" +) + +type Notifier struct{} +func (c *Notifier) Notify(diff notifier.DiffCache) error { + // ... + // do whatever you want here +} +``` diff --git a/website/versioned_docs/version-v1.13.0/go_module/notifier/index.md b/website/versioned_docs/version-v1.13.0/go_module/notifier/index.md new file mode 100644 index 00000000000..3cad29c1332 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/notifier/index.md @@ -0,0 +1,17 @@ +--- +sidebar_position: 1 +--- + +# Notify flag changes +If you want to be informed when a flag has changed, you can configure a [**notifier**](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag#NotifierConfig). + +A notifier will send one notification to the targeted system to inform them that a new flag configuration has been loaded. + +:::info +`go-feature-flag` can handle more than one notifier at a time. +::: + +Available notifiers are: + +- [Slack](slack.md) - Get a slack message with the changes. +- [Webhook](webhook.md) - Call an API with the changes. diff --git a/website/versioned_docs/version-v1.13.0/go_module/notifier/slack.md b/website/versioned_docs/version-v1.13.0/go_module/notifier/slack.md new file mode 100644 index 00000000000..8ff6b890ba8 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/notifier/slack.md @@ -0,0 +1,33 @@ +--- +sidebar_position: 1 +--- + +# Slack Notifier +The **Slack** notifier allows you to get notification on your favorite slack channel when an instance of `go-feature-flag` is detecting changes in the configuration file. + +
+ +## Configure Slack Notification +1. First, you need to create an incoming webhook on your slack instance. + *You can follow this [documentation to see how to do it](https://api.slack.com/messaging/webhooks#getting_started)* +2. Copy your webhook URL. + It should look like: `https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX`. +3. In your init method add a slack notifier + +```go linenums="1" hl_lines="5" +ffclient.Config{ + // ... + Notifiers: []notifier.Notifier{ + &slacknotifier.Notifier{ + SlackWebhookURL: "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX", + }, + // ... + }, +} +``` + +### Configuration fields + +| Field | Description | +|---|---| +|`SlackWebhookURL` | The complete URL of your incoming webhook configured in Slack. | diff --git a/website/versioned_docs/version-v1.13.0/go_module/notifier/webhook.md b/website/versioned_docs/version-v1.13.0/go_module/notifier/webhook.md new file mode 100644 index 00000000000..432af5126bc --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/notifier/webhook.md @@ -0,0 +1,114 @@ +--- +sidebar_position: 2 +--- + +# Webhook Notifier +The **Webhook notifier** will perform an HTTP POST request to the specified endpoint everytime that a change in the flags is detected. + +The format of the call is specified in the [format section](#format) and, you can [sign the body](#signature) to trust the data you are receiving. + +## Configure the webhook notifier + +```go +ffclient.Config{ + // ... + Notifiers: []notifier.Notifier{ + &webhooknotifier.Notifier{ + EndpointURL: " https://example.com/hook", + Secret: "Secret", + Meta: map[string]string{ + "app.name": "my app", + }, + Headers: map[string][]string{ + "Authorization": {"Bearer auth_token"}, + }, + }, + // ... + }, +} +``` + +## Configuration fields +| Field | Description | +|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `EndpointURL` | The complete URL of your API *(we will send a POST request to this URL, [see format](#format))* | +| `Secret` | *(optional)*
A secret key you can share with your webhook. We will use this key to sign the request *(see [signature section](#signature) for more details)*. | +| `Meta` | *(optional)*
A list of key value that will be add in your request, this is super useful if you want to add information on the current running instance of your app.

**By default the hostname is always added in the meta information.** | +| `Headers` | *(optional)*
the list of Headers to send to the endpoint | + +## Format +If you have configured a webhook, a `POST` request will be sent to the `EndpointURL` with a body in this format: + +```json +{ + "meta": { + "hostname": "server01", + // ... + }, + "flags": { + "deleted": {}, // map of your deleted flags + "added": {}, // map of your added flags + "updated": { + "flag-name": { // an object that contains old and new value + "old_value": {}, + "new_value": {} + } + } + } +} +``` + +### Example + +```json +{ + "meta":{ + "hostname": "server01" + }, + "flags":{ + "deleted": { + "test-flag": { + "rule": "key eq \"random-key\"", + "percentage": 100, + "true": true, + "false": false, + "default": false + } + }, + "added": { + "test-flag3": { + "percentage": 5, + "true": "test", + "false": "false", + "default": "default" + } + }, + "updated": { + "test-flag2": { + "old_value": { + "rule": "key eq \"not-a-key\"", + "percentage": 100, + "true": true, + "false": false, + "default": false + }, + "new_value": { + "disable": true, + "rule": "key eq \"not-a-key\"", + "percentage": 100, + "true": true, + "false": false, + "default": false + } + } + } + } +} +``` + +## Signature +This header **`X-Hub-Signature-256`** is sent if the webhook is configured with a secret. This is the HMAC hex digest of the request body, and is generated using the SHA-256 hash function and the secret as the HMAC key. + +:::caution +The recommendation is to always use the `Secret` and on your API/webook always verify the signature key to be sure that you don't have a man in the middle attack. +::: diff --git a/website/versioned_docs/version-v1.13.0/go_module/store_file/_category_.json b/website/versioned_docs/version-v1.13.0/go_module/store_file/_category_.json new file mode 100644 index 00000000000..5a330427a1b --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/store_file/_category_.json @@ -0,0 +1,5 @@ +{ + "position": 30, + "collapsible": true, + "collapsed": true +} diff --git a/website/versioned_docs/version-v1.13.0/go_module/store_file/custom.md b/website/versioned_docs/version-v1.13.0/go_module/store_file/custom.md new file mode 100644 index 00000000000..6ccd49273e6 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/store_file/custom.md @@ -0,0 +1,18 @@ +--- +sidebar_position: 30 +--- + +# Custom Retriever + +To create a custom retriever you must have a `struct` that implements the [`Retriever`](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag/retriever/#Retriever) interface. + +```go linenums="1" +type Retriever interface { + Retrieve(ctx context.Context) ([]byte, error) +} +``` + +The `Retrieve` function is supposed to load the file and to return a `[]byte` of your flag configuration file. + +You can check existing `Retriever` *([file](https://github.com/thomaspoignant/go-feature-flag/blob/main/retriever/fileretriever/retriever.go), +[s3](https://github.com/thomaspoignant/go-feature-flag/blob/main/retriever/s3retriever/retriever.go), ...)* to have an idea on how to do build your own. diff --git a/website/versioned_docs/version-v1.13.0/go_module/store_file/file.md b/website/versioned_docs/version-v1.13.0/go_module/store_file/file.md new file mode 100644 index 00000000000..0add1570e13 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/store_file/file.md @@ -0,0 +1,31 @@ +--- +sidebar_position: 7 +--- + +# File +The [**File Retriever**](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag/retriever/fileretriever/#Retriever) will read a local file to get your flags. + +:::tip +Using a file to store your flags is not recommend, except if it is in a shared folder for all your services. +::: + +## Example +```go linenums="1" +import "github.com/thomaspoignant/go-feature-flag/retriever/file" +// ... + +err := ffclient.Init(ffclient.Config{ + PollingInterval: 3 * time.Second, + Retriever: &fileretriever.Retriever{ + Path: "file-example.yaml", + }, +}) +defer ffclient.Close() +``` + +## Configuration fields +To configure your File retriever: + +| Field | Description | +|---|---| +|**`Path`**| location of your file on the file system.| diff --git a/website/versioned_docs/version-v1.13.0/go_module/store_file/github.md b/website/versioned_docs/version-v1.13.0/go_module/store_file/github.md new file mode 100644 index 00000000000..d405d6eb982 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/store_file/github.md @@ -0,0 +1,39 @@ +--- +sidebar_position: 6 +--- + +# Github + +The [**Github Retriever**](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag/retriever/githubretriever/#Retriever) +will perform an HTTP Request with your GitHub configuration to get your flags. + +!!! Tip + GitHub has rate limits, be sure to correctly set your `PollingInterval` to avoid reaching the limit. + +## Example + +```go linenums="1" +err := ffclient.Init(ffclient.Config{ + PollingInterval: 3 * time.Second, + Retriever: &githubretriever.Retriever{ + RepositorySlug: "thomaspoignant/go-feature-flag", + Branch: "main", + FilePath: "testdata/flag-config.yaml", + GithubToken: "XXXX", + Timeout: 2 * time.Second, + }, +}) +defer ffclient.Close() +``` + +## Configuration fields + +To configure the access to your GitHub file: + +| Field | Description | +|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **`RepositorySlug`** | Your GitHub slug `org/repo-name`. | +| **`FilePath`** | The path of your file. | +| **`Branch`** | *(optional)*
The branch where your file is.
Default: `main` | +| **`GithubToken`** | *(optional)*
Github token is used to access a private repository, you need the `repo` permission *([how to create a GitHub token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token))*. | +| **`Timeout`** | *(optional)*
Timeout for the HTTP call
Default: 10 seconds | diff --git a/website/versioned_docs/version-v1.13.0/go_module/store_file/gitlab.md b/website/versioned_docs/version-v1.13.0/go_module/store_file/gitlab.md new file mode 100644 index 00000000000..22ebed9597e --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/store_file/gitlab.md @@ -0,0 +1,41 @@ +--- +sidebar_position: 6 +--- + +# GitLab + +The [**Gitlab Retriever**](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag/retriever/gitlabretriever/#Retriever) +will perform an HTTP Request to the Gitlab API to get your flags. + +!!! Tip + Gitlab has rate limits, be sure to correctly set your `PollingInterval` to avoid reaching the limit. + +## Example + +```go linenums="1" +err := ffclient.Init(ffclient.Config{ + PollingInterval: 3 * time.Second, + Retriever: &gitlab.Retriever{ + RepositorySlug: "thomaspoignant/go-feature-flag", + Branch: "main", + FilePath: "testdata/flag-config.yaml", + GitlabToken: "XXXX", + Timeout: 2 * time.Second, + BaseURL: "https://gitlab.com", + }, +}) +defer ffclient.Close() +``` + +## Configuration fields + +To configure the access to your GitLab file: + +| Field | Description | +|----------------------|-------------------------------------------------------------------------------------------| +| **`BaseURL`** | *(optional)*
The domain name of your Gitlab instance
Default: https://gitlab.com | +| **`RepositorySlug`** | Your Gitlab slug `org/repo-name`. | +| **`FilePath`** | The path of your file. | +| **`Branch`** | *(optional)*
The branch where your file is.
Default: `main` | +| **`GitlabToken`** | *(optional)*
Gitlab token is used to access a private repository | +| **`Timeout`** | *(optional)*
Timeout for the HTTP call
Default: 10 seconds | diff --git a/website/versioned_docs/version-v1.13.0/go_module/store_file/google_cloud_storage.md b/website/versioned_docs/version-v1.13.0/go_module/store_file/google_cloud_storage.md new file mode 100644 index 00000000000..68ff4f9d171 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/store_file/google_cloud_storage.md @@ -0,0 +1,34 @@ +--- +sidebar_position: 5 +--- + +# Google Cloud Storage + +The [**Google Cloud Storage Retriever**](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag/retriever/gcstorageretriever/#Retriever) +will use the [google-cloud-storage package](https://pkg.go.dev/cloud.google.com/go/storage) +and [google-api-options package](https://pkg.go.dev/google.golang.org/api/option) to access your flag in Google Cloud +Storage. + +## Example + +```go +err := ffclient.Init(ffclient.Config{ + PollingInterval: 3 * time.Second, + Retriever: &gcstorageretriever.Retriever{ + Options: []option.ClientOption{option.WithoutAuthentication()}, + Bucket: "2093u4pkasjc3", + Object: "flags.yaml", + } +}) +defer ffclient.Close() +``` + +## Configuration fields + +To configure your Google Cloud Storage file location: + +| Field | Description | +|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **`Bucket`** | The name of your bucket. | +| **`Object`** | The name of your object in your bucket. | +| **`Option`** | An instance of `option.ClientOption` that configures your access to Google Cloud.
Check [this documentation for more info](https://cloud.google.com/docs/authentication). | diff --git a/website/versioned_docs/version-v1.13.0/go_module/store_file/http.md b/website/versioned_docs/version-v1.13.0/go_module/store_file/http.md new file mode 100644 index 00000000000..1fe7e3108d8 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/store_file/http.md @@ -0,0 +1,33 @@ +--- +sidebar_position: 2 +--- + +# HTTP endpoint + +The [__HTTP Retriever__](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag/retriever/httpretriever/#Retriever) +will perform an HTTP Request with your configuration to get your flags. + +## Example + +```go linenums="1" +err := ffclient.Init(ffclient.Config{ + PollingInterval: 3 * time.Second, + Retriever: &httpretriever.Retriever{ + URL: "http://example.com/flag-config.yaml", + Timeout: 2 * time.Second, + }, +}) +defer ffclient.Close() +``` + +## Configuration fields + +To configure your HTTP endpoint: + +| Field | Description | +|---------------|-----------------------------------------------------------------------------------------------------------------| +| __`URL`__ | Location where to retrieve the file
_(ex: [http://mydomain.io/flag.yaml](http://mydomain.io/flag.yaml))_. | +| __`Method`__ | the HTTP method you want to use
_(default is GET)_. | +| __`Body`__ | _(optional)_
If you need a body to get the flags. | +| __`Header`__ | _(optional)_
Header you should pass while calling the endpoint _(useful for authorization)_. | +| __`Timeout`__ | _(optional)_
Timeout for the HTTP call
(default is 10 seconds). | diff --git a/website/versioned_docs/version-v1.13.0/go_module/store_file/index.md b/website/versioned_docs/version-v1.13.0/go_module/store_file/index.md new file mode 100644 index 00000000000..8db45406746 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/store_file/index.md @@ -0,0 +1,18 @@ +--- +sidebar_position: 1 +--- + +# Retrieve your feature flags configuration +The module supports different ways of retrieving the flag file. +Available retriever are: + +- [S3 Bucket](./s3.md) +- [HTTP endpoint](./http.md) +- [Github](./github.md) +- [Gitlab](./gitlab.md) +- [File](./file.md) +- [Kubernetes configmap](./kubernetes_configmaps.md) +- [Google Cloud storage](./google_cloud_storage.md) + +To retrieve a file you need to provide a [retriever](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag/retriever/#Retriever) in your `ffclient.Config{}` during the initialization. +If the existing retriever does not work with your system you can extend the system and use a [custom retriever](custom.md). diff --git a/website/versioned_docs/version-v1.13.0/go_module/store_file/kubernetes_configmaps.md b/website/versioned_docs/version-v1.13.0/go_module/store_file/kubernetes_configmaps.md new file mode 100644 index 00000000000..f086b8bb42a --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/store_file/kubernetes_configmaps.md @@ -0,0 +1,47 @@ +--- +sidebar_position: 4 +--- + +# Kubernetes configmaps +A ConfigMap is an API object used to store non-confidential data in key-value pairs inside kubernetes. +GO Feature Flag can read directly in a configmap in your namespace. + +The [**Kubernetes Retriever**](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag/retriever/k8sretriever/#Retriever) +will access flags in a Kubernetes ConfigMap via the [Kubernetes Go client](https://github.com/kubernetes/client-go) + + +## Add your config file as configmap + +```shell +kubectl create configmap goff --from-file=examples/retriever_configmap/flags.yaml +``` + +## Configuration Example +```go linenums="1" +import ( + restclient "k8s.io/client-go/rest" +) + +config, _ := restclient.InClusterConfig() +err = ffclient.Init(ffclient.Config{ + PollingInterval: 3 * time.Second, + Retriever: &k8sretriever.Retriever{ + Path: "file-example.yaml", + Namespace: "default" + ConfigMapName: "my-configmap" + Key: "somekey.yml" + ClientConfig: &config + }, +}) +defer ffclient.Close() +``` + +## Configuration fields +To configure your retriever: + +| Field | Description | +|---------------------|----------------------------------------------------| +| **`Namespace`** | The namespace of the ConfigMap. | +| **`ConfigMapName`** | The name of the ConfigMap. | +| **`Key`** | The key within the ConfigMap storing the flags. | +| **`ClientConfig`** | The configuration object for the Kubernetes client | diff --git a/website/versioned_docs/version-v1.13.0/go_module/store_file/s3.md b/website/versioned_docs/version-v1.13.0/go_module/store_file/s3.md new file mode 100644 index 00000000000..3f40b3a0850 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/store_file/s3.md @@ -0,0 +1,30 @@ +--- +sidebar_position: 3 +--- + +# S3 Bucket +The [**S3Retriever**](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag/retriever/s3retriever/#Retriever) will use the [aws-sdk](https://github.com/aws/aws-sdk-go) to access your flag in an S3 bucket. + +## Example +```go linenums="1" +err := ffclient.Init(ffclient.Config{ + PollingInterval: 3 * time.Second, + Retriever: &s3retriever.Retriever{ + Bucket: "tpoi-test", + Item: "flag-config.yaml", + AwsConfig: aws.Config{ + Region: aws.String("eu-west-1"), + }, + }, +}) +defer ffclient.Close() +``` + +## Configuration fields +To configure your S3 file location: + +| Field | Description | +|---|---| +|**`Bucket`**| The name of your bucket.| +|**`Item`**| The location of your file in the bucket.| +|**`AwsConfig`**| An instance of `aws.Config` that configure your access to AWS
*check [this documentation for more info](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html)*.| diff --git a/website/versioned_docs/version-v1.13.0/go_module/target_user.md b/website/versioned_docs/version-v1.13.0/go_module/target_user.md new file mode 100644 index 00000000000..7caeeb7baa1 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/go_module/target_user.md @@ -0,0 +1,187 @@ +--- +sidebar_position: 20 +description: How to select who should have the flag activated. +--- +# Performing flag evaluations + +## Users +Feature flag targeting and rollouts are all determined by the user you pass to your **Variation** calls. +The SDK defines a [`User`](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag/ffuser#User) struct and a [`UserBuilder`](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag/ffuser#UserBuilder) to make this easy. + +Here's an example: + +```go linenums="1" +// User with only a key +user1 := ffcontext.NewEvaluationContext("user1-key") + +// User with a key plus other attributes +user2 = ffcontext.NewEvaluationContextBuilder("user2-key"). + AddCustom("firstname", "John"). + AddCustom("lastname", "Doe"). + AddCustom("email", "john.doe@example.com"). + Build() +``` + +The most common attribute is the user's key and **this is the only mandatory user attribute.** +The key should also uniquely identify each user. You can use a primary key, an e-mail address, or a hash, as long as the same user always has the same key. +**We recommend using a hash if possible.** +All the other attributes are optional. + +:::info +Custom attributes are one of the most powerful features. +They let you have rules on these attributes and target users according to any data that you want. +::: + +## Anonymous users +You can also distinguish logged-in users from anonymous users in the SDK, as follows: + +```go linenums="1" +// User with only a key +user1 := ffcontext.NewAnonymousEvaluationContext("user1-key") + +// User with a key plus other attributes +user2 = ffcontext.NewEvaluationContextBuilder("user2-key"). + Anonymous(true). + AddCustom("firstname", "John"). + AddCustom("lastname", "Doe"). + AddCustom("email", "john.doe@example.com"). + Build() +``` +You will still need to generate a unique key for anonymous users. Session IDs or UUIDs work best for this. + +Anonymous users work just like regular users, this information just helps you to add a rule to target a specific population. + +## Variation +The Variation methods determine whether a flag is enabled or not for a specific user. +There is a Variation method for each type: +[`BoolVariation`](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag#BoolVariation) , [`IntVariation`](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag#IntVariation) +, [`Float64Variation`](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag#Float64Variation) +, [`StringVariation`](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag#StringVariation) +, [`JSONArrayVariation`](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag#JSONArrayVariation) +, [`JSONVariation`](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag#JSONVariation) + +```go linenums="1" +result, _ := ffclient.BoolVariation("your.feature.key", user, false) + +// result is now true or false depending on the setting of +// this boolean feature flag +``` +Variation methods take the feature **flag key**, a **user**, and a **default value**. + +The default value is return when an error is encountered _(`ffclient` not initialized, variation with wrong type, flag does not exist ...)._ + +In the example, if the flag `your.feature.key` does not exists, result will be `false`. +Not that you will always have a usable value in the result. + +## Variation details +If you want more information about your flag evaluation, you can use the variation details functions. +There is a Variation method for each type: +[`BoolVariationDetails`](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag#BoolVariationDetails) +, [`IntVariation`](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag#IntVariationDetails) +, [`Float64VariationDetails`](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag#Float64VariationDetails) +, [`StringVariationDetails`](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag#StringVariationDetails) +, [`JSONArrayVariationDetails`](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag#JSONArrayVariationDetails) +, [`JSONVariationDetails`](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag#JSONVariationDetails) + +You can use these functions the same way as the other variation functions BUT it will return a generic object `model.VariationResult[]` containing your result. +This object will contain these fields: + +| field | type | description | +|-----------------|-------------------------|--------------------------------------------------------------------------------| +| `TrackEvents` | `bool` | `true` if this evaluation was tracked. | +| `VariationType` | `string` | The name of the variation used to get this value. | +| `Failed` | `bool` | `true` if an error occurred during the evaluation. | +| `Version` | `string` | The **version** of the flag used to do the evaluation. | +| `Reason` | `flag.ResolutionReason` | The reason used for this evaluation. | +| `ErrorCode` | `flag.ErrorCode` | Error code in case we have an error. | +| `Value` | `` | Value of the flag in the expected type. | +| `Cacheable` | `bool` | `true` if it can be cached (by user or for everyone depending on the reason). | + + +### Reason +GO Feature Flag can furnish you with diverse reasons in the variation details, giving you insight into the evaluation process of your feature flag. +Here is the full list of reason available: + +| Reason | description | +|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `TARGETING_MATCH` | The resolved value was the result of a dynamic evaluation, such as a rule or specific user-targeting. _(ex: serve variation A if username is Thomas)_ | +| `TARGETING_MATCH_SPLIT` | The resolved value was the result of a dynamic evaluation, that is serving a percentage. _(ex: serve variation A to 10% of users with the username Thomas)_ | +| `SPLIT` | The resolved value was the result of pseudorandom assignment. _(ex: serve variation A to 10% of all the users.)_ | +| `DISABLED` | Indicates that the feature flag is disabled | +| `DEFAULT` | The resolved value was the result of the flag being disabled in the management system. | +| `STATIC` | Indicates that the feature flag evaluated to a static value, for example, the default value for the flag. _(Note: Typically means that no dynamic evaluation has been executed for the feature flag)_ | +| `UNKNOWN` | Indicates an unknown issue occurred during evaluation | +| `ERROR` | Indicates that an error occurred during evaluation *(Note: The `errorCode` field contains the details of this error)* | +| `OFFLINE` | Indicates that GO Feature Flag is currently evaluating in offline mode. | + + +## Get all flags for a specific user +If you want to send the information about a specific user to a front-end, you will want a snapshot of all the flags for +this user at a specific time. + +The method `ffclient.AllFlagsState` returns a snapshot of flag values and metadata. +The function is evaluating all available flags for the user and return a `flagstate.AllFlagsState` object containing the +information you need. + +```go linenums="1" +user := ffcontext.NewEvaluationContext("example") +// AllFlagsState will give you the value for all the flags available. +allFlagsState := ffclient.AllFlagsState(u) + +// If you want to send it to a front-end you can Marshal it by calling MarshalJSON() +forFE, err := allFlagsState.MarshalJSON() +``` + +The `MarshalJSON()` function will return something like bellow, that can be directly used by your front-end application. +```json linenums="1" +{ + "flags": { + "test-flag0": { + "value": true, + "timestamp": 1622209328, + "variationType": "True", + "trackEvents": true + }, + "test-flag1": { + "value": "true", + "timestamp": 1622209328, + "variationType": "True", + "trackEvents": true + }, + "test-flag2": { + "value": 1, + "timestamp": 1622209328, + "variationType": "True", + "trackEvents": true + }, + "test-flag3": { + "value": [ + "yo", + "ya" + ], + "timestamp": 1622209328, + "variationType": "True", + "trackEvents": true + }, + "test-flag4": { + "value": { + "test": "yo" + }, + "timestamp": 1622209328, + "variationType": "True", + "trackEvents": true + }, + "test-flag5": { + "value": 1.1, + "timestamp": 1622209328, + "variationType": "True", + "trackEvents": false + } + }, + "valid": true +} +``` + +:::caution +There is no tracking done when evaluating all the flag at once. +::: diff --git a/website/versioned_docs/version-v1.13.0/index.md b/website/versioned_docs/version-v1.13.0/index.md new file mode 100644 index 00000000000..3103b556a06 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/index.md @@ -0,0 +1,37 @@ +--- +title: Home +description: go-feature-flag is a simple and complete feature flag solution, without any complex backend system to install. You need only a file as your backend. +sidebar_position: 1 +--- + +

+ go-feature-flag logo +

+ +## What is GO Feature Flag? +GO Feature Flag is a simple, complete and lightweight feature flag solution 100% opensource. + +The solution has been built to start experiencing the usage of feature flags in your code without having to contract with any vendor. + +**GO Feature Flag** has started to be a solution only for the GO language, but with the new standardisation of feature flags by [Openfeature](https://openfeature.dev/) project, +now the solution is available for multiple languages _(`JAVA`, `typescript`, `javascript`, ...)_ with a simple server to host. + +:::info +If you are not familiar with feature flags, also called feature toggles, you can read this [article from Martin Fowler](https://www.martinfowler.com/articles/feature-toggles.html) +where he explains why this is a great pattern. + +I've also written an [article](https://medium.com/better-programming/feature-flags-and-how-to-iterate-quickly-7e3371b9986) which explains why feature flags can fasten your iteration cycle. +::: + +## What can I do with GO Feature Flag? + +- Storing your configuration flags file on various locations (`HTTP`, `S3`, `Kubernetes`, [_see full list_](configure_flag/store_your_flags.mdx)). +- Configuring your flags in various [format](configure_flag/flag_format.mdx) (`JSON`, `TOML` and `YAML`). +- Adding complex [rules](configure_flag/flag_format.mdx#rule-format) to target your users. +- Use complex rollout strategy for your flags : + - [Run A/B testing experimentation](configure_flag/rollout/experimentation.mdx). + - [Progressively rollout a feature](configure_flag/rollout/progressive.mdx). + - [Schedule your flag updates](configure_flag/rollout/scheduled.mdx). +- Exporting your flags usage data ([`s3`](go_module/data_collection/s3.md), [`log`](go_module/data_collection/log.md), [`file`](go_module/data_collection/file.md), [_see full list_](configure_flag/export_flags_usage.mdx)). +- Getting notified when a flag has been changed ([`webhook`](go_module/notifier/webhook.md) and [`slack`](go_module/notifier/slack.md)). +- Use GO Feature Flag in several languages. diff --git a/website/versioned_docs/version-v1.13.0/linter.mdx b/website/versioned_docs/version-v1.13.0/linter.mdx new file mode 100644 index 00000000000..098c7d2896b --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/linter.mdx @@ -0,0 +1,116 @@ +--- +sidebar_position: 91 +description: Lint your config +--- + + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Lint your config + +A faulty configuration could make **GO Feature Flag** not the way you expect. +This is why we have introduced the `go-feature-flag-lint` a command line tool validates that a flags file can be parsed by **GO Feature Flag**. + +:::tip +We recommend you to use this command line in your CI/CD pipelines to avoid any disappointment. +::: + +## Install the linter + +### Install using Homebrew (mac and linux) +```shell +brew tap thomaspoignant/homebrew-tap +brew install go-feature-flag-lint +``` + +### Install using Scoop (windows) +```shell +scoop bucket add org https://github.com/go-feature-flag/scoop.git +scoop install go-feature-flag-lint +``` + +### Install using Docker +```shell +docker pull thomaspoignant/go-feature-flag-lint:latest +``` + +## Use the linter + +```shell +./go-feature-flag-lint \ + --input-format=yaml \ + --input-file=/input/my-go-feature-flag-config.yaml +``` + +The command line has 2 arguments you should specify. + +| param | description | +|------------------|-------------------------------------------------------------------------------------------------------------------| +| `--input-file` | **(mandatory)** The location of your configuration file. | +| `--input-format` | **(mandatory)** The format of your current configuration file.
Available formats are `yaml`, `json`, `toml`. | + +## Use the linter in your CI (continuous integration) + + + +You can run `go-feature-flag-lint` using GitHub actions: + + + + +```yaml +name: "Build" +on: + push: + branches: + - main + pull_request: + types: [ opened, synchronize, reopened ] + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: docker://thomaspoignant/go-feature-flag-lint:latest + with: + args: --input-file=/github/workspace/path/to/your/config.yaml --input-format=yaml +``` + + + + +```yaml +version: 2.1 +jobs: + build: + docker: + - image: cimg/base:2022.05 + + steps: + - checkout + - run: curl -L $(curl -s https://api.github.com/repos/thomaspoignant/go-feature-flag/releases/latest | jq -r '.assets[] | select(.name|match("Linux_x86_64.tar.gz$")) | .browser_download_url' | grep 'go-feature-flag-lint') --output release.tar.gz && tar -zxvf release.tar.gz + - run: ./go-feature-flag-lint --input-format=yaml --input-file=flag-config.yaml # please put the right file name +``` + + + + +```yaml +image: ubuntu +lint-job: + stage: build + + before_script: + - apt-get -qq update + - apt-get install -y jq curl + + script: + - curl -L $(curl -s https://api.github.com/repos/thomaspoignant/go-feature-flag/releases/latest | jq -r '.assets[] | select(.name|match("Linux_x86_64.tar.gz$")) | .browser_download_url' | grep 'go-feature-flag-lint') --output release.tar.gz && tar -zxvf release.tar.gz + - ./go-feature-flag-lint --input-format=yaml --input-file=flag-config.yaml # please put the right file name +``` + + + + diff --git a/website/versioned_docs/version-v1.13.0/migrate_v0_v1.md b/website/versioned_docs/version-v1.13.0/migrate_v0_v1.md new file mode 100644 index 00000000000..7dca8aed8bb --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/migrate_v0_v1.md @@ -0,0 +1,59 @@ +--- +sidebar_position: 90 +description: How to migrate from v0.x.x to v1.x.x +--- + +# Migrate from v0.x.x to v1.x.x + +:::info +Version `v1.0.0` has introduced a new flag format that push the limits of **GO Feature Flag** even further. +**BUT** the flag format from all the versions `v0.x.x` are still compatible and supported by the `v1.0.0`. +::: + +A command line is available to help you to convert your actual configuration file to the version `v1.x.x`. + + +## Install the migration command line + +### Install using Homebrew (mac and linux) +```shell +brew tap thomaspoignant/homebrew-tap +brew install go-feature-flag-migration-cli +``` + +### Install using Scoop (windows) +```shell +scoop bucket add org https://github.com/go-feature-flag/scoop.git +scoop install go-feature-flag-migration-cli +``` + +### Install using Docker +```shell +docker pull thomaspoignant/go-feature-flag-migration-cli:latest +``` + +## Use the migration command line + +```shell +./go-feature-flag-migration-cli \ + --input-format=yaml \ + --input-file=/config/my-go-feature-flag-config-v0.x.x.yaml \ + --output-format=yaml \ + --output-file=/config/my-go-feature-flag-config-v1.x.x.yaml +``` + +The command line has 4 arguments you should specify. + +- `input-format`: Format of your input file (`YAML`, `JSON` or `TOML`). +- `input-file`: Location of the flag file you want to convert. +- `output-format`: Format of your output file (`YAML`, `JSON` or `TOML`). +- `output-file`: Location of the converted flag file. + + +## Update your flag file + +When your file is ready, you just have to replace your file in the location where GO Feature Flag is retrieving it. + +:::tip +If for any reason your file is not readable by GO Feature Flag, it will not break anything, we will keep the latest version we have in memory. +::: diff --git a/website/versioned_docs/version-v1.13.0/openfeature_sdk/_category_.json b/website/versioned_docs/version-v1.13.0/openfeature_sdk/_category_.json new file mode 100644 index 00000000000..0140afc37a8 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/openfeature_sdk/_category_.json @@ -0,0 +1,10 @@ +{ + "position": 50, + "label":"Use with OpenFeature", + "collapsible": true, + "collapsed": true, + "link": { + "type": "generated-index", + "title": "Use with OpenFeature" + } +} diff --git a/website/versioned_docs/version-v1.13.0/openfeature_sdk/concepts.md b/website/versioned_docs/version-v1.13.0/openfeature_sdk/concepts.md new file mode 100644 index 00000000000..e45f35dafff --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/openfeature_sdk/concepts.md @@ -0,0 +1,33 @@ +--- +sidebar_position: 10 +description: How GO Feature Flag is working with OpenFeature. +--- + +# Concepts + +## What is OpenFeature? +:::note +OpenFeature is an open standard for feature flag management, created to support a robust feature flag ecosystem using cloud native technologies. OpenFeature provides a unified API and SDK, and a developer-first, cloud-native implementation, with extensibility for open source and commercial offerings. + +https://docs.openfeature.dev/docs/category/concepts +::: + +OpenFeature offer a framework-agnostic way of using feature flags, it means that if you use OpenFeature SDKs you will have minimum changes to do if you want to choose another provider. + +To support this initiative, **GO Feature Flag** does not have any SDKs and rely 100% on OpenFeature SDKs. +To be compatible with our solution, we offer [`providers`](https://docs.openfeature.dev/docs/reference/concepts/provider) for GO Feature Flag in several languages. + + +## How OpenFeature and GO Feature Flag are working together? + +To use the OpenFeature SDKs you need what we call a provider. +A **provider** is responsible for performing flag evaluations. It provides an abstraction between **GO Feature Flag** and the OpenFeature SDK. + +A provider need a backend service to perform the flag evaluation. This is why we have introduced the [**relay proxy**](../category/use-the-relay-proxy). +This component retrieve your feature flag configuration file using the GO module and expose APIs to get your flags variations. + +![](/docs/openfeature/concepts.jpg) + +With this simple architecture you have a central component _(the relay proxy)_ that is in charge of the flag evaluation, while the SDKs and providers are responsible to communicate with the relay proxy. + +This supports different languages the same way and makes you able to use GO Feature Flag with all your favorite languages. diff --git a/website/versioned_docs/version-v1.13.0/openfeature_sdk/openfeature_dotnet.mdx b/website/versioned_docs/version-v1.13.0/openfeature_sdk/openfeature_dotnet.mdx new file mode 100644 index 00000000000..03e1b3c1d42 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/openfeature_sdk/openfeature_dotnet.mdx @@ -0,0 +1,122 @@ +--- +sidebar_position: 52 +description: How to use the OpenFeature .Net SDK +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + +# .Net SDK usage + +## Install dependencies + +The first things we will do is install the **Open Feature SDK** and the **GO Feature Flag provider**. + + + + +```shell +dotnet add package OpenFeature.Contrib.GOFeatureFlag +``` + + + + +```shell +NuGet\Install-Package OpenFeature.Contrib.GOFeatureFlag +``` + + + + +```xml + +``` + + + + +```shell +paket add OpenFeature.Contrib.GOFeatureFlag +``` + + + + +```shell +// Install OpenFeature.Contrib.GOFeatureFlag as a Cake Addin +#addin nuget:?package=OpenFeature.Contrib.GOFeatureFlag + +// Install OpenFeature.Contrib.GOFeatureFlag as a Cake Tool +#tool nuget:?package=OpenFeature.Contrib.GOFeatureFlag +``` + + + + + +## Initialize your Open Feature client + +To evaluate the flags you need to have an Open Feature configured in you app. +This code block shows you how you can create a client that you can use in your application. + + + + +```csharp +using OpenFeature; +using OpenFeature.Contrib.GOFeatureFlag; + +// ... + +var goFeatureFlagProvider = new GoFeatureFlagProvider(new GoFeatureFlagProviderOptions +{ + Endpoint = "http://localhost:1031/", + Timeout = new TimeSpan(1000 * TimeSpan.TicksPerMillisecond) +}); +Api.Instance.SetProvider(goFeatureFlagProvider); +var client = Api.Instance.GetClient("my-app"); +``` + + + + +## Evaluate your flag + +This code block explain how you can create an `EvaluationContext` and use it to evaluate your flag. + +:::note +In this example we are evaluating a `boolean` flag, but other types are available. + +**Refer to the [Open Feature documentation](https://docs.openfeature.dev/docs/reference/concepts/evaluation-api#basic-evaluation) to know more about it.** +::: + + + + +```csharp +// Context of your flag evaluation. +// With GO Feature Flag you MUST have a targetingKey that is a unique identifier of the user. +var userContext = EvaluationContext.Builder() + .Set("targetingKey", "1d1b9238-2591-4a47-94cf-d2bc080892f1") // user unique identifier (mandatory) + .Set("firstname", "john") + .Set("lastname", "doe") + .Set("email", "john.doe@gofeatureflag.org") + .Set("admin", true) // this field is used in the targeting rule of the flag "flag-only-for-admin" + .Set("anonymous", false) + .Build(); + +var adminFlag = await client.GetBooleanValue("flag-only-for-admin", false, userContext); +if (adminFlag) { + // flag "flag-only-for-admin" is true for the user +} else { + // flag "flag-only-for-admin" is false for the user +} +``` + + + + +## Contribute to the provider +You can find the source of the provider in the [`open-feature/dotnet-sdk-contrib`](https://github.com/open-feature/dotnet-sdk-contrib/tree/main/src/OpenFeature.Contrib.Providers.GOFeatureFlag) repository. \ No newline at end of file diff --git a/website/versioned_docs/version-v1.13.0/openfeature_sdk/openfeature_go.mdx b/website/versioned_docs/version-v1.13.0/openfeature_sdk/openfeature_go.mdx new file mode 100644 index 00000000000..51b3e5dcdb9 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/openfeature_sdk/openfeature_go.mdx @@ -0,0 +1,110 @@ +--- +sidebar_position: 20 +description: How to use the OpenFeature GO SDK +--- + +# GO SDK usage + +## Install dependencies + +The first things we will do is install the **Open Feature SDK** and the **GO Feature Flag provider**. + +```shell +go get github.com/open-feature/go-sdk +go get github.com/open-feature/go-sdk-contrib/providers/go-feature-flag +``` + +## Initialize your Open Feature provider + +Despite other providers, this GO provider can be used with the **relay proxy** or used standalone +using the **GO Feature Flag module**. + +### Using the relay proxy + +If you want to use the provider with the **relay proxy** you should set the field `Endpoint` in the options. +By default it will use a default `HTTPClient` with a **timeout** configured at **10000** milliseconds. You can change +this configuration by providing your own configuration of the `HTTPClient`. + +#### Example +```go +options := gofeatureflag.ProviderOptions{ + Endpoint: "http://localhost:1031", + HTTPClient: &http.Client{ + Timeout: 1 * time.Second, + }, +} +provider, _ := gofeatureflag.NewProvider(options) +``` + +### Using the GO module _(standalone version)_ +If you want to use the provider in standalone mode using the GO module, you should set the field `GOFeatureFlagConfig` +in the options. + +You can check the [GO Feature Flag documentation website](https://docs.gofeatureflag.org) to look how to configure the +GO module. + +#### Example +```go +options := gofeatureflag.ProviderOptions{ + GOFeatureFlagConfig: &ffclient.Config{ + PollingInterval: 10 * time.Second, + Context: context.Background(), + Retriever: &fileretriever.Retriever{ + Path: "../testutils/module/flags.yaml", + }, + }, +} +provider, _ := gofeatureflag.NewProvider(options) +``` + +## Initialize your Open Feature client + +To evaluate the flags you need to have an Open Feature configured in you app. +This code block shows you how you can create a client that you can use in your application. + +```go +import ( + // ... + gofeatureflag "github.com/open-feature/go-sdk-contrib/providers/go-feature-flag/pkg" + of "github.com/open-feature/go-sdk/pkg/openfeature" +) + +// ... + +options := gofeatureflag.ProviderOptions{ + Endpoint: "http://localhost:1031", +} +provider, err := gofeatureflag.NewProvider(options) +of.SetProvider(provider) +client := of.NewClient("my-app") +``` + +## Evaluate your flag + +This code block explain how you can create an `EvaluationContext` and use it to evaluate your flag. + + +> In this example we are evaluating a `boolean` flag, but other types are available. +> +> **Refer to the [Open Feature documentation](https://docs.openfeature.dev/docs/reference/concepts/evaluation-api#basic-evaluation) to know more about it.** + +```go +evaluationCtx := of.NewEvaluationContext( + "1d1b9238-2591-4a47-94cf-d2bc080892f1", + map[string]interface{}{ + "firstname", "john", + "lastname", "doe", + "email", "john.doe@gofeatureflag.org", + "admin", true, + "anonymous", false, + }) +adminFlag, _ := client.BoolValue(context.TODO(), "flag-only-for-admin", false, evaluationCtx) +if adminFlag { + // flag "flag-only-for-admin" is true for the user +} else { + // flag "flag-only-for-admin" is false for the user +} +``` + +## Contribute to the provider +You can find the source of the provider in the [`open-feature/go-sdk-contrib`](https://github.com/open-feature/go-sdk-contrib/tree/main/providers/go-feature-flag) repository. \ No newline at end of file diff --git a/website/versioned_docs/version-v1.13.0/openfeature_sdk/openfeature_java.mdx b/website/versioned_docs/version-v1.13.0/openfeature_sdk/openfeature_java.mdx new file mode 100644 index 00000000000..57128a1511b --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/openfeature_sdk/openfeature_java.mdx @@ -0,0 +1,93 @@ +--- +sidebar_position: 40 +description: How to use the OpenFeature JAVA SDK +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# JAVA SDK usage + +## Install dependencies + +The first things we will do is install the **Open Feature SDK** and the **GO Feature Flag provider**. + + + + +```xml + + dev.openfeature + javasdk + [0,) + + + dev.openfeature.contrib.providers + go-feature-flag + [0,) + +``` + + + + +```gradle +implementation group: 'dev.openfeature', name: 'javasdk', version: '0.+' +implementation group: 'dev.openfeature.contrib.providers', name: 'go-feature-flag', version: '0.+' +``` + + + + + +## Initialize your Open Feature client +To evaluate the flags you need to have an Open Feature configured in you app. +This code block shows you how you can create a client that you can use in your application. + +```java +import dev.openfeature.contrib.providers.gofeatureflag.*; +import dev.openfeature.contrib.providers.gofeatureflag.exception.*; +import dev.openfeature.sdk.*; + +// ... + +GoFeatureFlagProviderOptions options = GoFeatureFlagProviderOptions.builder().endpoint("http://localhost:1031/").build(); +GoFeatureFlagProvider provider = new GoFeatureFlagProvider(options); + +OpenFeatureAPI.getInstance().setProvider(provider); +OpenFeatureAPI api = OpenFeatureAPI.getInstance(); +Client featureFlagClient = api.getClient(); +``` + +## Evaluate your flag + +This code block explain how you can create an `EvaluationContext` and use it to evaluate your flag. + +:::note +In this example we are evaluating a `boolean` flag, but other types are available. + +**Refer to the [Open Feature documentation](https://docs.openfeature.dev/docs/reference/concepts/evaluation-api#basic-evaluation) to know more about it.** +::: + +```java +// Context of your flag evaluation. +EvaluationContext userContext = new MutableContext() + .add("firstname", "john") + .add("lastname", "doe") + .add("email","john.doe@gofeatureflag.org") + .add("admin", true) + .add("anonymous", false); +// With GO Feature Flag you MUST have a targetingKey that is a unique identifier of the user. +userContext.setTargetingKey("1d1b9238-2591-4a47-94cf-d2bc080892f1"); + + + +Boolean adminFlag = featureFlagClient.getBooleanValue("flag-only-for-admin", false, userContext); +if (adminFlag) { + // flag "flag-only-for-admin" is true for the user +} else { + // flag "flag-only-for-admin" is false for the user +} +``` + +## Contribute to the provider +You can find the source of the provider in the [`open-feature/java-sdk-contrib`](https://github.com/open-feature/java-sdk-contrib/tree/main/providers/go-feature-flag) repository. \ No newline at end of file diff --git a/website/versioned_docs/version-v1.13.0/openfeature_sdk/openfeature_javascript.mdx b/website/versioned_docs/version-v1.13.0/openfeature_sdk/openfeature_javascript.mdx new file mode 100644 index 00000000000..b11a4df6798 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/openfeature_sdk/openfeature_javascript.mdx @@ -0,0 +1,135 @@ +--- +sidebar_position: 51 +description: How to use the OpenFeature Javascript SDK +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + +# Javascript / Typescript SDK usage + +## Install dependencies + +The first things we will do is install the **Open Feature SDK** and the **GO Feature Flag provider**. + + + + +```shell +yarn add @openfeature/js-sdk @openfeature/go-feature-flag-provider +``` + + + + +```shell +npm i @openfeature/js-sdk @openfeature/go-feature-flag-provider +``` + + + + +## Initialize your Open Feature client + +To evaluate the flags you need to have an Open Feature configured in you app. +This code block shows you how you can create a client that you can use in your application. + + + + +```javascript +const {OpenFeature} = require("@openfeature/js-sdk"); +const {GoFeatureFlagProvider} = require("@openfeature/go-feature-flag-provider"); + + +// init Open Feature SDK with GO Feature Flag provider +const goFeatureFlagProvider = new GoFeatureFlagProvider({ + endpoint: 'http://localhost:1031/' // DNS of your instance of relay proxy +}); +OpenFeature.setProvider(goFeatureFlagProvider); +const featureFlagClient = OpenFeature.getClient('my-app') +``` + + + + + +```typescript +import {EvaluationContext, OpenFeature} from "@openfeature/js-sdk"; +import {GoFeatureFlagProvider} from "@openfeature/go-feature-flag-provider"; + + +// init Open Feature SDK with GO Feature Flag provider +const goFeatureFlagProvider: GoFeatureFlagProvider = new GoFeatureFlagProvider({ +endpoint: 'http://localhost:1031/' +}); +OpenFeature.setProvider(goFeatureFlagProvider); +const featureFlagClient = OpenFeature.getClient('my-app'); +``` + + + + +## Evaluate your flag + +This code block explain how you can create an `EvaluationContext` and use it to evaluate your flag. + +:::note +In this example we are evaluating a `boolean` flag, but other types are available. + +**Refer to the [Open Feature documentation](https://docs.openfeature.dev/docs/reference/concepts/evaluation-api#basic-evaluation) to know more about it.** +::: + + + + +```javascript +// Context of your flag evaluation. +// With GO Feature Flag you MUST have a targetingKey that is a unique identifier of the user. +const userContext = { + targetingKey: '1d1b9238-2591-4a47-94cf-d2bc080892f1', // user unique identifier (mandatory) + firstname: 'john', + lastname: 'doe', + email: 'john.doe@gofeatureflag.org', + admin: true, // this field is used in the targeting rule of the flag "flag-only-for-admin" + // ... +}; + +const adminFlag = await featureFlagClient.getBooleanValue('flag-only-for-admin', false, userContext); +if (adminFlag) { + // flag "flag-only-for-admin" is true for the user +} else { + // flag "flag-only-for-admin" is false for the user +} +``` + + + + + +```typescript +// Context of your flag evaluation. +// With GO Feature Flag you MUST have a targetingKey that is a unique identifier of the user. +const userContext: EvaluationContext = { + targetingKey: '1d1b9238-2591-4a47-94cf-d2bc080892f1', // user unique identifier + firstname: 'john', + lastname: 'doe', + email: 'john.doe@gofeatureflag.org', + admin: true, // this field is used in the targeting rule of the flag "flag-only-for-admin" + // ... +}; + +const adminFlag = await featureFlagClient.getBooleanValue('flag-only-for-admin', false, userContext); +if (adminFlag) { + // flag "flag-only-for-admin" is true for the user +} else { + // flag "flag-only-for-admin" is false for the user +} +``` + + + + +## Contribute to the provider +You can find the source of the provider in the [`open-feature/js-sdk-contrib`](https://github.com/open-feature/js-sdk-contrib/tree/main/libs/providers/go-feature-flag) repository. \ No newline at end of file diff --git a/website/versioned_docs/version-v1.13.0/relay_proxy/_category_.json b/website/versioned_docs/version-v1.13.0/relay_proxy/_category_.json new file mode 100644 index 00000000000..8dd56dbf109 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/relay_proxy/_category_.json @@ -0,0 +1,11 @@ +{ + "position": 50, + "label":"Use the relay proxy", + "collapsible": true, + "collapsed": true, + "link": { + "type": "generated-index", + "title": "Use the relay proxy", + "description": "GO Feature Flag Relay Proxy is a powerful tool that allows developers to easily integrate feature flagging functionality into their applications. It is a simple API service that can be called directly through the API or via the available OpenFeature providers. The service wraps the GO Feature Flag golang module to evaluate your flags and allows it to be used with all the available languages." + } +} diff --git a/website/versioned_docs/version-v1.13.0/relay_proxy/configure_relay_proxy.md b/website/versioned_docs/version-v1.13.0/relay_proxy/configure_relay_proxy.md new file mode 100644 index 00000000000..74bfff6dfb2 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/relay_proxy/configure_relay_proxy.md @@ -0,0 +1,216 @@ +--- +sidebar_position: 30 +description: How to configure the relay proxy to serve your feature flags. +--- + +# 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. + +```yaml +retriever: + kind: file + path: /goff/flags.yaml # Location of your feature flag files +``` + +## Global configuration + +:::tip 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 name | Type | Default | Description | +|---------------------------|---------------------------|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `retriever` | [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](#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 + or - 10% of your polling interval.
Default: false | +| `hideBanner` | boolean | `false` | Should we display the beautiful **go-feature-flag** banner when starting the relay proxy | +| `enableSwagger` | boolean | `false` | Do 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://:/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 millisecond we are accepting to wait in our APIs. | +| `debug` | boolean | `false` | If `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. | +| `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 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. | +| `exporter` | [exporter](#exporter) | **none** | Exporter is the configuration on how to export data. | +| `notifier` | [notifier](#notifier) | **none** | Notifiers is the configuration on where to notify a flag change. | +| `apiKeys` | []string | **none** | List of authorized API keys. Each request will need to provide one of authorized key inside `Authorization` header with format `Bearer `.

_Note: there will be no authorization when this config is not set._ | + + + + +## 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 name | Type | Default | Description | +|------------|--------|----------|--------------------------------------------------------------------------------------------------------------------| +| `kind` | string | **none** | **(mandatory)** Value should be **`s3`**.
_This field is mandatory and describe 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 + +| Field name | Type | Default | Description | +|------------------|--------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `kind` | string | **none** | **(mandatory)** Value should be **`github`**.
_This field is mandatory and describe 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](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-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 describe 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`)_. | +| `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** | Github token is used to access a private repository, you need the repo permission ([how to create a GitHub token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token)). | +| `timeout` | string | `10000` | Timeout in millisecond used when calling GitHub. | + + +### File + +| Field name | Type | Default | Description | +|------------|--------|----------|----------------------------------------------------------------------------------------------------------------------| +| `kind` | string | **none** | **(mandatory)** Value should be **`file`**.
_This field is mandatory and describe 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 describe which retriever you are using._ | +| `url` | string | **none** | **(mandatory)** Location where 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 to call when calling the HTTP endpoint (useful for authorization). | +| `timeout` | string | `10000` | Timeout in millisecond used 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 describe 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 describe 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. | + + + +## type `exporter` + +### Webhook + +| Field name | Type | Default | Description | +|--------------------|---------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `kind` | string | **none** | **(mandatory)** Value should be **`webhook`**.
_This field is mandatory and describe 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](https://thomaspoignant.github.io/go-feature-flag/latest/data_collection/webhook/#signature) 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 describe which retriever you are using._ | +| `outputDir` | string | **none** | **(mandatory)** OutputDir is the location of the directory where to store the exported files. It should finish with a `/`. | +| `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}}\n` | CsvTemplate 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`](https://github.com/thomaspoignant/go-feature-flag/blob/main/internal/exporter/feature_event.go) to see what are the fields available. |` +| `parquetCompressionCodec` | string | `SNAPPY` | ParquetCompressionCodec is the parquet compression codec for better space efficiency. [Available options](https://github.com/apache/parquet-format/blob/master/Compression.md) |` + + +### Log + +| Field name | Type | Default | Description | +|--------------------|--------|-------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `kind` | string | **none** | **(mandatory)** Value should be **`log`**.
_This field is mandatory and describe 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](https://golang.org/pkg/text/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 describe 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 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}}\n` | CsvTemplate 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`](https://github.com/thomaspoignant/go-feature-flag/blob/main/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](https://github.com/apache/parquet-format/blob/master/Compression.md) |` + +### Google Storage + +| Field name | Type | Default | Description | +|--------------------|--------|-----------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `kind` | string | **none** | **(mandatory)** Value should be **`s3`**.
_This field is mandatory and describe 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}}\n` | CsvTemplate 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`](https://github.com/thomaspoignant/go-feature-flag/blob/main/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](https://github.com/apache/parquet-format/blob/master/Compression.md) |` + + + + +## 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 **`slack`**.
_This field is mandatory and describe 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](https://thomaspoignant.github.io/go-feature-flag/latest/notifier/webhook/#format) | +| `secret` | string | **none** | Secret used to sign your request body and fill the `X-Hub-Signature-256` header.
See [signature section](https://thomaspoignant.github.io/go-feature-flag/latest/data_collection/webhook/#signature) 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 | diff --git a/website/versioned_docs/version-v1.13.0/relay_proxy/deploy_relay_proxy.md b/website/versioned_docs/version-v1.13.0/relay_proxy/deploy_relay_proxy.md new file mode 100644 index 00000000000..7021befeb57 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/relay_proxy/deploy_relay_proxy.md @@ -0,0 +1,59 @@ +--- +sidebar_position: 70 +description: Deploy the relay proxy. +--- + +# Deploy the relay proxy + +## Deploy in Kubernetes using Helm +The relay proxy can be deployed in Kubernetes using a helm chart. +Helm is an invaluable tool for configuring and deploying applications to a Kubernetes environment. + +Below are the steps for installing a Helm Chart from a **GO Feature Flag** Helm repository. + +### Prerequisites + +- Access to a Kubernetes cluster +- Helm CLI installed on the client machine + +### Step 1: Prepare and Configure the Repository + +Add the repository to Helm with the Helm repository add command and provide a name and the repository URL. For example: + +```shell +helm repo add go-feature-flag https://charts.gofeatureflag.org/ +``` + +### Step 2: Install the Chart + +Install the Helm Chart with the Helm install command and provide the custom repository name, the chart name and any necessary values files. +You can look at the [helm doc](https://github.com/thomaspoignant/go-feature-flag/blob/main/cmd/relayproxy/helm-charts/relay-proxy/README.md) to know exactly what you can change in the values.yaml file. + +```shell +helm install go-feature-flag/relay-proxy -f values.yaml +``` + +### Step 3: Verify The Chart Installation + +Verify the Helm Chart installation with the Helm list command. For example: + +```shell +helm list +``` + +## Deploy as AWS Lambda +The GO Feature Flag relay proxy can easily be launched as an AWS Lambda function. +To do this, simply set the `startAsAwsLambda` option in your configuration file to `true`, like so: + +```yaml +# ... +startAsAwsLambda: true +``` + +Once you've updated your configuration file, you can deploy your function in AWS and configure it to be accessible +via HTTP. This can be achieved by creating an API Gateway or an Application Load Balancer (ALB) and linking it to +your Lambda function. + +By configuring your GO Feature Flag relay proxy to run as an AWS Lambda function, you can take advantage of the many +benefits of serverless computing, including automatic scaling, reduced infrastructure costs, and simplified +deployment and management. \ No newline at end of file diff --git a/website/versioned_docs/version-v1.13.0/relay_proxy/getting_started.md b/website/versioned_docs/version-v1.13.0/relay_proxy/getting_started.md new file mode 100644 index 00000000000..6b2cc5ef461 --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/relay_proxy/getting_started.md @@ -0,0 +1,56 @@ +--- +sidebar_position: 21 +description: Getting started with the relay proxy. +--- + +# Getting started + +Before starting your **relay proxy** you will need to create a minimal configuration file. + +```yaml +# this is a minimal config containing only where your flag file is located +retriever: + kind: http + url: https://raw.githubusercontent.com/thomaspoignant/go-feature-flag/main/examples/retriever_file/flags.yaml +``` + +After that you can launch the **relay proxy** by using this command: +```shell +go-feature-flag-relay-proxy --config=/path/to/your/configfile +``` + +The **relay proxy** will read the configuration file and retrieve all the flags. +After that you can use all the available endpoints _(see **Service endpoints** section)_ and get the variations for your users. + + +## Deployment options + +A common way to run **go-feature-flag relay proxy** is to use the Docker Container. +An image is available on docker Hub [`thomaspoignant/go-feature-flag-relay-proxy`](https://hub.docker.com/r/thomaspoignant/go-feature-flag-relay-proxy). + +You can also run it as a service in your application following the **Installation** section. + +## Specifying a configuration + +To configure the relay proxy you should provide a configuration file when launching the instance. + +The easiest way to provide the file is to use the option `--config=/path_to_your_file.yaml`. +But if you don't provide this option, the relay proxy will look in these folders if a file named `goff-proxy.yaml` is available. + +- **current folder** +- `/goff/` +- `/etc/opt/goff/` + +To learn how to configure the relay proxy, read [Configuration](./configure_relay_proxy). + +## Exporting metrics and traces + +To export the data you can use all the capabilities of `go-feature-flag` SDK. +To configure it please refer to the [type `exporter` section](./configure_relay_proxy#exporter) of the configuration. + +## Service endpoints +The Relay Proxy defines many HTTP/HTTPS endpoints. +Most of these are proxies for GO Feature Flag services, to be used by SDKs that connect to the Relay Proxy. +Others are specific to the Relay Proxy, such as for monitoring its status. + +Please refer to [endpoints documentation](./relay_proxy_endpoints) to get the full details of what exists in our REST API. diff --git a/website/versioned_docs/version-v1.13.0/relay_proxy/install_relay_proxy.md b/website/versioned_docs/version-v1.13.0/relay_proxy/install_relay_proxy.md new file mode 100644 index 00000000000..87007358ace --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/relay_proxy/install_relay_proxy.md @@ -0,0 +1,31 @@ +--- +sidebar_position: 20 +description: Relay proxy is the component that will evaluate the flags, this page explain how to install it. +--- + +# Install the relay proxy + +## When should I use the GO Feature Flag Relay Proxy? +- If you want to access your feature flag using an API instead of the [`thomaspoignant/go-feature-flag`](https://github.com/thomaspoignant/go-feature-flag) SDK. +- If you are not using GOlang to build your application. +- If you want to reduce the number of accesses to your configuration flag by centralizing them. + + +## Install using Homebrew (mac and linux) +```shell +brew install go-feature-flag-relay-proxy +``` + +## Install using Scoop (windows) +```shell +scoop bucket add org https://github.com/go-feature-flag/scoop.git +scoop install go-feature-flag-relay-proxy +``` + +## Install using docker +```shell +docker pull thomaspoignant/go-feature-flag-relay-proxy:latest +``` +:::info +More info in the [dockerhub page](https://hub.docker.com/r/thomaspoignant/go-feature-flag-relay-proxy). +::: diff --git a/website/versioned_docs/version-v1.13.0/relay_proxy/monitor_relay_proxy.md b/website/versioned_docs/version-v1.13.0/relay_proxy/monitor_relay_proxy.md new file mode 100644 index 00000000000..62d4e1de60e --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/relay_proxy/monitor_relay_proxy.md @@ -0,0 +1,21 @@ +--- +sidebar_position: 80 +description: Monitor the relay proxy. +--- + +# Monitor the relay proxy + +The **relay proxy** offer some endpoints for you to be able to see how it behaves. + +## `/health` +Making a **GET** request to the URL path `/health` will tell you if the relay proxy is ready to +serve traffic. + +This is useful especially for loadbalancer to know that they can send traffic to the service. + +## `/info` +Making a **GET** request to the URL path `/info` will give you information about the actual state +of the relay proxy. + +## `/metrics` +This endpoint is providing metrics about the relay proxy in the prometheus format. diff --git a/website/versioned_docs/version-v1.13.0/relay_proxy/relay_proxy_endpoints.md b/website/versioned_docs/version-v1.13.0/relay_proxy/relay_proxy_endpoints.md new file mode 100644 index 00000000000..1cb981b111b --- /dev/null +++ b/website/versioned_docs/version-v1.13.0/relay_proxy/relay_proxy_endpoints.md @@ -0,0 +1,25 @@ +--- +sidebar_position: 60 +description: Description of the available endpoints in the relay proxy. +--- + +# Relay proxy endpoints + +The most updated documentation about the relay proxy endpoints is the Swagger docs _(see [Swagger section](#swagger) to see how to access to the documentation)_. + +### Swagger +Swagger endpoint is serving a [swagger UI](https://swagger.io/tools/swagger-ui/) to test your REST endpoints. +By default, this endpoint is not exposed, you need to have this configuration in your **relay proxy** configuration file: + +```yaml +# ... + +enableSwagger: true +host: my-proxy-domain.com # the DNS to access the proxy +``` + +When enabled, you can go to the `/swagger/` endpoint with your browser, and you will have access to the Swagger UI for the relay proxy. + +## [OpenAPI documentation](/API_relayproxy) + +If you don't want to install the relay proxy to check the endpoints, you can go to this [**OpenAPI documentation**](/API_relayproxy) directly. diff --git a/website/versioned_sidebars/version-v1.13.0-sidebars.json b/website/versioned_sidebars/version-v1.13.0-sidebars.json new file mode 100644 index 00000000000..caea0c03ba6 --- /dev/null +++ b/website/versioned_sidebars/version-v1.13.0-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/website/versions.json b/website/versions.json index bf4ad50e43d..6551bf86b13 100644 --- a/website/versions.json +++ b/website/versions.json @@ -1,4 +1,5 @@ [ + "v1.13.0", "v1.12.1", "v1.12.0", "v1.11.0",