Bielu.Microservices.Orchestrator.Docker 0.1.0-beta.639158264724296298

Bielu.Microservices.Orchestrator

A .NET library for managing container runtimes (Docker, Podman, containerd, and Kubernetes) through a unified abstraction layer. Write your container-management logic once and swap the underlying runtime with a single line of configuration.

Features

• Unified API — single set of interfaces (IContainerManager, IImageManager, INetworkManager, IVolumeManager) shared across all runtimes
• Docker — full Docker Engine API integration via Docker.DotNet
• Podman — Docker-compatible API, zero extra code required
• containerd — gRPC-based containerd runtime integration
• Kubernetes — pod/deployment management via the official Kubernetes client
• OpenTelemetry tracing — automatic Activity spans around every operation
• Health checks — IHealthCheck that verifies the container runtime is reachable
• Dependency injection — first-class Microsoft.Extensions.DependencyInjection support
• Aspire integration — example and test projects using .NET Aspire

Packages

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

2. Register the orchestrator in DI

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

builder.Services.AddMicroservicesOrchestrator(orchestrator =>
{
 orchestrator.AddDocker(); // uses 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();
 }
}

Container Lifecycle

The IContainerManager interface (exposed via orchestrator.Containers) provides the full create → start → stop → remove workflow.

Create a container

using Bielu.Microservices.Orchestrator.Models;

var containerId = await orchestrator.Containers.CreateAsync(new CreateContainerRequest
{
 Image = "nginx:latest",
 Name = "my-nginx",
 Ports = [new PortMapping { ContainerPort = 80, HostPort = 8080 }],
 EnvironmentVariables = new Dictionary<string, string>
 {
 ["NGINX_HOST"] = "localhost"
 },
 Labels = new Dictionary<string, string>
 {
 ["app"] = "demo"
 }
});

Create multiple instances (replicas)

Set Replicas to create multiple container instances from the same configuration. Each instance is named with a numeric suffix (e.g., my-nginx-0, my-nginx-1) and labeled with orchestrator.group for grouping.

var firstContainerId = await orchestrator.Containers.CreateAsync(new CreateContainerRequest
{
 Image = "nginx:latest",
 Name = "my-nginx",
 Replicas = 3 // creates my-nginx-0, my-nginx-1, my-nginx-2
});

Start a container

await orchestrator.Containers.StartAsync(containerId);

Stop a container

// Graceful stop (waits up to 30 s for the process to exit)
await orchestrator.Containers.StopAsync(containerId, timeout: TimeSpan.FromSeconds(30));

Get logs

var logs = await orchestrator.Containers.GetLogsAsync(containerId, stdout: true, stderr: true);

Remove a container

// Remove a stopped container
await orchestrator.Containers.RemoveAsync(containerId);

// Force-remove a running container
await orchestrator.Containers.RemoveAsync(containerId, force: true);

Inspect a container

var info = await orchestrator.Containers.GetAsync(containerId);
// info.Id, info.Name, info.Image, info.State, ...

Image Management

// Pull an image
await orchestrator.Images.PullAsync(new PullImageRequest
{
 Image = "nginx",
 Tag = "latest"
});

// List images
var images = await orchestrator.Images.ListAsync();

// Tag an image
await orchestrator.Images.TagAsync(imageId, "myregistry/nginx", "v2");

// Remove an image
await orchestrator.Images.RemoveAsync(imageId, force: true);

Network Management

// Create a bridge network
var networkId = await orchestrator.Networks.CreateAsync("my-network", driver: "bridge");

// Connect / disconnect a container
await orchestrator.Networks.ConnectAsync(networkId, containerId);
await orchestrator.Networks.DisconnectAsync(networkId, containerId);

// List and remove
var networks = await orchestrator.Networks.ListAsync();
await orchestrator.Networks.RemoveAsync(networkId);

Volume Management

// Create a volume
var volume = await orchestrator.Volumes.CreateAsync("my-volume", driver: "local");

// List and remove
var volumes = await orchestrator.Volumes.ListAsync();
await orchestrator.Volumes.RemoveAsync("my-volume", force: true);

OpenTelemetry Tracing

Install the tracing package:

dotnet add package Bielu.Microservices.Orchestrator.OpenTelemetry

Wire up tracing

AddOpenTelemetryInstrumentation() wraps every registered manager interface with a decorator that opens an Activity span per operation. Call it after registering a provider:

using Bielu.Microservices.Orchestrator.OpenTelemetry.Extensions;

builder.Services.AddMicroservicesOrchestrator(orchestrator =>
{
 orchestrator
 .AddDocker()
 .AddOpenTelemetryInstrumentation(); // must come after the provider
});

Then register the library's ActivitySource with the OpenTelemetry SDK so spans reach your exporter:

using OpenTelemetry.Trace;

builder.Services.AddOpenTelemetry()
 .WithTracing(tracing => tracing
 .AddOrchestratorInstrumentation() // orchestrator spans
 .AddAspNetCoreInstrumentation() // HTTP request spans
 .AddConsoleExporter()); // or AddOtlpExporter() for production

