Files

Joseph Doherty de636b908b Add Akka.NET reference documentation

Notes and documentation covering actors, remoting, clustering, persistence,
streams, serialization, hosting, testing, and best practices for the Akka.NET
framework used throughout the ScadaLink system.

2026-03-16 09:08:17 -04:00

4.2 KiB

Raw Blame History

14 — Management (Akka.Management)

Overview

Akka.Management exposes HTTP endpoints for cluster health checks, membership information, and Cluster Bootstrap coordination. It is primarily used in dynamic environments (Kubernetes, cloud) where nodes need to discover and coordinate with each other via HTTP probes.

In the SCADA system, Management is useful for providing HTTP health check endpoints that operations tools (load balancers, monitoring systems, Windows Service health probes) can query to verify the Akka.NET cluster is functioning.

When to Use

Exposing an HTTP health check endpoint for monitoring tools or Windows Service health checks
If the system ever moves to containerized deployments where Cluster Bootstrap replaces static seed nodes
Providing operational visibility into cluster membership state via HTTP

When Not to Use

As a general-purpose HTTP API for the SCADA system — use ASP.NET Core for that
For equipment communication — Management HTTP endpoints are for cluster operations only

Design Decisions for the SCADA System

Health Check Endpoint

Configure Akka.Management to expose a simple HTTP health check on a management port:

akkaBuilder.WithAkkaManagement(options =>
{
    options.Port = 8558;
    options.Hostname = "0.0.0.0";
});

This provides endpoints like:

GET /cluster/members — current cluster membership
GET /cluster/health — cluster health status
GET /alive — basic liveness probe
GET /ready — readiness probe (cluster joined and stable)

Windows Service Health Integration

Use the Management health endpoint to report Akka.NET cluster health as part of the Windows Service's health reporting:

// In a health check service
public class AkkaHealthCheck : IHealthCheck
{
    public async Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context, CancellationToken ct)
    {
        try
        {
            using var client = new HttpClient();
            var response = await client.GetAsync("http://localhost:8558/ready", ct);
            return response.IsSuccessStatusCode
                ? HealthCheckResult.Healthy("Akka cluster ready")
                : HealthCheckResult.Degraded("Akka cluster not ready");
        }
        catch (Exception ex)
        {
            return HealthCheckResult.Unhealthy("Akka management unreachable", ex);
        }
    }
}

Port Selection

Use a dedicated port (8558 is the convention) separate from Akka.Remote's port (4053). Ensure Windows Firewall allows this port on both nodes.

Common Patterns

Cluster Bootstrap (Future Use)

If the system moves to dynamic infrastructure:

akkaBuilder
    .WithAkkaManagement(port: 8558)
    .WithClusterBootstrap(
        serviceName: "scada-cluster",
        requiredContactPoints: 2);

requiredContactPoints: 2 ensures both nodes must be visible before forming a cluster — preventing a single node from bootstrapping alone and creating a split-brain situation.

Operational Monitoring

Periodically poll the /cluster/members endpoint from an external monitoring system to track cluster state:

GET http://nodeA.scada.local:8558/cluster/members

{
  "selfNode": "akka.tcp://scada-system@nodeA.scada.local:4053",
  "members": [...],
  "unreachable": [...]
}

Anti-Patterns

Exposing Management Port to Equipment Network

The Management HTTP endpoint should only be accessible on the management/corporate network, not the equipment network. Equipment should never be able to reach cluster management endpoints.

Using Management as a REST API

Management endpoints are for cluster operations, not application logic. Do not add custom routes for SCADA operations (command dispatch, alarm query) to the Management HTTP server. Use ASP.NET Core for that.

Configuration Guidance

akka.management {
  http {
    hostname = "0.0.0.0"
    port = 8558
    route-providers-read-only = true  # Only expose read endpoints
  }
}

Firewall Rules

Ensure port 8558 is open between the two SCADA nodes and from the monitoring network. Block access from the equipment network.

References

Official Documentation: https://getakka.net/articles/discovery/akka-management.html
GitHub: https://github.com/akkadotnet/Akka.Management

4.2 KiB Raw Blame History