Table of Contents

Getting Started

1. Install the core package and a runtime provider

# Core + Docker (most common)
dotnet add package Bielu.Microservices.Orchestrator
dotnet add package Bielu.Microservices.Orchestrator.Docker

# — or Podman —
dotnet add package Bielu.Microservices.Orchestrator.Podman

# — or Kubernetes —
dotnet add package Bielu.Microservices.Orchestrator.Kubernetes

# — or containerd —
dotnet add package Bielu.Microservices.Orchestrator.Containerd

All packages target .NET 10 and share a single version.

2. Register the orchestrator in DI

using Bielu.Microservices.Orchestrator.Extensions;
using Bielu.Microservices.Orchestrator.Docker.Extensions;

builder.Services.AddMicroservicesOrchestrator(orchestrator =>
{
    orchestrator.AddDocker(); // uses the default Docker socket
});

Each provider exposes an options delegate for custom configuration:

orchestrator.AddDocker(options =>
{
    // Linux / macOS default: unix:///var/run/docker.sock
    // Windows default:       npipe://./pipe/docker_engine
    options.Endpoint = "tcp://remote-host:2376";
});

3. Inject IContainerOrchestrator and use it

using Bielu.Microservices.Orchestrator.Abstractions;

public class MyService(IContainerOrchestrator orchestrator)
{
    public async Task RunAsync()
    {
        // Check the runtime is reachable
        var available = await orchestrator.IsAvailableAsync();

        // List running containers
        var containers = await orchestrator.Containers.ListAsync();
    }
}

IContainerOrchestrator aggregates four managers:

Member Description
Containers IContainerManager — container lifecycle
Images IImageManager — pull, tag, remove images
Networks INetworkManager — networks and attachments
Volumes IVolumeManager — volumes
ProviderName Runtime name (e.g. "Docker", "Podman")
IsAvailableAsync() Whether the runtime is reachable

Builder options

Method Description
WithManagedContainersOnly(bool) Only list and manage containers the orchestrator created (default: true). Pass false to see every container on the host.
WithDefaultProvider(string) Sets the default runtime provider by name (e.g. "Docker", "Containerd").
WithStateTracking() Persists desired state and reconciles it on startup — see State Tracking & Recovery.
AddOpenTelemetryInstrumentation() Tracing and metrics decorators — see Observability.

Next steps

Edit this page