moin.aspire.hosting.akka 0.2.1

moin.aspire.hosting.akka

.NET Aspire Hosting Integration for Akka.NET - Because distributed actor systems deserve proper orchestration

<p align="center"> <img width="128" height="128" src="docs/logo/logo.png" alt="signal bot logo"> </p>

Overview

moin.aspire.hosting.akka bridges the gap between .NET Aspire and Akka.NET. If you want to build modern cloud-native applications with the Actor Model but don't want to sacrifice Aspire's orchestration, service discovery, and developer experience - this integration is for you.

This library provides seamless integration of Akka.NET into the .NET Aspire hosting model with built-in support for Lighthouse-based cluster discovery, making it as simple as possible to define and orchestrate Akka.NET-based microservices in your Aspire AppHost.

Why moin.aspire.hosting.akka?

• Aspire-First Design: Seamless integration into the Aspire ecosystem
• Lighthouse Support: Built-in Lighthouse nodes for automatic cluster discovery
• Type-Safe Configuration: Strongly-typed APIs for Akka.NET cluster configuration
• Service Discovery: Automatic integration with Aspire service discovery
• Developer Experience: Debug multi-node Akka.NET clusters locally without complex setups
• Production Ready: From development to deployment - consistent and reliable
• Observability: Full integration with Aspire Dashboard for monitoring and tracing

Prerequisites

Before you can use moin.aspire.hosting.akka, you need:

• .NET 8.0 SDK or higher
• .NET Aspire Workload installed
• Docker for running containerized Akka.NET nodes
• Akka.NET knowledge (recommended)

⚠️ Deployment Model Limitation

Important: moin.aspire.hosting.akka currently supports only homogeneous deployment models.

This means:

• ✅ All Akka nodes must be Docker-based (AddDockerfile)

  or

• ✅ All Akka nodes must be Project-based (AddProject)

• ❌ Mixing Docker containers and project references within the same Akka cluster is not supported

Why?

.NET Aspire treats Docker resources and project resources differently in terms of:

• networking
• service discovery
• endpoint resolution
• lifecycle management

Akka.NET clustering (especially Lighthouse-based discovery) requires consistent addressing and networking semantics across all nodes.
A mixed environment would result in invalid seed node addresses and unstable cluster formation.

Support for mixed environments may be evaluated in the future, but is currently out of scope.

Install .NET Aspire Workload

dotnet workload update
dotnet workload install aspire

Create New Aspire Project (Optional)

dotnet new aspire-starter -n MyAkkaApp
cd MyAkkaApp

Installation

Package Manager

Install-Package moin.aspire.hosting.akka

.NET CLI

dotnet add package moin.aspire.hosting.akka

PackageReference

<PackageReference Include="moin.aspire.hosting.akka" Version="1.0.0" />

Quick Start

Here's the complete example from the repository showing how to set up a multi-node Akka.NET cluster with Lighthouse in your Aspire AppHost:

1. AppHost Configuration

var builder = DistributedApplication.CreateBuilder(args);

// Define first Akka node
var nodeOne = builder
    .AddDockerfile("AkkaNodeOne", "../../", "example/akka.node.one/Dockerfile")
    .WithContainerName("akka.node.one")
    .WithImageRegistry("localhost")
    .WithImageTag("dev")
    .WithEnvironment("ASPNETCORE_ENVIRONMENT", builder.Environment.EnvironmentName)
    .WithOtlpExporter()
    .WithHttpEndpoint(targetPort: 8080)
    .WithHttpHealthCheck(path: "/health")
    .WithHttpHealthCheck(path: "/alive")
    .WithHttpHealthCheck(path: "/started");

// Define second Akka node
var nodeTwo = builder
    .AddDockerfile("AkkaNodeTwo", "../../", "example/akka.node.two/Dockerfile")
    .WithContainerName("akka.node.two")
    .WithImageRegistry("localhost")
    .WithImageTag("dev")
    .WithEnvironment("ASPNETCORE_ENVIRONMENT", builder.Environment.EnvironmentName)
    .WithOtlpExporter()
    .WithHttpEndpoint(targetPort: 8080)
    .WithHttpHealthCheck(path: "/health")
    .WithHttpHealthCheck(path: "/alive")
    .WithHttpHealthCheck(path: "/started");

// Configure Akka cluster with Lighthouse
builder.AddAkka("akka", "testing", akkaConfigure: akkaBuilder =>
{
    akkaBuilder
        .WithLighthouse(3)  // 3 Lighthouse seed nodes for cluster discovery
        .WithNode(targetPort: 8000, resource: nodeOne, endpointName: "akka")
        .WithNode(targetPort: 8001, resource: nodeTwo, endpointName: "akka");
});

await builder.Build().RunAsync();

2. Akka Node Implementation

