Add an Aspire.Hosting.AWS extension for Floci

[0mar-rivero]

Related to an existing integration?

Yes

Existing integration

CommunityToolkit.Aspire.Hosting.Floci

Overview

I propose adding a companion package named CommunityToolkit.Aspire.Hosting.Floci.AWS.

The existing Floci integration provides a local AWS emulator and configures application resources through standard AWS SDK environment variables. However, CloudFormation templates and CDK stacks created with Aspire.Hosting.AWS cannot currently be directed to Floci through Aspire resource references.

The proposed package would extend the existing Aspire.Hosting.AWS resource builders. Developers could call WithReference(floci) on a CloudFormation template, imported stack, or CDK stack to run it against Floci during local development.

Resources consuming outputs from a Floci-backed stack would also inherit the Floci reference, endpoint, credentials, region, and startup dependency.

This would be an extension of the existing Floci integration, not a replacement for AddFlociAws or a separate API for defining AWS resources.

Usage example

A normal Aspire.Hosting.AWS CDK stack could be directed to Floci by adding a reference:

var builder = DistributedApplication.CreateBuilder(args);

var floci = builder.AddFlociAws("floci");

var stack = builder
    .AddAWSCDKStack("aws-resources")
    .WithReference(floci);

stack.AddConstruct(stack =>
{
    _ = new Amazon.CDK.AWS.SQS.Queue(stack, "queue");
});

builder.Build().Run();

The same reference would work with a CloudFormation template:

var stack = builder
    .AddAWSCloudFormationTemplate("aws-resources", "resources.yaml")
    .WithReference(floci);

It would also work with an imported stack (considering there is a deployed stack in the container):

var stack = builder
    .AddAWSCloudFormationStack("existing-stack")
    .WithReference(floci);

A resource consuming stack outputs would automatically receive the Floci reference:

builder.AddProject<Projects.Api>("api")
    .WithReference(stack);

Breaking change?

No

Alternatives

Developers can currently configure the AWS SDK and CDK endpoint settings manually, invoke CDK or CloudFormation deployment commands outside Aspire, or inject Floci environment variables into each dependent resource.

Those approaches do not establish normal Aspire resource relationships, startup ordering, or automatic reference propagation from a stack to its consumers. They also require applications to understand and maintain the underlying AWS and Floci configuration details.

Another option is to define AWS resources through an emulator-specific API. The proposed integration avoids that approach and continues using the official Aspire.Hosting.AWS CloudFormation and CDK resource builders.

Additional context

The implementation would be isolated in a new companion package and would not modify CommunityToolkit.Aspire.Hosting.Floci.

CloudFormation and CDK support would initially be C#-only because those Aspire.Hosting.AWS resource types are not currently exposed to polyglot AppHosts. The package would explicitly declare that it is not polyglot compatible rather than exposing custom replacement APIs.

The proposed contribution includes:

• Support for CloudFormation templates, imported stacks, and CDK stacks
• Aspire startup relationships between AWS resources and Floci
• Reference propagation to resources consuming stack outputs
• Coexistence with DynamoDB Local and other local services available in Aspire.Hosting.AWS through their service-specific endpoint
• A dedicated C# CDK example
• Unit tests for configuration and reference propagation
• An end-to-end test that provisions an SQS queue through CDK and Floci
• Package documentation and API baseline coverage

I have prepared a prototype implementation on my fork to validate the API and end-to-end behavior:

https://github.com/0mar-rivero/Aspire/tree/feature/floci-aws-integration

I am happy to adjust the API or scope based on maintainer feedback before opening a pull request.

Help us help you

Yes, I'd like to be assigned to work on this item

[github-actions]

We have noticed this issue has not been updated within 21 days. If there is no action on this issue in the next 14 days, we will automatically close it. You can use /stale-extend to extend the window.

[0mar-rivero]

/stale-extend