Server configuration

Install Microsoft.Orleans.Server and add Orleans to a .NET Generic Host:

public static async Task RedisSilo(string[] args)
{
    var builder = Host.CreateApplicationBuilder(args);

    builder.UseOrleans(siloBuilder =>
    {
        siloBuilder.Configure<ClusterOptions>(options =>
        {
            options.ServiceId = "orders";
            options.ClusterId = "orders-production";
        });

        siloBuilder.UseRedisClustering(options =>
        {
            options.ConfigurationOptions =
                ConfigurationOptions.Parse(
                    builder.Configuration.GetConnectionString("redis")!);
        });
    });

    await builder.Build().RunAsync();
}

UseOrleans hosts a silo and registers a co-hosted IClusterClient. Use UseOrleansClient only in a process that doesn’t host grains.

Clustering provider

Every silo and external client must use the same ServiceId, ClusterId, and clustering backend. Install the package for the deployment platform:

Backend	Typical package or integration	Notes
Azure Table Storage	Microsoft.Orleans.Clustering.AzureStorage	Supports Microsoft Entra credentials and connection strings.
ADO.NET	Microsoft.Orleans.Clustering.AdoNet	Supports SQL Server, PostgreSQL, MySQL/MariaDB, and Oracle.
Redis	Microsoft.Orleans.Clustering.Redis	Can share a managed or self-hosted Redis service.
Azure Cosmos DB	Microsoft.Orleans.Clustering.Cosmos	Uses a Cosmos DB container for membership.
DynamoDB	Microsoft.Orleans.Clustering.DynamoDB	Common for AWS deployments.
Consul	Microsoft.Orleans.Clustering.Consul	Uses Consul key/value storage.
ZooKeeper	Microsoft.Orleans.Clustering.ZooKeeper	Uses a ZooKeeper ensemble.

Use UseLocalhostClustering, development clustering, or static gateways only for local development and tests.

Microsoft.Orleans.Hosting.Kubernetes configures a silo from its pod environment through UseKubernetesHosting; it is not a clustering provider. Kubernetes deployments still need one of the shared clustering providers above.

Clustering stores membership, not grain state. Configure grain storage and reminders separately when the application uses them. Provider packages expose Use...Clustering, Add...GrainStorage, and Use...ReminderService methods and can also participate in declarative configuration.

Orleans clustering information

ServiceId identifies the logical application and namespaces provider data. Keep it stable for the lifetime of the application. ClusterId identifies a specific cluster, such as orders-production or orders-green. All participants in one cluster must agree on both values.

Endpoints

A silo has two advertised endpoints:

• The silo endpoint is used for silo-to-silo traffic. Its default port is 11111.
• The gateway endpoint is used by external clients. Its default port is 30000; set it to 0 to disable the gateway.

Orleans must also know the IP address to advertise. If AdvertisedIPAddress isn’t configured, Orleans selects a local address and falls back to loopback if necessary. The listening endpoints default to the advertised address and corresponding advertised port; Orleans does not listen on every interface unless you configure wildcard listening endpoints.

For a directly reachable host, the helper configures advertised ports and an address:

public static void ConfigureDirectEndpoints(ISiloBuilder siloBuilder)
{
    siloBuilder.ConfigureEndpoints(
        advertisedIP: IPAddress.Parse("10.0.0.12"),
        siloPort: 11_111,
        gatewayPort: 30_000,
        listenOnAnyHostAddress: true);
}

For containers, NAT, or port forwarding, configure advertised and listening endpoints independently:

public static void ConfigureAdvertisedAndListeningEndpoints(
    ISiloBuilder siloBuilder)
{
    siloBuilder.Configure<EndpointOptions>(options =>
    {
        // Addresses that other silos and clients use.
        options.AdvertisedIPAddress = IPAddress.Parse("172.16.0.42");
        options.SiloPort = 11_111;
        options.GatewayPort = 30_000;

        // Sockets opened inside this process or container.
        options.SiloListeningEndpoint =
            new IPEndPoint(IPAddress.Any, 40_000);
        options.GatewayListeningEndpoint =
            new IPEndPoint(IPAddress.Any, 50_000);
    });
}

This silo listens on ports 40000 and 50000 but publishes 172.16.0.42:11111 and 172.16.0.42:30000. Ensure membership data never contains an address that peers can’t route to.

For private networking, host-port mappings, and cross-host container diagnostics, see Run Orleans in containers across multiple hosts.

Configure providers and options

Use named providers when grain types need different stores:

public static void ConfigureNamedProviders(ISiloBuilder siloBuilder)
{
    siloBuilder
        .AddRedisGrainStorage(
            "hot-state",
            options => options.ConfigurationOptions =
                ConfigurationOptions.Parse("localhost:6379"))
        .AddAdoNetGrainStorage("archive", options =>
        {
            options.Invariant = "Microsoft.Data.SqlClient";
            options.ConnectionString =
                "Server=localhost;Database=Orleans;Integrated Security=true";
        })
        .UseRedisReminderService(
            options => options.ConfigurationOptions =
                ConfigurationOptions.Parse("localhost:6379"));
}

Configure runtime behavior with the options pattern:

public static void ConfigureMembership(ISiloBuilder siloBuilder)
{
    siloBuilder.Configure<ClusterMembershipOptions>(options =>
    {
        options.ProbeTimeout = TimeSpan.FromSeconds(10);
    });
}

Prefer defaults until measurements or deployment requirements justify a change. See Core configuration options rather than copying every property into application configuration.

Production guidance

• Use workload identity, managed identity, or another short-lived credential mechanism where the provider supports it.
• Keep connection strings and credentials outside source control.
• Run at least three silos across failure domains when availability requirements demand quorum-like failure tolerance.
• Configure readiness so traffic starts only after host startup completes.
• Let the Generic Host receive termination signals and complete graceful shutdown.
• Choose the .NET GC mode and size CPU/memory limits from representative load tests.