K8sOperator.NET is a powerful and intuitive library designed for creating Kubernetes Operators using C#. It simplifies the development of robust, cloud-native operators by leveraging the full capabilities of the .NET ecosystem, making it easier than ever to manage complex Kubernetes workloads with custom automation.
- 🚀 Easy Integration - Simple, intuitive API for building Kubernetes operators
- 🎯 Custom Resource Support - Built-in support for Custom Resource Definitions (CRDs)
- 🔄 Automatic Reconciliation - Event-driven reconciliation with finalizer support
- 📦 MSBuild Integration - Automatic generation of manifests, Docker files, and launch settings
- 🐳 Docker Ready - Generate optimized Dockerfiles with best practices
- 🛠️ Built-in Commands - Help, version, install, and code generation commands
- 🔐 Security First - Non-root containers, RBAC support, and security best practices
- 📝 Source Generators - Compile-time generation of boilerplate code
- 🎨 Flexible Configuration - MSBuild properties for operator customization
- 🧪 Testable - Built with testing in mind
To install K8sOperator.NET, add the package to your .NET project:
dotnet add package K8sOperator.NETOr add it manually to your .csproj file:
<PackageReferenceInclude="K8sOperator.NET"Version="*" />Create a new ASP.NET Core Web Application and add K8sOperator.NET:
dotnet new web -n MyOperator
cd MyOperator
dotnet add package K8sOperator.NETUpdate your Program.cs:
usingK8sOperator.NET;varbuilder=WebApplication.CreateBuilder(args);builder.Services.AddOperator();varapp=builder.Build();// Map your controllers here// app.MapController<MyController>();awaitapp.RunOperatorAsync();Define your custom resource by inheriting from CustomResource:
usingK8sOperator.NET;[KubernetesEntity(Group="example.com",ApiVersion="v1",Kind="MyResource",PluralName="myresources")]publicclassMyResource:CustomResource<MyResource.MySpec,MyResource.MyStatus>{publicclassMySpec{publicstringName{get;set;}=string.Empty;publicintReplicas{get;set;}=1;}publicclassMyStatus{publicstringPhase{get;set;}="Pending";publicDateTime?LastUpdated{get;set;}}}Create a controller to handle your custom resource:
usingK8sOperator.NET;usingMicrosoft.Extensions.Logging;publicclassMyController:OperatorController<MyResource>{privatereadonlyILogger<MyController>_logger;publicMyController(ILogger<MyController>logger){_logger=logger;}publicoverrideasyncTaskAddOrModifyAsync(MyResourceresource,CancellationTokencancellationToken){_logger.LogInformation("Reconciling {Name} with {Replicas} replicas",resource.Spec.Name,resource.Spec.Replicas);// Your reconciliation logic hereresource.Status=newMyResource.MyStatus{Phase="Running",LastUpdated=DateTime.UtcNow};awaitTask.CompletedTask;}publicoverrideasyncTaskDeleteAsync(MyResourceresource,CancellationTokencancellationToken){_logger.LogInformation("Deleting {Name}",resource.Metadata.Name);// Cleanup logic hereawaitTask.CompletedTask;}publicoverrideasyncTaskFinalizeAsync(MyResourceresource,CancellationTokencancellationToken){_logger.LogInformation("Finalizing {Name}",resource.Metadata.Name);// Finalization logic hereawaitTask.CompletedTask;}}Wire everything together in Program.cs:
usingK8sOperator.NET;usingMyOperator;varbuilder=WebApplication.CreateBuilder(args);// Add operator servicesbuilder.Services.AddOperator();varapp=builder.Build();// Map the controller to watch MyResourceapp.MapController<MyController>();// Run the operatorawaitapp.RunOperatorAsync();K8sOperator.NET includes several built-in commands:
| Command | Description | Availability |
|---|---|---|
operator | Run the operator (watches for resources) | All builds |
install | Generate Kubernetes installation manifests | All builds |
version | Display version information | All builds |
help | Show available commands | All builds |
generate-launchsettings | Generate Visual Studio launch profiles | Debug only |
generate-dockerfile | Generate optimized Dockerfile | Debug only |
Note: The generate-* commands are development tools and are only available in Debug builds. They are automatically excluded from Release builds to keep your production operator lean.
# Run the operator
dotnet run -- operator
# Generate installation manifests
dotnet run -- install > install.yaml
# Show version
dotnet run -- version
# Generate launch settings (Debug only)
dotnet run -c Debug -- generate-launchsettings
# Generate Dockerfile (Debug only)
dotnet run -c Debug -- generate-dockerfileK8sOperator.NET uses MSBuild properties to configure your operator. Add these to your .csproj file:
<PropertyGroup>
<!-- Operator Configuration -->
<OperatorName>my-operator</OperatorName>
<OperatorNamespace>my-namespace</OperatorNamespace>
<!-- Container Configuration -->
<ContainerRegistry>ghcr.io</ContainerRegistry>
<ContainerRepository>myorg/my-operator</ContainerRepository>
<ContainerImageTag>1.0.0</ContainerImageTag>
<ContainerFamily>alpine</ContainerFamily>
<!-- Auto-generation (opt-in) -->
<CreateOperatorLaunchSettings>true</CreateOperatorLaunchSettings>
<GenerateOperatorDockerfile>true</GenerateOperatorDockerfile>
</PropertyGroup>| Property | Default | Description |
|---|---|---|
OperatorName | {project-name} | Name of the operator |
OperatorNamespace | {project-name}-system | Kubernetes namespace |
ContainerRegistry | ghcr.io | Container registry URL |
ContainerRepository | {Company}/{OperatorName} | Repository path |
ContainerImageTag | {Version} | Image tag |
ContainerFamily | (empty) | Image variant (e.g., alpine, distroless) |
CreateOperatorLaunchSettings | false | Auto-generate launch profiles |
GenerateOperatorDockerfile | false | Auto-generate Dockerfile |
When enabled, K8sOperator.NET automatically generates:
Metadata is embedded in your assembly:
[assembly:OperatorNameAttribute("my-operator")][assembly:NamespaceAttribute("my-namespace")][assembly:DockerImageAttribute("ghcr.io","myorg/my-operator","1.0.0-alpine")]Visual Studio launch profiles for all registered commands:
{
"profiles": {
"Operator": {
"commandName": "Project",
"commandLineArgs": "operator",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
},
"Install": {
"commandName": "Project",
"commandLineArgs": "install > ./install.yaml"
}
}
}Optimized multi-stage Dockerfile with security best practices:
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY ["MyOperator.csproj", "./"]
RUN dotnet restore
COPY . .
RUN dotnet publish -c Release -o /app/publish
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS final
WORKDIR /app
RUN groupadd -r operator && useradd -r -g operator operator
COPY --from=build /app/publish .
RUN chown -R operator:operator /app
USER operator
ENTRYPOINT ["dotnet", "MyOperator.dll"]
CMD ["operator"]Optimized Docker ignore file to reduce image size.
K8sOperator.NET generates production-ready Dockerfiles with:
- ✅ Multi-stage builds for smaller images
- ✅ Non-root user for security
- ✅ Health checks
- ✅ .NET 10 runtime
- ✅ Optimized layer caching
Generate a Dockerfile:
dotnet run -- generate-dockerfileBuild the image:
docker build -t ghcr.io/myorg/my-operator:1.0.0 .Push to registry:
docker push ghcr.io/myorg/my-operator:1.0.0Generate installation manifests:
dotnet run -- install > install.yamlThe generated manifest includes:
- Custom Resource Definitions (CRDs)
- ServiceAccount
- ClusterRole and ClusterRoleBinding
- Deployment
Apply to your cluster:
kubectl apply -f install.yaml# Check if operator is running
kubectl get pods -n my-namespace
# View operator logs
kubectl logs -n my-namespace deployment/my-operator -f
# Check CRDs
kubectl get crds
# Create a custom resource
kubectl apply -f my-resource.yamlContributions are welcome! Please feel free to submit a pull request or open an issue if you encounter any bugs or have feature requests.
Clone the repository
git clone https://github.com/pmdevers/K8sOperator.NET.git cd K8sOperator.NETBuild the solution
dotnet build
Run tests
dotnet testRun the example operator
cd examples/SimpleOperator dotnet run -- operator
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Please ensure:
- ✅ All tests pass
- ✅ Code follows existing style conventions
- ✅ New features include tests
- ✅ Documentation is updated
This project is licensed under the MIT License - see the LICENSE file for details.
Built with ❤️ using .NET 10
For more examples and documentation, visit the GitHub repository.