Create a typical Akka.NET service that will be containerized:

using Akka.Actor;
using Akka.Hosting;
using Akka.Cluster.Hosting;

var builder = WebApplication.CreateBuilder(args);

// Configure Akka.NET with Lighthouse discovery
builder.Services.AddAkka("testing", (configurationBuilder, provider) =>
{
    configurationBuilder
        .WithRemoting("0.0.0.0", 8000)  // Akka remoting port
        .WithClustering(new ClusterOptions
        {
            Roles = new[] { "worker" }
        })
        .WithActors((system, registry) =>
        {
            var workerActor = system.ActorOf(Props.Create<WorkerActor>(), "worker");
            registry.Register<WorkerActor>(workerActor);
        });
});

// Add health checks
builder.Services.AddHealthChecks()
    .AddCheck("akka", () => HealthCheckResult.Healthy());

var app = builder.Build();

// Health check endpoints
app.MapHealthChecks("/health");
app.MapHealthChecks("/alive");
app.MapHealthChecks("/started");

// API endpoints
app.MapGet("/process/{message}", async (string message, IRequiredActor<WorkerActor> worker) =>
{
    var result = await worker.ActorRef.Ask<string>(new ProcessMessage(message));
    return Results.Ok(new { result });
});

app.Run();

3. Actor Implementation

public class WorkerActor : ReceiveActor
{
    private readonly ILogger<WorkerActor> _logger;

    public WorkerActor(ILogger<WorkerActor> logger)
    {
        _logger = logger;
        
        Receive<ProcessMessage>(msg =>
        {
            _logger.LogInformation("Processing message: {Message}", msg.Content);
            var result = $"Processed: {msg.Content}";
            Sender.Tell(result);
        });
    }
}

public record ProcessMessage(string Content);

4. Dockerfile for Akka Node

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app
EXPOSE 8080
EXPOSE 8000

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["AkkaNode/AkkaNode.csproj", "AkkaNode/"]
RUN dotnet restore "AkkaNode/AkkaNode.csproj"
COPY . .
WORKDIR "/src/AkkaNode"
RUN dotnet build "AkkaNode.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "AkkaNode.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "AkkaNode.dll"]

Usage Examples

Basic Cluster Setup

The simplest way to create an Akka.NET cluster with automatic discovery:

builder.AddAkka("my-cluster", "MyActorSystem", akkaConfigure: akkaBuilder =>
{
    akkaBuilder.WithLighthouse(3);  // 3 Lighthouse nodes for HA
});

Adding Worker Nodes

Register your Akka.NET services as nodes in the cluster:

var worker1 = builder.AddProject<Projects.WorkerService1>("worker1");
var worker2 = builder.AddProject<Projects.WorkerService2>("worker2");

builder.AddAkka("cluster", "MySystem", akkaConfigure: akkaBuilder =>
{
    akkaBuilder
        .WithLighthouse(3)
        .WithNode(targetPort: 8000, resource: worker1, endpointName: "akka")
        .WithNode(targetPort: 8001, resource: worker2, endpointName: "akka");
});

Multiple Clusters

Run multiple independent Akka.NET clusters in the same AppHost:

// Frontend cluster
var frontendNode = builder.AddProject<Projects.FrontendService>("frontend");
builder.AddAkka("frontend-cluster", "FrontendSystem", akkaConfigure: akkaBuilder =>
{
    akkaBuilder
        .WithLighthouse(2)
        .WithNode(targetPort: 8000, resource: frontendNode, endpointName: "akka");
});

// Backend cluster
var backendNode = builder.AddProject<Projects.BackendService>("backend");
builder.AddAkka("backend-cluster", "BackendSystem", akkaConfigure: akkaBuilder =>
{
    akkaBuilder
        .WithLighthouse(2)
        .WithNode(targetPort: 9000, resource: backendNode, endpointName: "akka");
});

With External Resources

Integrate with other Aspire resources like databases and message queues:

var postgres = builder.AddPostgres("postgres").AddDatabase("akka-db");
var redis = builder.AddRedis("redis");

var akkaNode = builder
    .AddProject<Projects.PersistentService>("persistent-service")
    .WithReference(postgres)
    .WithReference(redis);

builder.AddAkka("persistent-cluster", "MySystem", akkaConfigure: akkaBuilder =>
{
    akkaBuilder
        .WithLighthouse(3)
        .WithNode(targetPort: 8000, resource: akkaNode, endpointName: "akka");
});

Scaling Nodes

Use Aspire's replica support for horizontal scaling:

var worker = builder
    .AddProject<Projects.WorkerService>("worker")
    .WithReplicas(5);  // Run 5 instances

builder.AddAkka("scaled-cluster", "MySystem", akkaConfigure: akkaBuilder =>
{
    akkaBuilder
        .WithLighthouse(3)
        .WithNode(targetPort: 8000, resource: worker, endpointName: "akka");
});

