akka-net-management

Akka.NET Verwaltung und Service Discovery

Wann dieses Skill verwenden

Verwenden Sie dieses Skill, wenn:

• Akka.NET Cluster in Kubernetes oder Cloud-Umgebungen bereitgestellt werden
• Statische Seed-Knoten durch dynamische Service Discovery ersetzt werden sollen
• Cluster Bootstrap für automatische Formation konfiguriert wird
• Health-Endpunkte für Load Balancer eingerichtet werden
• Eine Integration mit Azure Table Storage, Kubernetes API oder konfigurationsbasierter Discovery erforderlich ist

Referenzdateien

• discovery-providers.md: Konfiguration, Kubernetes und Azure Discovery Einrichtung mit vollständigem Code und Deployment-YAML
• configuration-reference.md: Stark typisierte Konfigurationsmodellklassen

Überblick

Akka.Management stellt HTTP-Endpunkte für die Clusterverwaltung bereit und integriert sich mit Akka.Cluster.Bootstrap, um eine dynamische Clusterbildung mittels Service Discovery anstelle statischer Seed-Knoten zu ermöglichen.

Warum Akka.Management verwenden?

Ansatz	Vorteile	Nachteile
Statische Seed-Knoten	Einfach, keine Abhängigkeiten	Skaliert nicht, erfordert bekannte IPs
Akka.Management	Dynamische Discovery, skaliert auf N Knoten	Mehr Konfiguration, externe Abhängigkeiten

Statische Seed-Knoten verwenden für: Entwicklung, Einzelknoten-Bereitstellungen, feste Infrastruktur.

Akka.Management verwenden für: Kubernetes, Auto-Scaling-Gruppen, dynamische Umgebungen, Produktionscluster.

---

Architektur

┌─────────────────────────────────────────────────────────────┐
│                    Cluster Bootstrap                         │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │  Knoten 1   │    │  Knoten 2   │    │  Knoten 3   │     │
│  │             │    │             │    │             │     │
│  │ Management  │◄──►│ Management  │◄──►│ Management  │     │
│  │ HTTP :8558  │    │ HTTP :8558  │    │ HTTP :8558  │     │
│  └──────┬──────┘    └──────┬──────┘    └──────┬──────┘     │
│         │                  │                  │             │
│         └──────────────────┼──────────────────┘             │
│                            │                                │
│                    ┌───────▼───────┐                        │
│                    │   Discovery   │                        │
│                    │   Provider    │                        │
│                    └───────────────┘                        │
│                            │                                │
└────────────────────────────┼────────────────────────────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
        ┌─────▼─────┐ ┌──────▼─────┐ ┌─────▼──────┐
        │ Kubernetes│ │   Azure    │ │   Config   │
        │    API    │ │   Tables   │ │   (HOCON)  │
        └───────────┘ └────────────┘ └────────────┘

---

Erforderliche NuGet-Pakete

<ItemGroup>
  <!-- Kernverwaltung -->
  <PackageReference Include="Akka.Management" />
  <PackageReference Include="Akka.Management.Cluster.Bootstrap" />

  <!-- Wählen Sie EINEN Discovery-Provider -->
  <PackageReference Include="Akka.Discovery.KubernetesApi" />    <!-- Für Kubernetes -->
  <PackageReference Include="Akka.Discovery.Azure" />            <!-- Für Azure -->
  <PackageReference Include="Akka.Discovery.Config.Hosting" />   <!-- Für statische Konfiguration -->
</ItemGroup>

---

Akka.Hosting Konfiguration

Grundlegende Einrichtung mit Modusauswahl

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 Konfiguration

private static void ConfigureAkkaManagement(
    AkkaConfigurationBuilder builder,
    AkkaSettings settings,
    IConfiguration configuration)
{
    var mgmtOptions = settings.AkkaManagementOptions;
    var bootstrapOptions = settings.ClusterBootstrapOptions;

    // WICHTIG: Seed-Knoten löschen, wenn Akka.Management verwendet wird
    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;
        });

    // Den Discovery-Provider konfigurieren
    ConfigureDiscovery(builder, settings, configuration);
}

Siehe discovery-providers.md für vollständigen Konfigurations-, Kubernetes- und Azure-Discovery-Einrichtungscode.

Siehe configuration-reference.md für die vollständigen stark typisierten Konfigurationsmodellklassen.

---

Health-Endpunkte

Akka.Management stellt Health-Endpunkte für Load Balancer und Orchestratoren bereit:

Endpunkt	Zweck	Gibt 200 zurück wenn
/alive	Lebendigkeit	ActorSystem läuft
/ready	Bereitschaft	Cluster-Mitglied ist Up
/cluster/members	Debug	Gibt Cluster-Mitgliedschaft zurück

ASP.NET Core Health Check Integration

// Akka Health Checks registrieren
builder.Services.AddHealthChecks();

// In der Akka-Konfiguration
builder
    .WithActorSystemLivenessCheck()     // Fügt „akka-liveness" Health Check hinzu
    .WithAkkaClusterReadinessCheck();   // Fügt „akka-cluster-readiness" Health Check hinzu

// Endpunkte definieren
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("liveness")
});

app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("readiness")
});

---

Fehlerbehebung

Cluster bildet sich nicht

Symptome: Knoten bleiben als separate Einzelknoten-Cluster.

Checkliste:

1. Alle Knoten verwenden denselben ServiceName
2. RequiredContactPointsNr entspricht der tatsächlichen Replikatanzahl
3. Discovery-Provider ist korrekt konfiguriert
4. Netzwerk erlaubt Verkehr auf dem Verwaltungsport (8558)
5. Für Kubernetes: RBAC-Berechtigungen sind gesetzt

Split Brain

Symptome: Es bilden sich mehrere Cluster anstelle eines einzigen.

Lösungen:

1. Setzen Sie ContactWithAllContactPoints = true
2. Erhöhen Sie StableMargin für langsamere Umgebungen
3. Für Aspire: Setzen Sie FilterOnFallbackPort = false (dynamische Ports)
4. Für Kubernetes: Setzen Sie FilterOnFallbackPort = true (feste Ports)

Azure Discovery Probleme

Symptome: Knoten können einander nicht über Azure Tables finden.

Checkliste:

1. Verbindungszeichenfolge ist gültig
2. Storage-Konto erlaubt Tabellenoperationen
3. Alle Knoten verwenden denselben ServiceName
4. Firewall erlaubt Zugriff auf Azure Storage

---

Aspire Integration

Ausführliche Aspire-spezifische Muster finden Sie im Skill akka-net-aspire-configuration.

Kurzreferenz für 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");

---

Zusammenfassung: Wann was verwenden

Szenario	Discovery-Methode	FilterOnFallbackPort
Lokale Entwicklung (einzelner Knoten)	Keine (Seed-Knoten verwenden)	N/A
Aspire Multi-Knoten	AzureTableStorage	false
Kubernetes	Kubernetes	true
Azure VMs/VMSS	AzureTableStorage	true
Feste Infrastruktur	Config	true
AWS ECS/EC2	AWS Discovery-Plugins	true