From b798dde6a74af4607556c778a05e8aca5947731a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Silva?= <2493377+askpt@users.noreply.github.com> Date: Thu, 16 Oct 2025 12:03:36 +0100 Subject: [PATCH 1/7] Add initial hosting-flagd.md documentation file MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: André Silva <2493377+askpt@users.noreply.github.com> --- docs/community-toolkit/hosting-flagd.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/community-toolkit/hosting-flagd.md diff --git a/docs/community-toolkit/hosting-flagd.md b/docs/community-toolkit/hosting-flagd.md new file mode 100644 index 0000000000..e69de29bb2 From f183f9103fb48b44dd01396ff912e2530e55128a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Silva?= <2493377+askpt@users.noreply.github.com> Date: Thu, 16 Oct 2025 12:07:21 +0100 Subject: [PATCH 2/7] Add flagd integration to the community toolkit overview MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: André Silva <2493377+askpt@users.noreply.github.com> --- docs/community-toolkit/overview.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/community-toolkit/overview.md b/docs/community-toolkit/overview.md index 81c6772dba..4a466c7182 100644 --- a/docs/community-toolkit/overview.md +++ b/docs/community-toolkit/overview.md @@ -54,6 +54,9 @@ The community toolkit is a growing project, publishing a set of NuGet packages. - The [RavenDB](https://ravendb.net/) integration enables hosting RavenDB containers. - [📄 Aspire RavenDB hosting integration](https://github.com/CommunityToolkit/Aspire/tree/main/src/CommunityToolkit.Aspire.Hosting.RavenDB). - [📦 CommunityToolkit.Aspire.Hosting.RavenDB](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.RavenDB). +- The [flagd](https://flagd.dev/) integration enables hosting flagd containers. + - [📄 Aspire flagd hosting integration](https://github.com/CommunityToolkit/Aspire/tree/main/src/CommunityToolkit.Aspire.Hosting.Flagd). + - [📦 CommunityToolkit.Aspire.Hosting.Flagd](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Flagd). ### Client integrations From 00e61dbb203cc9644fcff1188161423085f1e88a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Silva?= <2493377+askpt@users.noreply.github.com> Date: Thu, 16 Oct 2025 13:45:25 +0100 Subject: [PATCH 3/7] Add documentation for flagd hosting extensions integration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: André Silva <2493377+askpt@users.noreply.github.com> --- docs/community-toolkit/hosting-flagd.md | 232 ++++++++++++++++++++++++ 1 file changed, 232 insertions(+) diff --git a/docs/community-toolkit/hosting-flagd.md b/docs/community-toolkit/hosting-flagd.md index e69de29bb2..8a13f22d04 100644 --- a/docs/community-toolkit/hosting-flagd.md +++ b/docs/community-toolkit/hosting-flagd.md @@ -0,0 +1,232 @@ +--- +title: flagd hosting extensions +description: Learn about the Aspire Community Toolkit flagd hosting extensions package which provides functionality to host flagd feature flag evaluation containers. +ms.date: 10/16/2025 +ai-usage: ai-generated +--- + +# Aspire flagd integration + +[!INCLUDE [includes-hosting](../includes/includes-hosting.md)] + +[!INCLUDE [banner](includes/banner.md)] + +[flagd](https://flagd.dev) 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 .NET with the [`ghcr.io/open-feature/flagd` container image](https://github.com/open-feature/flagd/pkgs/container/flagd). + +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. flagd is designed to fit well into various infrastructures and can run as a separate process or directly in your application. + +## Hosting integration + +The flagd hosting integration models a flagd server as the `Aspire.Hosting.ApplicationModel.FlagdResource` type. To access this type and its APIs add the [📦 CommunityToolkit.Aspire.Hosting.Flagd](https://www.nuget.org/packages/CommunityToolkit.Aspire.Hosting.Flagd) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. + +### [.NET CLI](#tab/dotnet-cli) + +```dotnetcli +dotnet add package CommunityToolkit.Aspire.Hosting.Flagd +``` + +### [PackageReference](#tab/package-reference) + +```xml + +``` + +--- + +For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-package) or [Manage package dependencies in .NET applications](/dotnet/core/tools/dependencies). + +### Add flagd server resource + +In your app host project, call `AddFlagd` on the `builder` instance to add a flagd container resource: + +```csharp +var builder = DistributedApplication.CreateBuilder(args); + +var flagd = builder.AddFlagd("flagd") + .WithBindFileSync("./flags/"); + +builder.AddProject() + .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`. + +The method configures a connection in the `ExampleProject` named `"flagd"`. For more information, see [Built-in resource types](../fundamentals/app-host-overview.md#built-in-resource-types). + +> [!IMPORTANT] +> The flagd container requires a sync source to be configured. Use the `WithBindFileSync` method to configure file-based flag synchronization. + +> [!TIP] +> If you'd rather connect to an existing flagd server, call instead. For more information, see [Reference existing resources](../fundamentals/app-host-overview.md#reference-existing-resources). + +### Add flagd server resource with bind mount + +To add a bind mount to the flagd container resource, call the `Aspire.Hosting.FlagdBuilderExtensions.WithBindFileSync` method on the flagd container resource: + +```csharp +var builder = DistributedApplication.CreateBuilder(args); + +var flagd = builder.AddFlagd("flagd") + .WithBindFileSync( + fileSource: "./flags/", + filename: "flagd.json"); + +builder.AddProject() + .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`. + +For more information on bind mounts, see [Docker docs: Bind mounts](https://docs.docker.com/engine/storage/bind-mounts). + +### Flag configuration format + +flagd uses JSON files for flag definitions. Create a folder named `flags` in your project root and place your `flagd.json` file inside it. The flag configuration file must be named `flagd.json`. + +Here's a simple example: + +```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](https://flagd.dev/reference/flag-definitions/). + +### Configure logging + +To configure debug logging for the flagd container resource, call the `Aspire.Hosting.FlagdBuilderExtensions.WithLogLevel` method: + +```csharp +var builder = DistributedApplication.CreateBuilder(args); + +var flagd = builder.AddFlagd("flagd") + .WithBindFileSync("./flags/") + .WithLogLevel(Microsoft.Extensions.Logging.LogLevel.Debug); + +builder.AddProject() + .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: + +```csharp +var builder = DistributedApplication.CreateBuilder(args); + +var flagd = builder.AddFlagd( + name: "flagd", + port: 8013, + ofrepPort: 8016) + .WithBindFileSync("./flags/"); + +builder.AddProject() + .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. + +### Hosting integration 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](https://www.nuget.org/packages/OpenFeature.Contrib.Providers.Flagd) NuGet package in the client-consuming project. + +### [.NET CLI](#tab/dotnet-cli) + +```dotnetcli +dotnet add package OpenFeature.Contrib.Providers.Flagd +``` + +### [PackageReference](#tab/package-reference) + +```xml + +``` + +--- + +### Add flagd client + +In the _:::no-loc text="Program.cs":::_ file of your client-consuming project, configure the OpenFeature SDK to use the flagd provider: + +```csharp +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: + +```csharp +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](https://openfeature.dev/docs/reference/technologies/client/dotnet/) and the [flagd provider documentation](https://flagd.dev/providers/dotnet/). + +### 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: + +```plaintext +http://localhost: +``` + +Where `` is the port assigned to the flagd HTTP endpoint. + +## See also + +- [flagd documentation](https://flagd.dev) +- [OpenFeature documentation](https://openfeature.dev) +- [Aspire integrations](../fundamentals/integrations-overview.md) +- [Aspire GitHub repo](https://github.com/dotnet/aspire) From adef2b72e02d9880d59201dbf1ed633cf1fd3029 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Silva?= <2493377+askpt@users.noreply.github.com> Date: Fri, 17 Oct 2025 21:21:20 +0100 Subject: [PATCH 4/7] Update docs/community-toolkit/hosting-flagd.md Co-authored-by: David Pine --- docs/community-toolkit/hosting-flagd.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/community-toolkit/hosting-flagd.md b/docs/community-toolkit/hosting-flagd.md index 8a13f22d04..a8f9aa1ab3 100644 --- a/docs/community-toolkit/hosting-flagd.md +++ b/docs/community-toolkit/hosting-flagd.md @@ -38,7 +38,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add flagd server resource -In your app host project, call `AddFlagd` on the `builder` instance to add a flagd container resource: +In your AppHost project, call `AddFlagd` on the `builder` instance to add a flagd container resource: ```csharp var builder = DistributedApplication.CreateBuilder(args); From bac17b1b5dc917020bee8358d48962a8ecd2cf43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Silva?= <2493377+askpt@users.noreply.github.com> Date: Fri, 17 Oct 2025 21:24:43 +0100 Subject: [PATCH 5/7] Remove tip about connecting to an existing flagd server from hosting-flagd.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: André Silva <2493377+askpt@users.noreply.github.com> --- docs/community-toolkit/hosting-flagd.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/community-toolkit/hosting-flagd.md b/docs/community-toolkit/hosting-flagd.md index a8f9aa1ab3..dac3625b04 100644 --- a/docs/community-toolkit/hosting-flagd.md +++ b/docs/community-toolkit/hosting-flagd.md @@ -59,9 +59,6 @@ The method conf > [!IMPORTANT] > The flagd container requires a sync source to be configured. Use the `WithBindFileSync` method to configure file-based flag synchronization. -> [!TIP] -> If you'd rather connect to an existing flagd server, call instead. For more information, see [Reference existing resources](../fundamentals/app-host-overview.md#reference-existing-resources). - ### Add flagd server resource with bind mount To add a bind mount to the flagd container resource, call the `Aspire.Hosting.FlagdBuilderExtensions.WithBindFileSync` method on the flagd container resource: From 6281d56b313611022b9d1b0959026d30371dcb86 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Silva?= <2493377+askpt@users.noreply.github.com> Date: Fri, 17 Oct 2025 21:26:15 +0100 Subject: [PATCH 6/7] Add flagd hosting documentation link to the table of contents MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: André Silva <2493377+askpt@users.noreply.github.com> --- docs/toc.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/toc.yml b/docs/toc.yml index ae30c9bd56..f5ea739315 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -470,6 +470,8 @@ items: href: community-toolkit/hosting-mysql-extensions.md - name: RavenDB href: community-toolkit/ravendb.md + - name: flagd + href: community-toolkit/hosting-flagd.md - name: Aspire.Hosting API reference href: /dotnet/api/?term=Aspire.Hosting&view=dotnet-aspire-9.0&preserve-view=true From 74d229cf5147308aa0e1d448d7f94fdb6bcf2995 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Silva?= <2493377+askpt@users.noreply.github.com> Date: Wed, 29 Oct 2025 22:19:54 +0000 Subject: [PATCH 7/7] Update docs/community-toolkit/hosting-flagd.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/community-toolkit/hosting-flagd.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/community-toolkit/hosting-flagd.md b/docs/community-toolkit/hosting-flagd.md index dac3625b04..18b8bea4a8 100644 --- a/docs/community-toolkit/hosting-flagd.md +++ b/docs/community-toolkit/hosting-flagd.md @@ -83,7 +83,7 @@ For more information on bind mounts, see [Docker docs: Bind mounts](https://docs ### Flag configuration format -flagd uses JSON files for flag definitions. Create a folder named `flags` in your project root and place your `flagd.json` file inside it. The flag configuration file must be named `flagd.json`. +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: