Deploy .NET Orleans on Northflank

Orleans is a framework for building highly-distributed applications that can run on a variety of environments like cloud-native services, virtual machines, or Kubernetes. Orleans revolves around "Actors" — essentially lightweight, isolated units of logic, similar to microservices.

The two key concepts you'll encounter in Orleans are:

• Grains: The actors that perform tasks.
• Silos: The infrastructure hosting the grains.

Orleans powers many well-known platforms and applications, including Microsoft Azure, Xbox services, and the game Gears of War.

In this guide, we'll walk you through deploying a sample Orleans app using Northflank. While Orleans is designed for Kubernetes clustering, Northflank simplifies access to K8s capabilities — including scalability, availability, and infrastructure management — without requiring deep technical expertise.

First, we’ll tweak the app to support PostgreSQL as a backend, giving us more deployment flexibility, then we'll explore using a Northflank templates to define and deploy your entire Orleans project. You can also use Northflank to deploy Orleans into your own cloud provider accounts, including Google Cloud Platform, Amazon Web Services, and Microsoft Azure.

Prerequisites

You should sign up for an account on Northflank if you haven't already, and link a version control system provider such as GitHub, GitLab, or Bitbucket. Then, create a new Orleans project in your team.

Let’s dive in!

Orleans communicates directly between its actors, so in Kubernetes, this translates to pod-to-pod communication. To set up PostgreSQL as the clustering backend, we’ll modify the sample app.

Let’s add the necessary .Net packages:

cd KubeSiloHost
dotnet add package Orleans.Clustering.AdoNet
dotnet add package Orleans.Persistence.AdoNet
dotnet add package Npgsql

Verify these dependencies in the .csproj file:

...
<PackageReference Include="Microsoft.Orleans.Persistence.AdoNet" Version="9.0.1" />
<PackageReference Include="Microsoft.Orleans.Clustering.AdoNet" Version="9.0.1" />
<PackageReference Include="Npgsql" Version="9.0.2" />
...

Now let’s update the Program.cs file to use PostgreSQL and allow configuration via Environment Variables:

private static void ConfigureDelegate(HostBuilderContext context, ISiloBuilder builder)
    {
        var connectionString = Environment.GetEnvironmentVariable("POSTGRES_URI")
                               ?? "Host=localhost;Database=postgres;Username=user;Password=password";
        var clusterId = Environment.GetEnvironmentVariable("CLUSTER_ID") ?? "testcluster";
        var serviceId = Environment.GetEnvironmentVariable("SERVICE_ID") ?? "testservice";

        builder.Configure<ClusterOptions>(options =>
            {
                options.ClusterId = clusterId;
                options.ServiceId = serviceId;
            })
            .UseAdoNetClustering(options =>
            {
                options.Invariant = "Npgsql";
                options.ConnectionString = connectionString;
            })
            .AddAdoNetGrainStorageAsDefault(options =>
            {
                options.Invariant = "Npgsql";
                options.ConnectionString = connectionString;
            })
            .ConfigureLogging(logging => logging.AddConsole());
    }

Repeat these steps for any other Orleans services you want to deploy. You can find example configurations for Orleans services in our repository.

Creating new addon in Northflank is pretty straightforward. Just pick the latest version of PostgreSQL, adjust resources, replicas and give it a name.

For a more detailed steps, check out this guide to deploy PostgreSQL on Northflank.

To simplify credential management, create a new secret group.

Configure your PostgreSQL addon to link the connection details to the secret group select the following and give them the required aliases:

Any linked connection details will be automatically populated with the values from the addon, and automatically updated should the configuration of the addon change them.

Now we can construct the connection string required by Orleans. Add an environment variable to the secret group with the name POSTGRES_CONNECTION_STRING. Set the value as "Host=${PG_HOST};Database=${PG_DATABASE};Username=${PG_USERNAME};Password=${PG_PASSWORD}", which will use the linked connection details to populate the connection string.

We'll also add CLUSTER_ID and SERVICE_ID as environment variables to the group, both with the values test1, or whatever you prefer. These are used to identify your Orleans service and the cluster deployment.

To create the required tables, we can use a manual job.

In a directory in your Orleans repository, create a Dockerfile that executes SQL scripts from the official Orleans repository to configure your database, and add these scripts to the same directory. You can refer to the example in our repository.

Next, create a manual job on Northflank, select version control as the source and point it at your Orleans repository. Set the build context and Dockerfile location to the path containing your bootstrap scripts and Dockerfile.

There’s no need to specify environment variables separately as they are all inherited from the secret group. The job will build the bootstrap image from your repository, and you can run it on demand.

Run the job when your addon has finished deploying to initialise the database for your Orleans application.

Now the final setup of the application. Let’s start with a Silo app and create a new combined service. Select your Orleans repository, select Dockerfile as the build type, and enter the location of your Silo Dockerfile.

Repeat this process for the other components (e.g. Gateway and Client). Your services will build and deploy automatically

Once the services have deployed and are running, you can check the logs of the Client application to verify the connection to Orleans cluster.

Combined services build and run your code in a single service, a self-contained CI/CD pipeline. If you want to set up multiple environments and automate your releases, you can use build and deployment services in a pipeline.

Northflank gives you access to Kubernete's powerful scaling capabilities, so you can scale your Orleans project horizontally and vertically. You can increase the compute plan of your services to deploy with more CPU and memory, and scale the number of instances to handle increased workloads. Enable autoscaling to scale your services based on demand, maintaining availability while optimizing costs.

You can also scale the resources and replicas for your PostgreSQL addon, or add connection poolers to manage database connections.

Deploying Orleans involves multiple steps, but you can streamline the process by using a Northflank template. Templates allow you to define and deploy an entire environment in one configuration, which can then be deployed in a single click.

You can then update your template and run it again to update your entire environment, or create templates with dynamic configurations that you can use to deploy multiple environments across different regions and cloud providers.

Here’s the sample template JSON for the deployment used in this guide.

To use it:

1. Open templates in your team
2. Create a new template and upload the JSON file
3. Press run

And that’s it! You now have a fully functional deployment of Dotnet Orleans cluster running on Kubernetes with Northflank.

Northflank's BYOC (Bring Your Own Cloud) approach enables you to integrate your current cloud infrastructure from providers like AWS, Google Cloud Platform, Azure, and more, while simultaneously accessing Northflank's comprehensive suite of tools for building, deploying, monitoring, and managing your applications.

With Northflank, you can securely manage your cloud infrastructure by leveraging advanced credential management, granular access controls, and secure account linking. This approach allows you to maintain full control over your cloud resources and costs while meeting your organization's compliance and data security requirements.

Northflank provides flexible deployment options for your templates into your own cloud account through BYOC integration. You can create a BYOC cluster either manually or with as party of a template. Credentials can be securely supplied as encrypted argument overrides, which are protected at rest, dynamically injected during template execution, and accessible only to authorized team members with appropriate roles. Once configured, you can designate your custom cluster as the deployment target for your project, either within the template or directly through the Northflank application.

You can then select your own cluster as the target for your project in the template, or when creating a new project in the Northflank application.

This article demonstrated how Northflank offers a powerful platform for deploying, managing, and scaling Orleans applications. Jobs, managed addons, and templates simplify complex workflows while maintaining flexibility and efficiency.

Whether you’re a solo developer or part of a large team, Northflank empowers you to focus on delivering high-quality applications while it handles the headache of infrastructure management.

You can continue reading other guides on how to deploy different applications on Northflank or explore the benefits of Bring Your Own Cloud feature on Northflank.