From 57ca71c43c9a04da649c2df5240f0b4f12a50334 Mon Sep 17 00:00:00 2001 From: Marcus Kimpenhaus Date: Fri, 12 Jun 2026 09:01:33 +0200 Subject: [PATCH 1/3] docs: update Aspire operator docs - Adjusted Markdown syntax for note and tip blocks. --- README.md | 45 +---------------------------------- docs/docs/operator/aspire.mdx | 6 ++--- 2 files changed, 4 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 96904e51..e68ad151 100644 --- a/README.md +++ b/README.md @@ -102,49 +102,6 @@ aspire run --project src/MyApp.AppHost/MyApp.AppHost.csproj aspire publish --project src/MyApp.AppHost/MyApp.AppHost.csproj --output-path ./artifacts/k8s ``` -Common AppHost shapes: - -Local development only: - -```csharp -var dev = builder.AddKubernetesEnvironment("dev"); - -builder.AddKubeOps("operator") - .RunWithKubernetes(dev, run => run.WithPersistentCrds()); -``` - -Azure publish/deploy only: - -```csharp -var aks = builder.AddAzureKubernetesEnvironment("aks"); - -builder.AddKubeOps("operator") - .PublishAsKubernetesOperator(aks, publish => publish.WithServiceAccount("operator")); -``` - -Local run and Azure deploy: - -```csharp -var dev = builder.AddKubernetesEnvironment("dev"); -var aks = builder.AddAzureKubernetesEnvironment("aks"); - -builder.AddKubeOps("operator") - .RunWithKubernetes(dev) - .PublishAsKubernetesOperator(aks); -``` - -Publish only without an Aspire Kubernetes environment: - -```csharp -builder.AddKubeOps("operator") - .PublishAsKubernetesOperator(publish => - { - publish.Namespace = "operator-system"; - publish.WithServiceAccount("operator"); - }); -``` - -Without `RunWithKubernetes(...)`, `AddKubeOps(...)` keeps the operator in explicit-start mode for local Aspire runs. Standalone manifest publish does not require `AddKubernetesEnvironment(...)`, Helm, or a live cluster; publishing with a Kubernetes environment generates an Aspire Helm chart, while `aspire deploy` installs that chart into the selected environment. ## Packages @@ -201,4 +158,4 @@ In short: ## Motivation -KubeOps aims to provide a first-class experience for developing Kubernetes operators within the .NET ecosystem, offering an alternative to Go-based SDKs like Kubebuilder and Operator SDK, while embracing familiar C# patterns and tooling. +KubeOps aims to provide a first-class experience for developing Kubernetes operators within the .NET ecosystem, offering an alternative to Go-based SDKs like Kubebuilder and Operator SDK, while embracing familiar C# patterns and tooling. \ No newline at end of file diff --git a/docs/docs/operator/aspire.mdx b/docs/docs/operator/aspire.mdx index c1d51cce..972f85aa 100644 --- a/docs/docs/operator/aspire.mdx +++ b/docs/docs/operator/aspire.mdx @@ -54,7 +54,7 @@ await host.RunAsync(); - **HTTP resilience** — the standard resilience handler (retries, circuit breaker, timeouts) is applied to all `HttpClient` instances. - **Health checks** — a default `self` liveness check tagged `live`. -:::tip Operator name +:::tip[Operator name] The OpenTelemetry service name and the tracing source name must match `OperatorSettings.Name` — otherwise the operator's reconciliation traces are never captured. Call `AddKubeOpsServiceDefaults()` **after** `AddKubernetesOperator()` so KubeOps can resolve the configured name automatically. If you must call it earlier, pass the name explicitly (and keep it in sync with `OperatorSettings.Name`): ```csharp @@ -96,7 +96,7 @@ builder.Build().Run(); - `RunWithKubernetes(k8s)` opts the operator into local execution against a Kubernetes target. - `PublishAsKubernetesOperator(k8s)` includes the operator, CRDs, RBAC, and service account in the Aspire Kubernetes publish/deploy output. -:::note Project reference +:::note[Project reference] When referencing `KubeOps.Aspire.Hosting` from an AppHost, mark it as a normal code reference so the AppHost SDK does not treat it as a resource: ```xml @@ -233,4 +233,4 @@ builder.AddKubeOps("operator") .PublishAsKubernetesOperator(aks, publish => publish.WithServiceAccount("operator")); ``` -For the deeper run/publish model, see [Aspire Kubernetes Operator Model](./aspire-kubernetes-model). +For the deeper run/publish model, see [Aspire Kubernetes Operator Model](./aspire-kubernetes-model). \ No newline at end of file From cb23d764e01a45eb106e45b784f0ecd4b7a069a2 Mon Sep 17 00:00:00 2001 From: Marcus Kimpenhaus Date: Fri, 12 Jun 2026 10:35:38 +0200 Subject: [PATCH 2/3] chore: added further details docs link --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index e68ad151..86a648ba 100644 --- a/README.md +++ b/README.md @@ -102,6 +102,7 @@ aspire run --project src/MyApp.AppHost/MyApp.AppHost.csproj aspire publish --project src/MyApp.AppHost/MyApp.AppHost.csproj --output-path ./artifacts/k8s ``` +For further details, see the [Aspire documentation](https://dotnet.github.io/dotnet-operator-sdk/docs/operator/aspire). ## Packages From adc68eee1155749fea5e8e444d9c1271cf05a55c Mon Sep 17 00:00:00 2001 From: Marcus Kimpenhaus Date: Fri, 12 Jun 2026 10:43:11 +0200 Subject: [PATCH 3/3] chore: fixed some warnings and formatting issues --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 86a648ba..e579aa07 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# KubeOps - Kubernetes Operators in .NET +# KubeOps – Kubernetes Operators in .NET **Build Kubernetes Operators in .NET with Ease** @@ -16,7 +16,7 @@ The documentation is also provided within the code itself (description of method - **Define CRDs in C#:** Model your [Custom Resource Definitions (CRDs)](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/) using plain C# classes and attributes. - **Controller Logic:** Implement reconciliation logic using the `IEntityController` interface. -- **Finalizers:** Easily add cleanup logic before resource deletion with `IEntityFinalizer`. +- **Finalizers:** Add cleanup logic before resource deletion with `IEntityFinalizer`. - **Webhooks:** Create [Admission](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/) (validating/mutating) and [Conversion](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#webhook-conversion) webhooks integrated with ASP.NET Core. - **Code Generation:** Includes Roslyn source generators and a CLI tool (`kubeops`) to automate boilerplate code for CRDs, controllers, and RBAC rules. - **Enhanced Kubernetes Client:** Provides convenience methods built on top of the official client library. @@ -111,10 +111,10 @@ The runtime libraries target [.NET 8.0](https://learn.microsoft.com/en-us/dotnet The SDK is designed to be modular. You can include only the packages you need: | Package | Description | -| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|----------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [KubeOps.Abstractions](./src/KubeOps.Abstractions/README.md) | Defines core interfaces, attributes (like `[KubernetesEntity]`), and base classes used across the SDK. Essential for defining your custom resources and controllers. | -| [KubeOps.Aspire](./src/KubeOps.Aspire/README.md) | [.NET Aspire](https://learn.microsoft.com/dotnet/aspire/) service defaults for an operator: a single `AddKubeOpsServiceDefaults()` call wiring up OpenTelemetry, service discovery, HTTP resilience, and health checks. | -| [KubeOps.Aspire.Hosting](./src/KubeOps.Aspire.Hosting/README.md) | [.NET Aspire](https://learn.microsoft.com/dotnet/aspire/) hosting integration. Adds `AddKubeOps(...)` so a KubeOps operator can be orchestrated as a resource inside an Aspire AppHost. | +| [KubeOps.Aspire](./src/KubeOps.Aspire/README.md) | [.NET Aspire](https://learn.microsoft.com/dotnet/aspire/) service defaults for an operator: a single `AddKubeOpsServiceDefaults()` call wiring up OpenTelemetry, service discovery, HTTP resilience, and health checks. | +| [KubeOps.Aspire.Hosting](./src/KubeOps.Aspire.Hosting/README.md) | [.NET Aspire](https://learn.microsoft.com/dotnet/aspire/) hosting integration. Adds `AddKubeOps(...)` so a KubeOps operator can be orchestrated as a resource inside an Aspire AppHost. | | [KubeOps.Cli](./src/KubeOps.Cli/README.md) | A [.NET Tool](https://docs.microsoft.com/en-us/dotnet/core/tools/global-tools) providing commands for scaffolding projects, generating [Custom Resource Definitions (CRDs)](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/), and more. | | [KubeOps.Generator](./src/KubeOps.Generator/README.md) | Contains [Roslyn Source Generators](https://docs.microsoft.com/en-us/dotnet/csharp/roslyn-sdk/source-generators-overview) to automate boilerplate code generation for CRDs and controllers based on your definitions. | | [KubeOps.KubernetesClient](./src/KubeOps.KubernetesClient/README.md) | Provides an enhanced client for interacting with the [Kubernetes API](https://kubernetes.io/docs/reference/kubernetes-api/), built on top of the official `KubernetesClient` library. Offers convenience methods for common operator tasks. | @@ -129,7 +129,7 @@ You can find various example operators demonstrating different features in the [ ## License -This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details. This license applies to all packages in the KubeOps SDK. +This project is licensed under the Apache License 2.0 – see the [LICENSE](LICENSE) file for details. This license applies to all packages in the KubeOps SDK. ## .NET Foundation @@ -143,7 +143,7 @@ KubeOps is maintained by the repository collaborators and maintainers. We welcom If you want to contribute, feel free to open a pull request or write issues :-) Please note that this project is released with a [Contributor Code of Conduct](./CODE_OF_CONDUCT.md). -By participating in this project you agree to abide by its terms. +By participating in this project, you agree to abide by its terms. Read more about contribution (especially for setting up your local environment) in the [CONTRIBUTING file](./CONTRIBUTING.md).