flagd integration

Dette indhold er ikke tilgængeligt i dit sprog endnu.

⭐ Community Toolkit

flagd is a feature flag evaluation engine that provides an OpenFeature-compliant backend system for managing and evaluating feature flags in real-time. The Aspire flagd integration enables you to create new container instances from Aspire with the ghcr.io/open-feature/flagd container image.

flagd is designed to be a flexible, open-source feature flag evaluation engine. It enables real-time flag modifications, supports various flag types (boolean, string, number, JSON), uses context-sensitive rules for targeting, and performs pseudorandom assignments for experimentation. You can aggregate flag definitions from multiple sources and expose them through gRPC or OFREP services.

Hosting integration

To get started with the Aspire flagd hosting integration, install the CommunityToolkit.Aspire.Hosting.Flagd NuGet package in the app host project.

aspire add communitytoolkit-flagd

Aspire CLI er interaktiv; vælg det passende søgeresultat når du bliver spurgt:

Select an integration to add:

> communitytoolkit-flagd (CommunityToolkit.Aspire.Hosting.Flagd)
> Other results listed as selectable options...

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

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

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.

Client integration

To get started with the Aspire flagd client integration, install an OpenFeature provider for .NET. The most common provider for flagd is the OpenFeature.Contrib.Providers.Flagd NuGet package in the client-consuming project:

dotnet add package OpenFeature.Contrib.Providers.Flagd

Add flagd client

In the Program.cs file of your client-consuming project, configure the OpenFeature SDK to use the flagd provider:

using OpenFeature;
using OpenFeature.Contrib.Providers.Flagd;

var connectionString = builder.Configuration.GetConnectionString("flagd");

await OpenFeature.Api.Instance.SetProviderAsync(
    new FlagdProvider(new Uri(connectionString)));

var flagClient = OpenFeature.Api.Instance.GetClient();

You can then use the flagClient to evaluate feature flags:

var welcomeBanner = await flagClient.GetBooleanValueAsync(
    "welcome-banner",
    defaultValue: false);

var backgroundColor = await flagClient.GetStringValueAsync(
    "background-color",
    defaultValue: "#000000");

For more information on the OpenFeature SDK and flagd provider, see the OpenFeature .NET documentation and the flagd provider documentation.

Configuration

The flagd client integration uses the connection string from the ConnectionStrings configuration section. The connection string is automatically provided when you reference the flagd resource in your app host project using WithReference.

The connection string format is:

http://localhost:<port>

Where <port> is the port assigned to the flagd HTTP endpoint.