Skip to content

Commit b8a38a0

Browse files
askptIEvangelistCopilot
authored
Add flagd Hosting documentation (#5300)
* Add initial hosting-flagd.md documentation file Signed-off-by: André Silva <2493377+askpt@users.noreply.github.com> * Add flagd integration to the community toolkit overview Signed-off-by: André Silva <2493377+askpt@users.noreply.github.com> * Add documentation for flagd hosting extensions integration Signed-off-by: André Silva <2493377+askpt@users.noreply.github.com> * Update docs/community-toolkit/hosting-flagd.md Co-authored-by: David Pine <david.pine@microsoft.com> * Remove tip about connecting to an existing flagd server from hosting-flagd.md Signed-off-by: André Silva <2493377+askpt@users.noreply.github.com> * Add flagd hosting documentation link to the table of contents Signed-off-by: André Silva <2493377+askpt@users.noreply.github.com> * Update docs/community-toolkit/hosting-flagd.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Signed-off-by: André Silva <2493377+askpt@users.noreply.github.com> Co-authored-by: David Pine <david.pine@microsoft.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent d925788 commit b8a38a0

File tree

3 files changed

+234
-0
lines changed

3 files changed

+234
-0
lines changed

‎docs/community-toolkit/hosting-flagd.md‎

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
---
2+
title: flagd hosting extensions
3+
description: Learn about the Aspire Community Toolkit flagd hosting extensions package which provides functionality to host flagd feature flag evaluation containers.
4+
ms.date: 10/16/2025
5+
ai-usage: ai-generated
6+
---
7+
8+
# Aspire flagd integration
9+
10+
[!INCLUDE [includes-hosting](../includes/includes-hosting.md)]
11+
12+
[!INCLUDE [banner](includes/banner.md)]
13+
14+
[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).
15+
16+
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.
17+
18+
## Hosting integration
19+
20+
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.
21+
22+
### [.NET CLI](#tab/dotnet-cli)
23+
24+
```dotnetcli
25+
dotnet add package CommunityToolkit.Aspire.Hosting.Flagd
26+
```
27+
28+
### [PackageReference](#tab/package-reference)
29+
30+
```xml
31+
<PackageReference Include="CommunityToolkit.Aspire.Hosting.Flagd"
32+
Version="*" />
33+
```
34+
35+
---
36+
37+
For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-package) or [Manage package dependencies in .NET applications](/dotnet/core/tools/dependencies).
38+
39+
### Add flagd server resource
40+
41+
In your AppHost project, call `AddFlagd` on the `builder` instance to add a flagd container resource:
42+
43+
```csharp
44+
var builder = DistributedApplication.CreateBuilder(args);
45+
46+
var flagd = builder.AddFlagd("flagd")
47+
.WithBindFileSync("./flags/");
48+
49+
builder.AddProject<Projects.ExampleProject>()
50+
.WithReference(flagd);
51+
52+
// After adding all resources, run the app...
53+
```
54+
55+
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`.
56+
57+
The <xref:Aspire.Hosting.ResourceBuilderExtensions.WithReference%2A> 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).
58+
59+
> [!IMPORTANT]
60+
> The flagd container requires a sync source to be configured. Use the `WithBindFileSync` method to configure file-based flag synchronization.
61+
62+
### Add flagd server resource with bind mount
63+
64+
To add a bind mount to the flagd container resource, call the `Aspire.Hosting.FlagdBuilderExtensions.WithBindFileSync` method on the flagd container resource:
65+
66+
```csharp
67+
var builder = DistributedApplication.CreateBuilder(args);
68+
69+
var flagd = builder.AddFlagd("flagd")
70+
.WithBindFileSync(
71+
fileSource: "./flags/",
72+
filename: "flagd.json");
73+
74+
builder.AddProject<Projects.ExampleProject>()
75+
.WithReference(flagd);
76+
77+
// After adding all resources, run the app...
78+
```
79+
80+
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`.
81+
82+
For more information on bind mounts, see [Docker docs: Bind mounts](https://docs.docker.com/engine/storage/bind-mounts).
83+
84+
### Flag configuration format
85+
86+
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`.
87+
88+
Here's a simple example:
89+
90+
```json
91+
{
92+
"$schema": "https://flagd.dev/schema/v0/flags.json",
93+
"flags": {
94+
"welcome-banner": {
95+
"state": "ENABLED",
96+
"variants": {
97+
"on": true,
98+
"off": false
99+
},
100+
"defaultVariant": "off"
101+
},
102+
"background-color": {
103+
"state": "ENABLED",
104+
"variants": {
105+
"red": "#FF0000",
106+
"blue": "#0000FF",
107+
"yellow": "#FFFF00"
108+
},
109+
"defaultVariant": "red"
110+
}
111+
}
112+
}
113+
```
114+
115+
For more information on flag configuration, see the [flagd flag definitions documentation](https://flagd.dev/reference/flag-definitions/).
116+
117+
### Configure logging
118+
119+
To configure debug logging for the flagd container resource, call the `Aspire.Hosting.FlagdBuilderExtensions.WithLogLevel` method:
120+
121+
```csharp
122+
var builder = DistributedApplication.CreateBuilder(args);
123+
124+
var flagd = builder.AddFlagd("flagd")
125+
.WithBindFileSync("./flags/")
126+
.WithLogLevel(Microsoft.Extensions.Logging.LogLevel.Debug);
127+
128+
builder.AddProject<Projects.ExampleProject>()
129+
.WithReference(flagd);
130+
131+
// After adding all resources, run the app...
132+
```
133+
134+
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.
135+
136+
### Customize ports
137+
138+
To customize the ports used by the flagd container resource, provide the `port` and `ofrepPort` parameters to the `AddFlagd` method:
139+
140+
```csharp
141+
var builder = DistributedApplication.CreateBuilder(args);
142+
143+
var flagd = builder.AddFlagd(
144+
name: "flagd",
145+
port: 8013,
146+
ofrepPort: 8016)
147+
.WithBindFileSync("./flags/");
148+
149+
builder.AddProject<Projects.ExampleProject>()
150+
.WithReference(flagd);
151+
152+
// After adding all resources, run the app...
153+
```
154+
155+
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.
156+
157+
### Hosting integration health checks
158+
159+
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.
160+
161+
The hosting integration uses the flagd `/healthz` endpoint to perform health checks.
162+
163+
## Client integration
164+
165+
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.
166+
167+
### [.NET CLI](#tab/dotnet-cli)
168+
169+
```dotnetcli
170+
dotnet add package OpenFeature.Contrib.Providers.Flagd
171+
```
172+
173+
### [PackageReference](#tab/package-reference)
174+
175+
```xml
176+
<PackageReference Include="OpenFeature.Contrib.Providers.Flagd"
177+
Version="*" />
178+
```
179+
180+
---
181+
182+
### Add flagd client
183+
184+
In the _:::no-loc text="Program.cs":::_ file of your client-consuming project, configure the OpenFeature SDK to use the flagd provider:
185+
186+
```csharp
187+
using OpenFeature;
188+
using OpenFeature.Contrib.Providers.Flagd;
189+
190+
var connectionString = builder.Configuration.GetConnectionString("flagd");
191+
192+
await OpenFeature.Api.Instance.SetProviderAsync(
193+
new FlagdProvider(new Uri(connectionString)));
194+
195+
var flagClient = OpenFeature.Api.Instance.GetClient();
196+
```
197+
198+
You can then use the `flagClient` to evaluate feature flags:
199+
200+
```csharp
201+
var welcomeBanner = await flagClient.GetBooleanValueAsync(
202+
"welcome-banner",
203+
defaultValue: false);
204+
205+
var backgroundColor = await flagClient.GetStringValueAsync(
206+
"background-color",
207+
defaultValue: "#000000");
208+
```
209+
210+
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/).
211+
212+
### Configuration
213+
214+
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`.
215+
216+
The connection string format is:
217+
218+
```plaintext
219+
http://localhost:<port>
220+
```
221+
222+
Where `<port>` is the port assigned to the flagd HTTP endpoint.
223+
224+
## See also
225+
226+
- [flagd documentation](https://flagd.dev)
227+
- [OpenFeature documentation](https://openfeature.dev)
228+
- [Aspire integrations](../fundamentals/integrations-overview.md)
229+
- [Aspire GitHub repo](https://github.com/dotnet/aspire)

‎docs/community-toolkit/overview.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,9 @@ The community toolkit is a growing project, publishing a set of NuGet packages.
5454
- The [RavenDB](https://ravendb.net/) integration enables hosting RavenDB containers.
5555
- [📄 Aspire RavenDB hosting integration](https://github.com/CommunityToolkit/Aspire/tree/main/src/CommunityToolkit.Aspire.Hosting.RavenDB).
5656
- [📦 CommunityToolkit.Aspire.Hosting.RavenDB](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.RavenDB).
57+
- The [flagd](https://flagd.dev/) integration enables hosting flagd containers.
58+
- [📄 Aspire flagd hosting integration](https://github.com/CommunityToolkit/Aspire/tree/main/src/CommunityToolkit.Aspire.Hosting.Flagd).
59+
- [📦 CommunityToolkit.Aspire.Hosting.Flagd](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Flagd).
5760

5861
### Client integrations
5962

‎docs/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -470,6 +470,8 @@ items:
470470
href: community-toolkit/hosting-mysql-extensions.md
471471
- name: RavenDB
472472
href: community-toolkit/ravendb.md
473+
- name: flagd
474+
href: community-toolkit/hosting-flagd.md
473475
- name: Aspire.Hosting API reference
474476
href: /dotnet/api/?term=Aspire.Hosting&view=dotnet-aspire-9.0&preserve-view=true
475477

0 commit comments

Comments
 (0)