flagd

README

Flagd is a simple command line tool for fetching and evaluating feature flags for services. It is designed to conform with the OpenFeature specification.

Install

Go binary

1. Install Go 1.18 or above
2. run go install github.com/open-feature/flagd@latest

Docker

1. docker pull ghcr.io/open-feature/flagd:latest

NOTE: It is possible to run flagD as a systemd service. Installation instructions can be found here.

Example usage

1. Download sample flag configurations: curl https://raw.githubusercontent.com/open-feature/flagd/main/config/samples/example_flags.json -o example_flags.json
2. Run one of the following commands based on how flagD was installed:
   • Go binary: flagd start -f example_flags.json
   • Docker: docker run -p 8013:8013 -v $(pwd)/:/etc/flagd/ -it ghcr.io/open-feature/flagd:latest start --uri /etc/flagd/example_flags.json
3. Changes made in example_flags.json will immediately take affect. Go ahead, give a shot!

This now provides an accessible http or https endpoint for flag evaluation. A complete list of supported configuration options can be seen here.

Resolve a boolean value

Command:

curl -X POST "localhost:8013/schema.v1.Service/ResolveBoolean" -d '{"flagKey":"myBoolFlag","context":{}}' -H "Content-Type: application/json"

Result:

{"value":true,"reason":"DEFAULT","variant":"on"}

Resolve a string value

Command:

curl -X POST "localhost:8013/schema.v1.Service/ResolveString" -d '{"flagKey":"myStringFlag","context":{}}' -H "Content-Type: application/json"

Result:

{"value":"val1","reason":"DEFAULT","variant":"key1"}

Resolve a integer value

Command:

curl -X POST "localhost:8013/schema.v1.Service/ResolveInt" -d '{"flagKey":"myIntFlag","context":{}}' -H "Content-Type: application/json"

Result:

{"value":"1","reason":"DEFAULT","variant":"one"}

Why is this int response a string?

Resolve a float value

Command:

curl -X POST "localhost:8013/schema.v1.Service/ResolveFloat" -d '{"flagKey":"myFloatFlag","context":{}}' -H "Content-Type: application/json"

Result:

{"value":1.23,"reason":"DEFAULT","variant":"one"}

Resolve an object value

Command:

curl -X POST "localhost:8013/schema.v1.Service/ResolveObject" -d '{"flagKey":"myObjectFlag","context":{}}' -H "Content-Type: application/json"

Result:

{"value":{"key":"val"},"reason":"DEFAULT","variant":"object1"}

Resolve a boolean value with evaluation context

Command:

curl -X POST "localhost:8013/schema.v1.Service/ResolveBoolean" -d '{"flagKey":"isColorYellow","context":{"color":"yellow"}}' -H "Content-Type: application/json"

Result:

{"value":true,"reason":"TARGETING_MATCH","variant":"on"}

Return value type mismatch error

A type mismatch error is returned when the resolved value of a flag does not match the type requested. In the example below, the resolved value of myBoolFlag is a boolean but the request expects a string to be returned.

Command:

curl -X POST "localhost:8013/schema.v1.Service/ResolveString" -d '{"flagKey":"myBoolFlag","context":{}}' -H "Content-Type: application/json"

Result:

{"code":"invalid_argument","message":"TYPE_MISMATCH"}

Return flag not found error

The flag not found error is returned when flag key in the request doesn't match any configured flags.

Command:

curl -X POST "localhost:8013/schema.v1.Service/ResolveBoolean" -d '{"flagKey":"aMissingFlag","context":{}}' -H "Content-Type: application/json"

Result:

{"code":"not_found","message":"FLAG_NOT_FOUND"}

https

When it is desired to use TLS for increased security, flagD can be started with the following cert and key information.

flagd start --server-cert-path ./example-cert.pem --server-key-path ./example-key.pem

This enables you to use an upgraded connection for the previous example requests, such as the following:

curl -X POST "localhost:8013/schema.v1.Service/ResolveBoolean" -d '{"flagKey":"myBoolFlag","context":{}}' -H "Content-Type: application/json"
// {"value":true,"reason":"DEFAULT","variant":"on"}

Multiple source example

Multiple providers can be supplied as the following:

./flagd start -f config/samples/example_flags.json -f config/samples/example_flags_secondary.json --service-provider http --sync-provider filepath

1. IMG=flagd-local make docker-build
2. docker run -p 8013:8013 -it flagd-local start --uri ./examples/example_flags.json

Targeting Rules

The flag object has a field named "targeting", this can be populated with a JsonLogic rule. Any data in the body of a flag evaluation call is processed by the JsonLogic rule to determine the result of flag evaluation. If this result is null or an invalid (undefined) variant then the default variant is returned.

JsonLogic provides a playground for evaluating your rules against data.

Example

A flag is defined as such:

{
  "flags": {
    "isColorYellowFlag": {
      "state": "ENABLED",
      "variants": {
        "on": true,
        "off": false
      },
      "defaultVariant": "off",
      "targeting": {
        "if": [
          {
            "==": [
              {
                "var": ["color"]
              },
              "yellow"
            ]
          },
          "on",
          "off"
        ]
      }
    }
  }
}

The rule provided returns "on" if var color == "yellow" and "off" otherwise:

curl -X POST "localhost:8013/schema.v1.Service/ResolveBoolean" -d '{"flagKey":"isColorYellow","context":{"color":"yellow"}}' -H "Content-Type: application/json"

returns

{ "value": true, "reason": "TARGETING_MATCH", "variant": "on" }

whereas

curl -X POST "localhost:8013/schema.v1.Service/ResolveBoolean" -d '{"flagKey":"isColorYellow","context":{"color":"white"}}' -H "Content-Type: application/json"

returns

{ "value": true, "reason": "TARGETING_MATCH", "variant": "off" }

Customization of sync providers

Reusable targeting rules

Fractional Evaluation

The people who make flagD great 💜