flagd Documentation

flagd is an open-source, OpenFeature-compliant feature flag evaluation engine. It is designed to be a minimalist and flexible backend for feature flag management.

Key capabilities include:

• Real-time flag modification: Update flags without restarting services.
• Multiple flag types: Supports boolean, string, number, and JSON.
• Targeting: Use context-sensitive rules to target specific users or user traits.
• Experimentation & Rollouts: Perform pseudorandom assignments for A/B testing and progressive roll-outs.
• Aggregation: Combine flag definitions from multiple sources (files, HTTP, Kubernetes, gRPC).
• Flexible Deployment: Can be used as a sidecar, a central service, or an in-process engine.

Note: flagd does not include a UI, management console, or a persistence layer. It is configured via a POSIX-style CLI.

The flagd-proxy acts as a pub/sub mechanism for flagd sidecar containers deployed in Kubernetes. It allows these sidecars to subscribe to change events in FeatureFlag Custom Resources (CRs).

How it works:

• When a request is made, the proxy spawns a goroutine to watch the specific CR using the core package Kubernetes sync.
• Subsequent requests for the same resource add a new stream to a broadcast list.
• When all streams for a resource are closed and no listeners remain, the sync is closed.
• The API is compatible with the flagd gRPC spec, meaning you can use existing gRPC sync mechanisms to subscribe to CR changes.

flagd providers act as the bridge between the OpenFeature SDK and the flagd daemon. Depending on your latency requirements and connectivity, you can use one of three resolver types:

• RPC Resolver: Evaluates flags remotely by connecting to a flagd instance via the gRPC evaluation protocol. This introduces network latency but keeps flag rules centralized.
• In-Process Resolver: Downloads the flag set rules from flagd and evaluates them locally. This offers the lowest latency and is ideal for high-performance applications.
• File Resolver: Operates offline by reading flag definitions from a local file. Like the in-process resolver, it offers low latency and is ideal for environments without network connectivity.

In-process providers support shared evaluators via $ref references. Before evaluating targeting rules, the provider resolves any $ref by replacing it with the corresponding entry from the $evaluators object defined in the flag set.

Constraint: Nested references ($ref within a $ref) are not supported. Each shared evaluator must be self-contained.

When flagd is configured with multiple --uri flags, it merges all flag definitions into a single state.

Merge Priority: If multiple sources contain the same flag key, flagd uses a priority order based on the order of definition. The latest defined source takes precedence over those defined before it.

Example: If you run --uri file:A.json --uri file:B.json, and both files contain a flag named foo, the definition from B.json will be used.

./bin/flagd start --uri file:source-A.json --uri file:source-B.json --uri file:source-C.json

In microservice architectures using service discovery or service meshes (like Istio, Envoy, or Consul), standard DNS resolution (e.g., localhost:8013) may be insufficient. flagd proposes supporting gRPC custom name resolution to allow for custom routing and name resolution via a specialized target string.

This enhancement allows the gRPC client to use a scheme-based target string instead of a simple host:port address. For example, when using an Envoy sidecar proxy, you can use a target string that specifies both the proxy location and the service authority.

Current Language Support: As of the current proposal, only Java and Golang have the required gRPC core interfaces to implement and utilize custom resolvers.

# Example target string for Envoy sidecar proxy
envoy://localhost:9211/flagd-sync.service

You can use starts_with and ends_with operations within a targeting rule to select a variant based on whether a property in the evaluation context begins or ends with a specific string.

These operations expect an array containing exactly two items:

1. The resolved value from the evaluation context (the string to be checked).
2. The target string (the prefix or suffix to look for).

The operation returns a boolean indicating if the condition is met.

// Example of a starts_with rule in a targeting configuration
"starts_with": [
  // The resolved value from the evaluation context (e.g., from 'email')
  "user@faas", 
  // The prefix that must be present
  "user@faas"
]

flagd is OpenFeature-compliant. To use flagd in your application, you must use the OpenFeature SDK for your specific language along with a flagd provider.

Providers for flagd operate in two distinct modes:

1. RPC Mode: The provider communicates with a remote flagd instance over HTTP or gRPC. This is suitable for centralized flag management.
2. In-process Mode: The provider embeds flagd's evaluation engine directly into your application process. This eliminates network latency for flag evaluations.

Note that some providers support both modes, while others are limited to one (e.g., PHP and Web providers only support RPC mode).

Each flag within the flags object must have a unique flag key. This key is a required property used to identify the flag during evaluation. When choosing a key, it should be unique across your configuration and should clearly convey the intent of the flag (e.g., new-welcome-banner).

{
  "$schema": "https://flagd.dev/schema/v0/flags.json",
  "flags": {
    "new-welcome-banner": {
      ...
    }
  }
}

To follow the DRY (Don't Repeat Yourself) principle, flagd allows you to define shared targeting logic in a top-level $evaluators property. You can then reference these shared rules within specific flag targeting blocks using the $ref operator.

This is useful for common logic, such as checking if a user belongs to a specific domain or has a certain attribute, which can be reused across multiple flags.

{
  "$evaluators": {
    "isEmployee": {
      "ends_with": [{"var": "email"}, "@company.com"]
    }
  },
  "flags": {
    "feature-x": {
      "state": "ENABLED",
      "defaultVariant": "enabled",
      "variants": {
        "enabled": true,
        "disabled": false
      },
      "targeting": {
        "if": [{"$ref": "isEmployee"}, "enabled", "disabled"]
      }
    }
  }
}