akka-net-management

Gerenciamento e Descoberta de Serviços Akka.NET

Quando Usar Esta Skill

Use esta skill quando:

• Implantar clusters Akka.NET no Kubernetes ou em ambientes de nuvem
• Substituir nós seed estáticos por descoberta dinâmica de serviços
• Configurar bootstrap de cluster para formação automática
• Configurar endpoints de integridade para balanceadores de carga
• Integrar com Azure Table Storage, API Kubernetes ou descoberta baseada em configuração

Arquivos de Referência

• discovery-providers.md: Configuração de descoberta Config, Kubernetes e Azure com código completo e YAML de implantação
• configuration-reference.md: Classes de modelo de configuração fortemente tipadas

Visão Geral

Akka.Management fornece endpoints HTTP para gerenciamento de cluster e integra-se com Akka.Cluster.Bootstrap para permitir a formação dinâmica de clusters usando descoberta de serviços em vez de nós seed estáticos.

Por que Usar Akka.Management?

Abordagem	Prós	Contras
Nós Seed Estáticos	Simples, sem dependências	Não escala, requer IPs conhecidos
Akka.Management	Descoberta dinâmica, escala para N nós	Mais configuração, dependências externas

Use nós seed estáticos para: Desenvolvimento, implantações de nó único, infraestrutura fixa.

Use Akka.Management para: Kubernetes, grupos de auto-scaling, ambientes dinâmicos, clusters em produção.

---

Arquitetura

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

---

Pacotes NuGet Necessários

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

  <!-- Escolha UM provedor de descoberta -->
  <PackageReference Include="Akka.Discovery.KubernetesApi" />    <!-- Para Kubernetes -->
  <PackageReference Include="Akka.Discovery.Azure" />            <!-- Para Azure -->
  <PackageReference Include="Akka.Discovery.Config.Hosting" />   <!-- Para configuração estática -->
</ItemGroup>

---

Configuração Akka.Hosting

Configuração Básica com Seleção de Modo

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

Configuração do Akka.Management

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

    // IMPORTANTE: Limpar nós seed ao usar 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;
        });

    // Configurar o provedor de descoberta
    ConfigureDiscovery(builder, settings, configuration);
}

Veja discovery-providers.md para o código completo de configuração de descoberta Config, Kubernetes e Azure.

Veja configuration-reference.md para as classes de modelo de configuração fortemente tipadas.

---

Endpoints de Integridade

O Akka.Management expõe endpoints de integridade para balanceadores de carga e orquestradores:

Endpoint	Finalidade	Retorna 200 Quando
/alive	Vivacidade	ActorSystem está em execução
/ready	Prontidão	Membro do cluster está Up
/cluster/members	Depuração	Retorna a associação do cluster

Integração com Health Checks do ASP.NET Core

// Registrar health checks do Akka
builder.Services.AddHealthChecks();

// Na configuração do Akka
builder
    .WithActorSystemLivenessCheck()     // Adiciona o health check "akka-liveness"
    .WithAkkaClusterReadinessCheck();   // Adiciona o health check "akka-cluster-readiness"

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

---

Solução de Problemas

Cluster Não se Forma

Sintomas: Nós permanecem como clusters separados de nó único.

Checklist:

1. Todos os nós usam o mesmo ServiceName
2. RequiredContactPointsNr corresponde ao número real de réplicas
3. O provedor de descoberta está configurado corretamente
4. A rede permite tráfego na porta de gerenciamento (8558)
5. Para Kubernetes: Permissões RBAC estão configuradas

Split Brain

Sintomas: Múltiplos clusters se formam em vez de um.

Soluções:

1. Definir ContactWithAllContactPoints = true
2. Aumentar StableMargin para ambientes mais lentos
3. Para Aspire: Definir FilterOnFallbackPort = false (portas dinâmicas)
4. Para Kubernetes: Definir FilterOnFallbackPort = true (portas fixas)

Problemas com Descoberta Azure

Sintomas: Nós não conseguem se encontrar via Azure Tables.

Checklist:

1. A string de conexão é válida
2. A conta de armazenamento permite operações de tabela
3. Todos os nós usam o mesmo ServiceName
4. O firewall permite acesso ao Azure Storage

---

Integração com Aspire

Para padrões específicos do Aspire, veja a skill akka-net-aspire-configuration.

Referência rápida para Aspire:

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

---

Resumo: Quando Usar o Quê

Cenário	Método de Descoberta	FilterOnFallbackPort
Desenvolvimento local (nó único)	Nenhum (usar nós seed)	N/A
Aspire multi-nó	AzureTableStorage	false
Kubernetes	Kubernetes	true
VMs/VMSS Azure	AzureTableStorage	true
Infraestrutura fixa	Config	true
AWS ECS/EC2	Plugins de descoberta AWS	true