CommunityToolkit / CommunityToolkit/Aspire
Add an Aspire.Hosting.AWS extension for Floci
- Dominant language
- C#
- Stars
- 627
- Forks
- 196
- Avg merge
- 2d 11h
- Merged PRs (30d)
- 35
Description
### 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:
```csharp
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:
```csharp
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):
```csharp
var stack = builder
.AddAWSCloudFormationStack("existing-stack")
.WithReference(floci);
```
A resource consuming stack outputs would automatically receive the Floci reference:
```csharp
builder.AddProject("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
Contributor guide
Research direction
Start by reading the existing CommunityToolkit.Aspire.Hosting.Floci integration and the Aspire.Hosting.AWS resource builders for CloudFormation templates, imported stacks, and CDK stacks. Review the prototype branch and the proposed unit, end-to-end, example, documentation, and API baseline coverage. Done means a companion package supports Floci references, startup relationships, and reference propagation for all three stack types.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, csharp
- Domain
- backend, cloud
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100