Closed KrzysFR closed 2 months ago
Aspire 8.0 is officially released, and is ~fully supported.
I'm marking this as closed as it was for the initial preview. See below for known issues that would need to be addressed as some point.
A sample AppHost looks like this:
private static void Main(string[] args)
{
var builder = DistributedApplication.CreateBuilder(args);
// we need a FoundationDB Cluster
var fdb = builder
.AddFoundationDb("fdb", apiVersion: 720, root: "/MyAwesomeApp", clusterVersion: "7.3.47", rollForward: FdbVersionPolicy.Exact)
.WithDefaults(timeout: TimeSpan.FromSeconds(15), retryLimit: 10, tracing: FdbTracingOptions.All);
// we have an API server that uses FoundationDB
var api = builder
.AddProject<Projects.My_Awesome_Api_Project>("api")
.WithReference(fdb);
// we also have a "frontend" server that uses FoundationDB as well
var frontend = builder
.AddProject<Projects.My_Awesome_Frontend_Project>("frontend")
.WithReference(fdb);
// ....
builder.Build().Run();
}
Using Aspire for the "local dev loop", this will run a single local node using Docker, and automatically inject the connection string to the "api" project.
After using it for a while, there are several issues that are still pending:
fdbcli
does not have any way to pass the connection string as argument from the command line. You have to create a custom .cluster file on disk and pass the path to this file. This is the only tool that requires this, as all the other features pass the connection string in memory.All of these are not deal breaker, but this means that there is a need for a better "out of the box" experience:
We live in interesting times: https://learn.microsoft.com/en-us/dotnet/aspire/get-started/aspire-overview
Documentation on how to create a new component is a bit scarce for the moment, but I was able to create a first prototype of a FoundationDB aspire component.
Integration with the AppHost and projects
Example of an AppHost:
Here, we will setup a "transient" fdb cluster using a locally started foundationdb docker image (https://hub.docker.com/r/foundationdb/foundationdb), using a local instance of Docker (support windows, linux, macos).
The "connection string" that we generate for the cluster includes the selected API version (
720
), the root path of the application in the cluster (/Sandbox/MySuperApp
), and we select an exact version for the FoundationDB cluster (7.2.5
).This connection string will be available to the backend process (via environment variables) which will automatically configure a local
FdbDatabaseProvider
with the same settings.In the backend startup logic, instead of adding a regular fdb database provider, we can use the new extension method:
At runtime
Running the AppHost inside Visual Studio (F5) we see that a new docker container is started and listening on port 4550:
And it is also visible in the Aspire Dashboard:
The docker image is configured with the following variables:
The connection string is injected inside the 'backend' process via the
ConnectionStrings__fdb
variable with valueApiVersion=720;Root=/Sandbox/Syracuse;ClusterFileContents=docker:docker@127.0.0.1:4550;ClientVersion=7.2.5
, which is then picked up during startup to setup the database provider:Issues
I encountered the following issues:
Cannot override the ENTRYPOINT of an Aspire container resource
The foundationdb docker starts the
fdb.bash
entrypoint which will connect the node to an existing cluster.For local, single-node development, we need to run
configure new single ...
at least once to initialize the cluster. The docker image contains another alternative entrypointfdb-single.bash
which would do that, but Aspire (preview2) does not expose a way to override the ENTRYPOINT. Snooping in the code, there is a "Command" property on the ContainerSpec object, but I don't find any obvious way to change this value (the value is not assigned anywhere in the current Aspire preview).Currently, I have to copy the cluster file somewhere, and run
fdbcli -C path/to/file.cluster --exec "configure new single memory"
manually from the host.The docker is stopped and restarted on every start of the application, which means all data is lost. I'm adding volume mount from
/var/fdb/data
to a temp folder, but doing this with Docker for Windows, and using the wsl2 backend, crashes the fdbserver (probably having a volume mount on a docker linux image, through docker, to a windows NTFS partition is creating some issues).I'm using a named volume mount instead, to work around this issue, but I can only one per container.
Custom cluster file contents requires a temp local file
The docker image will accept a
FDB_CLUSTER_CONTENTS
parameter, but there is nothing similar in the fdb C api, which means the backend process in our example above needs to write a file somewhere on the disk, withdocker:docker@127.0.0.1:4550
and then pass the path to this file when connecting to the database.This creates a few issues like requiring write permissions on the local folder where the binary are deployed, OR find a temp folder that is writable.
No easy way to manage version roll forwar policy with docker image
The
foundationdb
docker image has alatest
tag, and then one tag per version, but there is not "latest per minor or major version" tag, like for example "7.2-latest" or "7.x-latest" which could be used to easily select the last compatible version.For now, I have hardcoded a set of versions for 7.1 / 7.2 and 7.3 in the code, but this is not ideal.
I tried looking at the Docker API to fetch the list of tags, but 1) this API has already changed (now in v2) 2) the code path in the Aspire AppHost that has to configure the resources is NOT async, and doing HTTP requests to the cloud would cause issues 3) the CI server would need access to the cloud, 4) it could be throttled by DockerHub
Requires Aspire preview 2 which is not public yet
There is a nasty bug in preview 1 where it will not use the correct service ports (and instead use random ports), which has been fixed in the repo, but not yet available on the public nuget feed.
I'm currently using the daily build feed that has this issue fixed, see https://github.com/dotnet/aspire/blob/main/docs/using-latest-daily.md
You MUST update the aspire workload and tooling, or else it will fail at runtime (dcp reconcilier errors).