Features

moin.aspire.hosting.akka provides comprehensive support for the Akka.NET ecosystem:

• ✅ Lighthouse Integration - Automatic cluster discovery with Lighthouse nodes
• ✅ Multi-Node Clusters - Easy configuration of complex cluster topologies
• ✅ Docker Support - Native support for Dockerfile-based Akka services
• ✅ Service Discovery - Automatic Aspire service discovery integration
• ✅ Health Checks - Built-in health check support for all nodes
• ✅ Observability - Full integration with Aspire Dashboard (metrics, traces, logs)
• ✅ Type-Safe Configuration - Strongly-typed builder API
• ✅ Environment Management - Seamless environment variable injection
• ✅ OTLP Export - OpenTelemetry integration for monitoring
• ✅ Development Mode - Easy local multi-node cluster testing

Architecture

moin.aspire.hosting.akka follows the Aspire hosting model and integrates seamlessly:

┌─────────────────────────────┐
│   Aspire AppHost            │
│   (Program.cs)              │
└──────────┬──────────────────┘
           │
           ▼
┌─────────────────────────────┐
│  moin.aspire.hosting.akka   │  ← This library
│  - AddAkka extension        │
│  - Lighthouse management    │
│  - Node configuration       │
└──────────┬──────────────────┘
           │
           ▼
┌─────────────────────────────┐
│  Lighthouse Seed Nodes      │
│  (Automatic Discovery)      │
└──────────┬──────────────────┘
           │
           ▼
┌─────────────────────────────┐
│  Akka.NET Worker Nodes      │
│  - Docker containers        │
│  - Actor systems            │
│  - Cluster members          │
└─────────────────────────────┘

Lighthouse Configuration

Lighthouse is a discovery service for Akka.NET clusters. moin.aspire.hosting.akka automatically provisions Lighthouse nodes for you:

How It Works

1. Lighthouse Nodes: The library automatically creates the specified number of Lighthouse seed nodes
2. Service Discovery: Worker nodes automatically discover Lighthouse nodes via Aspire service discovery
3. Cluster Formation: Nodes join the cluster by connecting to any available Lighthouse node
4. High Availability: Multiple Lighthouse nodes ensure no single point of failure

Recommended Configuration

// Development: 1-2 Lighthouse nodes
akkaBuilder.WithLighthouse(1);  // Single node for local dev

// Production: 3+ Lighthouse nodes for HA
akkaBuilder.WithLighthouse(3);  // Recommended for production

// High-scale: 5+ Lighthouse nodes
akkaBuilder.WithLighthouse(5);  // For very large clusters

Configuration Options

Environment Variables

The library automatically injects necessary environment variables:

ASPNETCORE_ENVIRONMENT=Development
LIGHTHOUSE_SERVICE_NAME=akka-lighthouse
AKKA_CLUSTER_NAME=testing

Health Check Endpoints

Standard health check endpoints are configured automatically:

• /health - Overall health status
• /alive - Liveness probe (is the service running?)
• /started - Startup probe (is the service ready?)

Custom Configuration

You can add custom configuration to your nodes:

var node = builder
    .AddDockerfile("CustomNode", "../../", "Dockerfile")
    .WithEnvironment("AKKA_CLUSTER_ROLES", "worker,processor")
    .WithEnvironment("AKKA_LOGLEVEL", "DEBUG")
    .WithEnvironment("CUSTOM_SETTING", "value");

builder.AddAkka("cluster", "MySystem", akkaConfigure: akkaBuilder =>
{
    akkaBuilder
        .WithLighthouse(3)
        .WithNode(targetPort: 8000, resource: node, endpointName: "akka");
});

Deployment

Local Development

Run your Akka.NET cluster locally with Aspire:

cd src/AppHost
dotnet run

The Aspire Dashboard will open automatically at http://localhost:15000 where you can:

• Monitor all nodes and their health status
• View logs from all services in real-time
• See distributed traces across the cluster
• Check metrics and performance

Docker Compose

Export your Aspire configuration to Docker Compose:

dotnet publish /p:PublishProfile=DefaultContainer

Kubernetes

Deploy to Kubernetes using Aspire's deployment manifests:

dotnet aspire deploy kubernetes

Example generated manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: akka-lighthouse
spec:
  replicas: 3
  selector:
    matchLabels:
      app: akka-lighthouse
  template:
    metadata:
      labels:
        app: akka-lighthouse
    spec:
      containers:
      - name: lighthouse
        image: petabridge/lighthouse:latest
        ports:
        - containerPort: 4053
          name: akka
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: akka-worker
spec:
  replicas: 5
  selector:
    matchLabels:
      app: akka-worker
  template:
    metadata:
      labels:
        app: akka-worker
    spec:
      containers:
      - name: worker
        image: myakkaservice:latest
        ports:
        - containerPort: 8080
          name: http
        - containerPort: 8000
          name: akka
        env:
        - name: LIGHTHOUSE_SERVICE_NAME
          value: "akka-lighthouse"

