Summary Akka.Management for cluster bootstrapping, service discovery (Kubernetes, Azure, Config), health checks, and dynamic cluster formation without static seed nodes.
Akka.NET Management and Service Discovery
When to Use This Skill
Use this skill when:
Deploying Akka.NET clusters to Kubernetes or cloud environments
Replacing static seed nodes with dynamic service discovery
Configuring cluster bootstrap for auto-formation
Setting up health endpoints for load balancers
Integrating with Azure Table Storage, Kubernetes API, or config-based discovery
Reference Files
Overview
Akka.Management provides HTTP endpoints for cluster management and integrates with Akka.Cluster.Bootstrap to enable dynamic cluster formation using service discovery instead of static seed nodes.
Why Use Akka.Management?
Approach Pros Cons Static Seed Nodes Simple, no dependencies Doesn't scale, requires known IPs Akka.Management Dynamic discovery, scales to N nodes More configuration, external dependencies
Use static seed nodes for: Development, single-node deployments, fixed infrastructure.
Use Akka.Management for: Kubernetes, auto-scaling groups, dynamic environments, production clusters.
Architecture
┌─────────────────────────────────────────────────────────────┐
│ Cluster Bootstrap │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Node 1 │ │ Node 2 │ │ Node 3 │ │
│ │ │ │ │ │ │ │
│ │ Management │◄──►│ Management │◄──►│ Management │ │
│ │ HTTP :8558 │ │ HTTP :8558 │ │ HTTP :8558 │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ └──────────────────┼──────────────────┘ │
│ │ │
│ ┌───────▼───────┐ │
│ │ Discovery │ │
│ │ Provider │ │
│ └───────────────┘ │
│ │ │
└────────────────────────────┼────────────────────────────────┘
│
┌──────────────┼──────────────┐
│ │ │
┌─────▼─────┐ ┌──────▼─────┐ ┌─────▼──────┐
│ Kubernetes│ │ Azure │ │ Config │
│ API │ │ Tables │ │ (HOCON) │
└───────────┘ └────────────┘ └────────────┘
Required NuGet Packages <ItemGroup>
<!-- Core management -->
<PackageReference Include="Akka.Management" />
<PackageReference Include="Akka.Management.Cluster.Bootstrap" />
<!-- Choose ONE discovery provider -->
<PackageReference Include="Akka.Discovery.KubernetesApi" /> <!-- For Kubernetes -->
<PackageReference Include="Akka.Discovery.Azure" /> <!-- For Azure -->
<PackageReference Include="Akka.Discovery.Config.Hosting" /> <!-- For static config -->
</ItemGroup>
Akka.Hosting Configuration
Basic Setup with Mode Selection public static class AkkaConfiguration
{
public static IServiceCollection ConfigureAkka(
this IServiceCollection services,
Action<AkkaConfigurationBuilder, IServiceProvider>? additionalConfig = null)
{
services.AddOptions<AkkaSettings>()
.BindConfiguration("AkkaSettings")
.ValidateDataAnnotations()
.ValidateOnStart();
return services.AddAkka("MySystem", (builder, sp) =>
{
var settings = sp.GetRequiredService<IOptions<AkkaSettings>>().Value;
var configuration = sp.GetRequiredService<IConfiguration>();
ConfigureNetwork(builder, settings, configuration);
ConfigureHealthChecks(builder);
additionalConfig?.Invoke(builder, sp);
});
}
private static void ConfigureNetwork(
AkkaConfigurationBuilder builder,
AkkaSettings settings,
IConfiguration configuration)
{
if (settings.ExecutionMode == AkkaExecutionMode.LocalTest)
return;
builder.WithRemoting(settings.RemoteOptions);
if (settings.ClusterBootstrapOptions.Enabled)
ConfigureAkkaManagement(builder, settings, configuration);
else
builder.WithClustering(settings.ClusterOptions);
}
}
Akka.Management Configuration private static void ConfigureAkkaManagement(
AkkaConfigurationBuilder builder,
AkkaSettings settings,
IConfiguration configuration)
{
var mgmtOptions = settings.AkkaManagementOptions;
var bootstrapOptions = settings.ClusterBootstrapOptions;
// IMPORTANT: Clear seed nodes when using Akka.Management
settings.ClusterOptions.SeedNodes = [];
builder
.WithClustering(settings.ClusterOptions)
.WithAkkaManagement(setup =>
{
setup.Http.HostName = mgmtOptions.HostName;
setup.Http.Port = mgmtOptions.Port;
setup.Http.BindHostName = "0.0.0.0";
setup.Http.BindPort = mgmtOptions.Port;
})
.WithClusterBootstrap(options =>
{
options.ContactPointDiscovery.ServiceName = bootstrapOptions.ServiceName;
options.ContactPointDiscovery.PortName = bootstrapOptions.PortName;
options.ContactPointDiscovery.RequiredContactPointsNr = bootstrapOptions.RequiredContactPointsNr;
options.ContactPointDiscovery.Interval = bootstrapOptions.ContactPointProbingInterval;
options.ContactPointDiscovery.StableMargin = bootstrapOptions.StableMargin;
options.ContactPointDiscovery.ContactWithAllContactPoints = bootstrapOptions.ContactWithAllContactPoints;
options.ContactPoint.FilterOnFallbackPort = bootstrapOptions.FilterOnFallbackPort;
options.ContactPoint.ProbeInterval = bootstrapOptions.BootstrapperDiscoveryPingInterval;
});
// Configure the discovery provider
ConfigureDiscovery(builder, settings, configuration);
}
Health Endpoints Akka.Management exposes health endpoints for load balancers and orchestrators:
Endpoint Purpose Returns 200 When /aliveLiveness ActorSystem is running /readyReadiness Cluster member is Up /cluster/membersDebug Returns cluster membership
ASP.NET Core Health Check Integration // Register Akka health checks
builder.Services.AddHealthChecks();
// In Akka configuration
builder
.WithActorSystemLivenessCheck() // Adds "akka-liveness" health check
.WithAkkaClusterReadinessCheck(); // Adds "akka-cluster-readiness" health check
// Map endpoints
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
Predicate = check => check.Tags.Contains("liveness")
});
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
Predicate = check => check.Tags.Contains("readiness")
});
Troubleshooting
Cluster Won't Form Symptoms: Nodes stay as separate single-node clusters.
All nodes use same ServiceName
RequiredContactPointsNr matches actual replica countDiscovery provider is configured correctly
Network allows traffic on management port (8558)
For Kubernetes: RBAC permissions are set
Split Brain Symptoms: Multiple clusters form instead of one.
Set ContactWithAllContactPoints = true
Increase StableMargin for slower environments
For Aspire: Set FilterOnFallbackPort = false (dynamic ports)
For Kubernetes: Set FilterOnFallbackPort = true (fixed ports)
Azure Discovery Issues Symptoms: Nodes can't find each other via Azure Tables.
Connection string is valid
Storage account allows table operations
All nodes use same ServiceName
Firewall allows access to Azure Storage
Aspire Integration For detailed Aspire-specific patterns, see the akka-net-aspire-configuration skill.
Quick reference for Aspire:
// In AppHost
appBuilder
.WithEndpoint(name: "remote", protocol: ProtocolType.Tcp,
env: "AkkaSettings__RemoteOptions__Port")
.WithEndpoint(name: "management", protocol: ProtocolType.Tcp,
env: "AkkaSettings__AkkaManagementOptions__Port")
.WithEnvironment("AkkaSettings__ClusterBootstrapOptions__Enabled", "true")
.WithEnvironment("AkkaSettings__ClusterBootstrapOptions__DiscoveryMethod", "AzureTableStorage")
.WithEnvironment("AkkaSettings__ClusterBootstrapOptions__FilterOnFallbackPort", "false");
Summary: When to Use What Scenario Discovery Method FilterOnFallbackPort Local development (single node) None (use seed nodes) N/A Aspire multi-node AzureTableStorage falseKubernetes Kubernetes trueAzure VMs/VMSS AzureTableStorage trueFixed infrastructure Config trueAWS ECS/EC2 AWS discovery plugins true
