flagd Hosting integration reference

To get started with the Aspire flagd integrations, follow the Get started with flagd integrations guide.

This article includes full details about the Aspire flagd Hosting integration.

Installation

To access the flagd hosting APIs for expressing them as resources in your AppHost project, install the 📦 CommunityToolkit.Aspire.Hosting.Flagd NuGet package:

dotnet add package CommunityToolkit.Aspire.Hosting.Flagd

Add flagd server resource

In your app host project, call AddFlagd on the builder instance to add a flagd container resource:

var builder = DistributedApplication.CreateBuilder(args);
  
var flagd = builder.AddFlagd("flagd")
                   .WithBindFileSync("./flags/");
  
builder.AddProject<Projects.ExampleProject>()
       .WithReference(flagd);
  
// After adding all resources, run the app...

When Aspire adds a container image to the app host, as shown in the preceding example with the ghcr.io/open-feature/flagd image, it creates a new flagd server instance on your local machine. A reference to your flagd server (the flagd variable) is added to the ExampleProject.

Add flagd server resource with bind mount

To add a bind mount to the flagd container resource, call the WithBindFileSync method on the flagd container resource:

var builder = DistributedApplication.CreateBuilder(args);
  
var flagd = builder.AddFlagd("flagd")
                   .WithBindFileSync(
                       fileSource: "./flags/",
                       filename: "flagd.json");
  
builder.AddProject<Projects.ExampleProject>()
       .WithReference(flagd);
  
// After adding all resources, run the app...

The bind mount is used to provide flagd with access to your flag configuration files. The fileSource parameter specifies the path on your host machine where the flag configuration file is located, and the filename parameter specifies the name of the flag configuration file. The default filename is flagd.json.

Flag configuration format

flagd uses JSON files for flag definitions. Create a folder named flags in your project root and place your flag configuration file inside it. By default, the filename is flagd.json, but you can specify a different filename using the filename parameter in WithBindFileSync.

Here's a simple example:

{
    "$schema": "https://flagd.dev/schema/v0/flags.json",
    "flags": {
        "welcome-banner": {
            "state": "ENABLED",
            "variants": {
                "on": true,
                "off": false
            },
            "defaultVariant": "off"
        },
        "background-color": {
            "state": "ENABLED",
            "variants": {
                "red": "#FF0000",
                "blue": "#0000FF",
                "yellow": "#FFFF00"
            },
            "defaultVariant": "red"
        }
    }
}

For more information on flag configuration, see the flagd flag definitions documentation.

Configure logging

To configure debug logging for the flagd container resource, call the WithLogLevel method:

var builder = DistributedApplication.CreateBuilder(args);
  
var flagd = builder.AddFlagd("flagd")
                   .WithBindFileSync("./flags/")
                   .WithLogLevel(Microsoft.Extensions.Logging.LogLevel.Debug);
  
builder.AddProject<Projects.ExampleProject>()
       .WithReference(flagd);
  
// After adding all resources, run the app...

The WithLogLevel method enables debug logging in the flagd container, which provides verbose output for troubleshooting flag evaluation issues. Currently, only Debug log level is supported.

Customize ports

To customize the ports used by the flagd container resource, provide the port and ofrepPort parameters to the AddFlagd method:

var builder = DistributedApplication.CreateBuilder(args);
  
var flagd = builder.AddFlagd(
    name: "flagd",
    port: 8013,
    ofrepPort: 8016)
    .WithBindFileSync("./flags/");
  
builder.AddProject<Projects.ExampleProject>()
       .WithReference(flagd);
  
// After adding all resources, run the app...

The port parameter specifies the host port for the flagd HTTP endpoint, and the ofrepPort parameter specifies the host port for the OFREP (OpenFeature Remote Evaluation Protocol) endpoint. If these parameters aren't provided, random ports are assigned.

Health checks

The flagd hosting integration automatically adds a health check for the flagd server resource. The health check verifies that the flagd server is running and that a connection can be established to it.

The hosting integration uses the flagd /healthz endpoint to perform health checks.