Set up GO Feature Flag in the AppHost

このコンテンツはまだ日本語訳がありません。

⭐ Community Toolkit

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

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

Installation

To start building an Aspire app that uses GO Feature Flag, install the 📦 CommunityToolkit.Aspire.Hosting.GoFeatureFlag NuGet package:

aspire add CommunityToolkit.Aspire.Hosting.GoFeatureFlag

Learn more about aspire add in the command reference.

Or, choose a manual installation approach:

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

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

Add goff resource

Once you’ve installed the hosting integration in your AppHost project, you can add a GO Feature Flag relay proxy resource as shown in the following example:

var builder = DistributedApplication.CreateBuilder(args);

var goff = builder.AddGoFeatureFlag("goff")
    .WithGoffBindMount("./goff");

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(goff);

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

When Aspire adds a container image to the AppHost, as shown in the preceding example with the docker.io/gofeatureflag/go-feature-flag image, it creates a new GO Feature Flag relay proxy instance on your local machine.
The WithGoffBindMount call mounts a local folder into the /goff path inside the container, where the relay proxy reads its flag and proxy configuration files.
The WithReference call configures a connection in the consuming project named after the referenced resource (goff in the preceding example).

Add goff resource with configuration path

To point the relay proxy to a specific configuration file inside the container, pass the pathToConfigFile parameter to AddGoFeatureFlag:

var builder = DistributedApplication.CreateBuilder(args);

var goff = builder.AddGoFeatureFlag("goff", pathToConfigFile: "/goff/goff-proxy.yaml")
    .WithGoffBindMount("./goff");

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(goff);

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

The pathToConfigFile parameter sets the --config argument passed to the relay proxy entrypoint. If this parameter is omitted, the relay proxy looks for a default configuration file in its working directory.

Add goff resource with data volume

To persist relay proxy data (such as cached flag evaluations) across container restarts, add a named data volume:

var builder = DistributedApplication.CreateBuilder(args);

var goff = builder.AddGoFeatureFlag("goff")
    .WithGoffBindMount("./goff")
    .WithDataVolume();

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(goff);

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

The data volume is mounted at the /goff_data path in the container. When a name parameter isn’t provided, a name is generated automatically. For more information on data volumes, see Docker docs: Volumes.

Flag configuration format

The relay proxy reads feature flag definitions from configuration files. GO Feature Flag supports YAML, JSON, and TOML formats. Here is a minimal example to get started:

display-banner:
  variations:
    enabled: true
    disabled: false
  defaultRule:
    variation: enabled

For the full syntax, see Create flags with GO Feature Flag.

Relay proxy configuration

In addition to flag definition files, the relay proxy requires a configuration file that tells it where to load flags from. Create a goff-proxy.yaml file in the same bind-mounted folder:

retrievers:
  - kind: file
    path: /goff/flags.yaml

This instructs the relay proxy to load flags from the flags.yaml file inside the /goff folder (the bind-mounted local folder). For all relay proxy configuration options, see the GO Feature Flag relay proxy documentation.

Configure logging

To configure the log level for the GO Feature Flag container resource, call WithLogLevel:

var builder = DistributedApplication.CreateBuilder(args);

var goff = builder.AddGoFeatureFlag("goff")
    .WithGoffBindMount("./goff")
    .WithLogLevel(Microsoft.Extensions.Logging.LogLevel.Debug);

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(goff);

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

The WithLogLevel method sets the LOGLEVEL environment variable on the container. The supported log levels are Debug, Information, Warning, and Error.

Customize ports

To use a specific host port for the relay proxy HTTP endpoint, pass the port parameter to AddGoFeatureFlag:

var builder = DistributedApplication.CreateBuilder(args);

var goff = builder.AddGoFeatureFlag(name: "goff", port: 1031)
    .WithGoffBindMount("./goff");

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(goff);

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

The port parameter specifies the host port bound to the relay proxy’s internal port. If not provided, Aspire assigns a random port.

Connection properties

For the full reference of GO Feature Flag connection properties — and how consuming apps in C#, TypeScript, Python, and Go read them — see Connect to GO Feature Flag.

Hosting integration health checks

The GO Feature Flag hosting integration automatically adds a health check for the relay proxy resource. The health check verifies that the relay proxy is running and reachable by calling its /health endpoint.