k8sOperator

A modern Kubernetes Operator framework for .NET that makes it easy to build custom controllers and operators.

Features

• 🎯 Simple API - Fluent builder pattern for Kubernetes resources
• 🔄 Reconciliation - Built-in controller pattern with informers and caching
• 📦 Custom Resources - Full CRD support with type-safe definitions
• 🗳️ Leader Election - High availability out of the box
• 🚀 AOT Ready - Optimized for trimmed, single-file deployments
• 🛠️ CLI Included - Built-in commands for install, create, and version
• 📊 Source Generators - Automatic builder extensions for your resources

Installation

dotnet add package k8sOperator

Quick Start

1. Define Your Custom Resource

[KubernetesEntity(Group=KubeGroup,ApiVersion=KubeApiVersion,Kind=KubeKind,PluralName=KubePluralName)]publicclassV1MyApp:IKubernetesObject<V1ObjectMeta>,ISpec<V1MyAppSpec>,IStatus<V1MyAppStatus>{publicconststringKubeApiVersion="v1";publicconststringKubeKind="MyApp";publicconststringKubeGroup="modern-engineering.io";publicconststringKubePluralName="myapps";publicstringApiVersion{get;set;}=$"{KubeGroup}/{KubeApiVersion}";publicstringKind{get;set;}=KubeKind;publicV1ObjectMetaMetadata{get;set;}=newV1ObjectMeta();publicV1MyAppSpecSpec{get;set;}=newV1MyAppSpec();publicV1MyAppStatusStatus{get;set;}=newV1MyAppStatus();}publicclassV1MyAppSpec{publicintReplicas{get;set;}publicstring?Image{get;set;}}publicclassV1MyAppStatus{publicstring?Phase{get;set;}publicintReadyReplicas{get;set;}}

2. Create a Reconciler

publicclassMyAppReconciler{publicasyncTask<IReconcileResult>ReconcileAsync(ReconcileContextcontext){varapp=context.GetResource<V1MyApp>();varinformer=context.GetInformer<V1MyApp>();// Your reconciliation logic here// You can access other resources from the cachevarallApps=informer.List().Count();returnReconcileResult.Success<V1MyApp>(x =>{x.WithLabel("managed-by","simple-operator");x.WithLabel("processed","true");x.WithStatus(x =>{x.Phase="Reconciling";x.ReadyReplicas=resource.Spec?.Replicas??0;});});}}

3. Create a JsonSerializerContext

JsonSerializerContext is needed because it gives the .NET source generator a compile-time map of which types should be serialized and deserialized. That helps the framework avoid reflection-heavy runtime work and makes JSON handling more efficient, especially in trimmed or AOT-friendly applications.

[JsonSerializable(typeof(V1MyApp))][JsonSerializable(typeof(V1MyAppSpec))][JsonSerializable(typeof(V1MyAppStatus))][JsonSourceGenerationOptions(PropertyNamingPolicy=JsonKnownNamingPolicy.CamelCase,WriteIndented=false,DefaultIgnoreCondition=JsonIgnoreCondition.WhenWritingNull,GenerationMode=JsonSourceGenerationMode.Default)]publicpartialclassAppJsonSerializerContext:JsonSerializerContext{}

4. Register and Run

varbuilder=WebApplication.CreateBuilder(args);builder.Services.AddOperator(x =>{x.Name="simple-operator";x.Namespace="default";x.JsonSerializerContext=AppJsonSerializerContext.Default;x.Install.Resources.Add(typeof(V1MyApp));});varapp=builder.Build();app.AddReconciler<V1MyApp>(V1MyAppReconciler.ReconcileAsync);awaitapp.RunOperatorAsync();

Building Resources

Use the fluent builder API:

vardeployment=ObjectBuilder.Create<V1Deployment>().WithName("my-app").WithNamespace("default").WithLabel("app","my-app").WithSpec(spec =>spec.WithReplicas(3).WithTemplate(template =>template.WithSpec(podSpec =>podSpec.WithContainer(c =>c.WithImage("nginx:latest").WithPort(80))))).Build();

CLI Commands

# Show version
myoperator version
# Install CRDs
myoperator install
# Create resource
myoperator create myapp --name demo
# Show help
myoperator help

Configuration

Configure via appsettings.json or attributes:

{
"Operator": {
"Name": "my-operator",
"Namespace": "default",
}
}

Links

• GitHub
• Examples
• Documentation

Requirements

• .NET 10.0 or later
• Kubernetes 1.25+

License

MIT License

---

Built with ❤️ by Patrick Evers