Every container, image, network, and volume operation will now emit a span with semantic attributes such as container.id, container.image, network.driver, and volume.name.

Health Checks

Install the health-checks package:

dotnet add package Bielu.Microservices.Orchestrator.HealthChecks

Register the health check

AddContainerRuntimeHealthCheck() adds an IHealthCheck that calls IContainerOrchestrator.IsAvailableAsync():

using Bielu.Microservices.Orchestrator.HealthChecks.Extensions;

builder.Services.AddHealthChecks()
 .AddContainerRuntimeHealthCheck(
 name: "container-runtime",
 failureStatus: HealthStatus.Unhealthy,
 tags: ["ready", "runtime"]);

Map health-check endpoints

using Microsoft.AspNetCore.Diagnostics.HealthChecks;

// Liveness — always healthy if the process is running
app.MapHealthChecks("/health");

// Readiness — healthy only when the container runtime is reachable
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
 Predicate = r => r.Tags.Contains("ready")
});

The check returns:

Switching Runtime Providers

Because every provider implements the same interfaces, switching runtimes is a one-line change. The rest of your code stays exactly the same:

builder.Services.AddMicroservicesOrchestrator(orchestrator =>
{
 // Pick one:
 orchestrator.AddDocker();
 // orchestrator.AddPodman(o => o.Endpoint = "unix:///run/podman/podman.sock");
 // orchestrator.AddKubernetes(o => o.Namespace = "my-namespace");
 // orchestrator.AddContainerd(o => o.Endpoint = "http://localhost:1234");

 orchestrator.AddOpenTelemetryInstrumentation(); // optional, works with any provider
});

Full ASP.NET Core Example

A complete working example lives in . Here is the condensed version:

using Bielu.Microservices.Orchestrator.Abstractions;
using Bielu.Microservices.Orchestrator.Docker.Extensions;
using Bielu.Microservices.Orchestrator.Extensions;
using Bielu.Microservices.Orchestrator.HealthChecks.Extensions;
using Bielu.Microservices.Orchestrator.Models;
using Bielu.Microservices.Orchestrator.OpenTelemetry.Extensions;
using Microsoft.AspNetCore.Diagnostics.HealthChecks;
using Microsoft.Extensions.Diagnostics.HealthChecks;
using OpenTelemetry.Trace;

var builder = WebApplication.CreateBuilder(args);

// 1. Register orchestrator with Docker + tracing
builder.Services.AddMicroservicesOrchestrator(o => o
 .AddDocker()
 .AddOpenTelemetryInstrumentation());

// 2. Configure OpenTelemetry exporter
builder.Services.AddOpenTelemetry()
 .WithTracing(t => t
 .AddOrchestratorInstrumentation()
 .AddAspNetCoreInstrumentation()
 .AddConsoleExporter());

// 3. Health checks
builder.Services.AddHealthChecks()
 .AddContainerRuntimeHealthCheck(
 failureStatus: HealthStatus.Unhealthy,
 tags: ["ready", "runtime"]);

var app = builder.Build();

// Health endpoints
app.MapHealthChecks("/health");
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
 Predicate = r => r.Tags.Contains("ready")
});

// Container CRUD
app.MapGet("/api/containers", async (IContainerOrchestrator o, bool all = false) =>
 Results.Ok(await o.Containers.ListAsync(all)));

app.MapPost("/api/containers", async (CreateContainerRequest req, IContainerOrchestrator o) =>
{
 var id = await o.Containers.CreateAsync(req);
 return Results.Created($"/api/containers/{id}", new { Id = id });
});

app.MapPost("/api/containers/{id}/start", async (string id, IContainerOrchestrator o) =>
{
 await o.Containers.StartAsync(id);
 return Results.Ok(new { Message = $"Container {id} started." });
});

app.MapPost("/api/containers/{id}/stop", async (string id, IContainerOrchestrator o, int? timeoutSeconds) =>
{
 var timeout = timeoutSeconds.HasValue ? TimeSpan.FromSeconds(timeoutSeconds.Value) : (TimeSpan?)null;
 await o.Containers.StopAsync(id, timeout);
 return Results.Ok(new { Message = $"Container {id} stopped." });
});

app.MapGet("/api/containers/{id}/logs", async (string id, IContainerOrchestrator o) =>
 Results.Ok(new { Logs = await o.Containers.GetLogsAsync(id) }));

app.MapDelete("/api/containers/{id}", async (string id, IContainerOrchestrator o, bool force = false) =>
{
 await o.Containers.RemoveAsync(id, force);
 return Results.NoContent();
});

// Provider info
app.MapGet("/api/provider", async (IContainerOrchestrator o) =>
 Results.Ok(new { o.ProviderName, IsAvailable = await o.IsAvailableAsync() }));

app.Run();

API Reference

IContainerOrchestrator

IContainerManager

IImageManager

INetworkManager

IVolumeManager

License

MIT — see for details.