Troubleshooting

Nodes not joining the cluster?

• Verify Lighthouse nodes are running (check Aspire Dashboard)
• Ensure the Akka remoting port is correctly configured (default: 8000)
• Check that WithNode targetPort matches your service's remoting port
• Review logs for connection errors

Lighthouse service not found?

• Ensure AddAkka is called before building the app
• Check that the cluster name matches across all nodes
• Verify service discovery is working (check Aspire Dashboard services tab)

Health checks failing?

• Ensure health check endpoints are configured: /health, /alive, /started
• Verify the HTTP endpoint port (typically 8080)
• Check if the service is actually running (docker ps or Aspire Dashboard)

Port conflicts?

• Each node needs unique ports for HTTP and Akka remoting
• Use different targetPort values for each node
• Check for port conflicts with other services: netstat -an | grep <port>

Performance issues?

• Increase Lighthouse node count for larger clusters
• Check resource limits in Docker/Kubernetes
• Review serialization configuration in Akka.NET
• Enable batching for high-throughput scenarios

Best Practices

Development

• Use WithLighthouse(1) for local single-machine development
• Enable detailed logging during development: AKKA_LOGLEVEL=DEBUG
• Use the Aspire Dashboard extensively for debugging
• Keep health check endpoints simple and fast

Production

• Use WithLighthouse(3) or more for high availability
• Implement proper health checks in all services
• Configure resource limits appropriately
• Use meaningful cluster and service names
• Enable split-brain resolver for network partition handling
• Implement graceful shutdown handling

Configuration

• Use environment-specific configuration files
• Leverage Aspire's secret management for sensitive data
• Keep port assignments consistent across environments
• Document custom environment variables
• Use semantic versioning for Docker images

Monitoring

• Monitor cluster membership changes
• Track message throughput and latency
• Set up alerts for node failures
• Use distributed tracing for message flows
• Monitor resource usage (CPU, memory, network)

Common Patterns

Background Worker Pattern

var worker = builder
    .AddProject<Projects.BackgroundWorker>("worker")
    .WithReplicas(3);

builder.AddAkka("workers", "WorkerSystem", akkaConfigure: akkaBuilder =>
{
    akkaBuilder
        .WithLighthouse(2)
        .WithNode(targetPort: 8000, resource: worker, endpointName: "akka");
});

API Gateway + Worker Pattern

var api = builder.AddProject<Projects.ApiGateway>("api");
var worker = builder.AddProject<Projects.Worker>("worker").WithReplicas(5);

builder.AddAkka("system", "MySystem", akkaConfigure: akkaBuilder =>
{
    akkaBuilder
        .WithLighthouse(3)
        .WithNode(targetPort: 8000, resource: api, endpointName: "akka")
        .WithNode(targetPort: 8000, resource: worker, endpointName: "akka");
});

Multi-Tenant Pattern

var tenantA = builder.AddProject<Projects.TenantService>("tenant-a");
var tenantB = builder.AddProject<Projects.TenantService>("tenant-b");

builder.AddAkka("tenant-a-cluster", "TenantA", akkaConfigure: akkaBuilder =>
{
    akkaBuilder.WithLighthouse(2).WithNode(8000, tenantA, "akka");
});

builder.AddAkka("tenant-b-cluster", "TenantB", akkaConfigure: akkaBuilder =>
{
    akkaBuilder.WithLighthouse(2).WithNode(8000, tenantB, "akka");
});

Roadmap

Planned features for upcoming releases:

• Native support for Akka.Management
• Built-in split-brain resolver configuration
• Automatic sharding setup
• Performance profiling integration
• Cluster visualization in Aspire Dashboard
• Support for multiple Akka.NET versions
• Advanced routing strategies
• Metrics aggregation across nodes

Contributing

Contributions are welcome! This library grows with the community's needs.

How to Contribute

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Write tests for your changes
4. Ensure all tests pass: dotnet test
5. Submit a Pull Request

Contribution Guidelines

• Follow existing code style and conventions
• Include unit tests for new features
• Update documentation for API changes
• Keep changes focused and atomic
• Add examples for new features

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Built with ❤️ for the .NET Aspire and Akka.NET communities

For questions, support, or feature requests, please open an issue.

Related Projects

• .NET Aspire - The cloud-native development framework
• Akka.NET - Actor model for .NET
• Akka.Hosting - Hosting infrastructure for Akka.NET
• Lighthouse - Service discovery for Akka.NET clusters
• Petabridge Akka.NET Samples - Code samples for Akka.NET