Set up flagd in the AppHost

⭐ Community Toolkit

This article is the reference for the Aspire flagd Hosting integration. It enumerates the AppHost APIs that you use to model a flagd resource in your AppHost project.

If you’re new to the flagd integration, start with the Get started with flagd integrations guide. For how consuming apps read the connection information this page exposes, see Connect to flagd.

Installation

To start building an Aspire app that uses flagd, install the 📦 CommunityToolkit.Aspire.Hosting.Flagd NuGet package:

Terminal

aspire add flagd

Learn more about aspire add in the command reference.

Or, choose a manual installation approach:

C# — AppHost.cs

#:package CommunityToolkit.Aspire.Hosting.Flagd@*

XML — AppHost.csproj

<PackageReference Include="CommunityToolkit.Aspire.Hosting.Flagd" Version="*" />

Note

TypeScript AppHost support for the flagd integration is not yet available.

Add flagd resource

Once you’ve installed the hosting integration in your AppHost project, you can add a flagd resource. The flagd container requires a sync source. Use WithBindFileSync to mount a directory of flag-definition files into the container:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var flagd = builder.AddFlagd("flagd")
    .WithBindFileSync("./flags/");

builder.AddProject<Projects.ExampleProject>("api")
    .WithReference(flagd);

// After adding all resources, run the app...
builder.Build().Run();

1. When Aspire adds a container image to the AppHost, 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.

2. The AppHost reference call configures a connection in the consuming project named after the referenced flagd resource, such as flagd in the preceding example.

참고

When you reference a flagd resource from the AppHost, Aspire makes the server’s connection information available to the consuming project as environment variables. For a complete list of these properties and per-language connection examples, see Connect to flagd.

Add flagd resource with file sync options

To specify the flag-definition filename explicitly, pass both the fileSource directory and the filename to WithBindFileSync:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var flagd = builder.AddFlagd("flagd")
    .WithBindFileSync(
        fileSource: "./flags/",
        filename: "flagd.json");

builder.AddProject<Projects.ExampleProject>("api")
    .WithReference(flagd);

// After adding all resources, run the app...
builder.Build().Run();

The fileSource parameter is the path on your host machine where flag configuration files are located. The filename parameter names the flag configuration file inside that directory. When filename is omitted, it defaults to flagd.json.

Flag configuration format

flagd uses JSON files for flag definitions. Create a flags folder in your project root and add a flag configuration file. A minimal example:

JSON — flags/flagd.json

{
    "$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 enable debug logging for the flagd container, call WithLogLevel:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var flagd = builder.AddFlagd("flagd")
    .WithBindFileSync("./flags/")
    .WithLogLevel(Microsoft.Extensions.Logging.LogLevel.Debug);

builder.AddProject<Projects.ExampleProject>("api")
    .WithReference(flagd);

// After adding all resources, run the app...
builder.Build().Run();

Debug logging provides verbose output for troubleshooting flag evaluation issues. Currently, only the Debug log level is supported.

Customize ports

To use fixed host ports instead of randomly assigned ones, pass the port and ofrepPort parameters to AddFlagd:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var flagd = builder.AddFlagd(
    name: "flagd",
    port: 8013,
    ofrepPort: 8016)
    .WithBindFileSync("./flags/");

builder.AddProject<Projects.ExampleProject>("api")
    .WithReference(flagd);

// After adding all resources, run the app...
builder.Build().Run();

The port parameter sets the host port for the flagd HTTP/gRPC endpoint. The ofrepPort parameter sets the host port for the OFREP (OpenFeature Remote Evaluation Protocol) endpoint. When these parameters are omitted, Aspire assigns random ports.

Health checks

The flagd hosting integration automatically registers a health check for the flagd resource. The health check polls the flagd /healthz endpoint to verify the server is running and reachable.