akka-net-management

Akka.NET の管理とサービスディスカバリー

このスキルを使用する場面

次の場合にこのスキルを使用します：

• Akka.NET クラスターを Kubernetes またはクラウド環境にデプロイする
• 静的なシードノードを動的なサービスディスカバリーに置き換える
• 自動形成のためのクラスター・ブートストラップを設定する
• ロードバランサー向けのヘルスエンドポイントを設定する
• Azure Table Storage、Kubernetes API、または設定ベースのディスカバリーと統合する

参照ファイル

• discovery-providers.md：完全なコードとデプロイ用 YAML を含む、Config、Kubernetes、Azure のディスカバリー設定
• configuration-reference.md：強い型付けを使用した設定モデルクラス

概要

Akka.Management はクラスター管理用の HTTP エンドポイントを提供し、Akka.Cluster.Bootstrap と統合することで、静的なシードノードの代わりにサービスディスカバリーを使用した動的なクラスター形成を可能にします。

Akka.Management を使用する理由

アプローチ	メリット	デメリット
静的シードノード	シンプルで、依存関係がありません	スケールせず、既知の IP が必要です
Akka.Management	動的なディスカバリーが可能で、N 個のノードにスケールします	設定が増え、外部依存関係があります

静的シードノードを使用する場面：開発、単一ノードのデプロイ、固定されたインフラストラクチャ。

Akka.Management を使用する場面：Kubernetes、自動スケーリンググループ、動的な環境、本番クラスター。

---

アーキテクチャ

┌─────────────────────────────────────────────────────────────┐
│                    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)  │
        └───────────┘ └────────────┘ └────────────┘

---

必須の NuGet パッケージ

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

  
  <PackageReference Include="Akka.Discovery.KubernetesApi" />    
  <PackageReference Include="Akka.Discovery.Azure" />            
  <PackageReference Include="Akka.Discovery.Config.Hosting" />   
</ItemGroup>

---

Akka.Hosting の設定

モードを選択する基本設定

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 の設定

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);
}

Config、Kubernetes、Azure のディスカバリー設定コードの全体については、discovery-providers.md を参照してください。

強い型付けを使用した設定モデルクラスの全体については、configuration-reference.md を参照してください。

---

ヘルスエンドポイント

Akka.Management は、ロードバランサーとオーケストレーター向けのヘルスエンドポイントを公開します。

エンドポイント	用途	200 を返す条件
/alive	生存確認	ActorSystem が実行中
/ready	準備状態の確認	クラスターのメンバーが Up
/cluster/members	デバッグ	クラスターのメンバーシップを返す

ASP.NET Core のヘルスチェック統合

// 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")
});

---

トラブルシューティング

クラスターが形成されない

**症状：**ノードが個別の単一ノードクラスターのままになります。

チェックリスト：

1. すべてのノードで同じ ServiceName を使用している
2. RequiredContactPointsNr が実際のレプリカ数と一致している
3. ディスカバリープロバイダーが正しく設定されている
4. ネットワークで管理ポート（8558）の通信が許可されている
5. Kubernetes の場合：RBAC 権限が設定されている

スプリットブレイン

**症状：**1 つではなく複数のクラスターが形成されます。

解決策：

1. ContactWithAllContactPoints = true を設定する
2. 動作の遅い環境では StableMargin を大きくする
3. Aspire の場合：FilterOnFallbackPort = false を設定する（動的ポート）
4. Kubernetes の場合：FilterOnFallbackPort = true を設定する（固定ポート）

Azure ディスカバリーの問題

**症状：**ノードが Azure Tables 経由で互いを検出できません。

チェックリスト：

1. 接続文字列が有効である
2. ストレージアカウントでテーブル操作が許可されている
3. すべてのノードで同じ ServiceName を使用している
4. ファイアウォールで Azure Storage へのアクセスが許可されている

---

Aspire との統合

Aspire 固有のパターンの詳細については、akka-net-aspire-configuration スキルを参照してください。

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");

---

まとめ：用途に応じた選択

シナリオ	ディスカバリー方法	FilterOnFallbackPort
ローカル開発（単一ノード）	なし（シードノードを使用）	N/A
Aspire のマルチノード	AzureTableStorage	false
Kubernetes	Kubernetes	true
Azure VM／VMSS	AzureTableStorage	true
固定されたインフラストラクチャ	Config	true
AWS ECS／EC2	AWS ディスカバリープラグイン	true