diff --git a/docs/docs/operator/advanced-configuration.mdx b/docs/docs/operator/advanced-configuration.mdx index b8c3a953..8f9cae8d 100644 --- a/docs/docs/operator/advanced-configuration.mdx +++ b/docs/docs/operator/advanced-configuration.mdx @@ -323,7 +323,7 @@ reconciliation only when the incoming generation is **greater** than the cached This matches the pattern used by most Kubernetes controllers (e.g., `kube-controller-manager`) and is the correct default for the majority of operators. -:::tip When to use `ByGeneration` +:::tip[When to use `ByGeneration`] Your controller only reacts to `.spec` changes. Status writes, label updates, and annotation changes are either performed by your own controller (and should not re-trigger it), or performed by other actors and are irrelevant to your business logic. @@ -349,7 +349,7 @@ for **every successful API server write**, regardless of which field changed. - Your controller must be **idempotent** for status-only changes, since it will be called when another actor updates `.status` on the same resource. -:::warning Infinite reconcile loop risk +:::warning[Infinite reconcile loop risk] Because **every write to the resource increments `resourceVersion`**, a reconciler that writes back to the resource — for example to update `.status` — will trigger a new watch event, which triggers another reconcile, which writes again, and so on. @@ -375,14 +375,14 @@ Without this guard, `ByResourceVersion` will produce an infinite reconcile loop controller that writes to the resource during reconciliation. ::: -:::tip When to use `ByResourceVersion` +:::tip[When to use `ByResourceVersion`] Your controller needs to react to changes outside `.spec`. Common examples: - A controller that mirrors label or annotation values into child resources. - A controller that acts on status conditions written by another controller. - A controller that must respond to ownership or finalizer changes made by external actors. ::: -:::caution Performance consideration +:::caution[Performance consideration] `ByResourceVersion` can significantly increase the number of reconciliation calls, especially for resources whose `.status` is updated frequently. Size `MaxParallelReconciliations` and the error backoff settings accordingly and ensure your controller logic is fast for status-only no-op cases. diff --git a/docs/docs/operator/build-customization.mdx b/docs/docs/operator/build-customization.mdx index 3122b28e..1b12ac4f 100644 --- a/docs/docs/operator/build-customization.mdx +++ b/docs/docs/operator/build-customization.mdx @@ -157,7 +157,7 @@ dotnet tool install --local KubeOps.Cli dotnet tool install --global KubeOps.Cli ``` -:::note Local vs global tools +:::note[Local vs global tools] Local tools are not added to your `PATH`. When KubeOps runs as part of the build, it can invoke a locally installed CLI via `dotnet tool run kubeops`. ::: diff --git a/docs/docs/operator/building-blocks/controllers.mdx b/docs/docs/operator/building-blocks/controllers.mdx index 4532b706..8e8d41c0 100644 --- a/docs/docs/operator/building-blocks/controllers.mdx +++ b/docs/docs/operator/building-blocks/controllers.mdx @@ -98,7 +98,7 @@ public async Task> ReconcileAsync( ### DeletedAsync -:::warning Important +:::warning[Important] The `DeletedAsync` method is informational only and executes asynchronously without guarantees. While it is called when a resource is deleted, it cannot ensure proper cleanup. For reliable resource cleanup, use [finalizers](./finalizer). ::: @@ -204,7 +204,7 @@ public class V1DemoEntityController( } ``` -:::info Durable Queue +:::info[Durable Queue] By default, queue entries are held in memory and lost on operator restart. To back the queue with an external system, see [Advanced Configuration — Queue Strategy](../advanced-configuration#queue-strategy). ::: diff --git a/docs/docs/operator/building-blocks/finalizer.mdx b/docs/docs/operator/building-blocks/finalizer.mdx index d59052b9..753fb076 100644 --- a/docs/docs/operator/building-blocks/finalizer.mdx +++ b/docs/docs/operator/building-blocks/finalizer.mdx @@ -229,7 +229,7 @@ To fix stuck resources: kubectl patch -p '{"metadata":{"finalizers":[]}}' --type=merge ``` -:::warning Manual Finalizer Removal +:::warning[Manual Finalizer Removal] Only remove finalizers manually as a last resort. This can lead to orphaned resources and inconsistent cluster state. ::: @@ -262,4 +262,4 @@ Don't use finalizers for: - Simple logging or monitoring - Non-critical cleanup tasks -- Operations that can be handled by the `DeletedAsync` method in controllers +- Operations that can be handled by the `DeletedAsync` method in controllers \ No newline at end of file diff --git a/docs/docs/operator/building-blocks/webhooks.mdx b/docs/docs/operator/building-blocks/webhooks.mdx index 26b01694..161f639d 100644 --- a/docs/docs/operator/building-blocks/webhooks.mdx +++ b/docs/docs/operator/building-blocks/webhooks.mdx @@ -12,7 +12,7 @@ Webhooks in Kubernetes allow you to intercept and modify requests to the API ser - Mutation Webhooks: Modify resources before they are stored - Conversion Webhooks: Convert between different versions of your custom resources -:::warning Web Version Required +:::warning[Web Version Required] Webhooks require the web version of KubeOps (`KubeOps.Operator.Web`) as they need to expose HTTP endpoints. This introduces additional dependencies on ASP.NET Core. ::: @@ -64,7 +64,7 @@ For local development, your operator must be accessible from the Kubernetes clus - Telepresence - Custom reverse proxy solutions -:::danger LocalTunnel Deprecated +:::danger[LocalTunnel `Deprecated`] The LocalTunnel option is deprecated due to stability issues. It's recommended to use the certificate provider or other more reliable solutions. ::: @@ -172,7 +172,7 @@ public class DemoMutationWebhook : MutationWebhook ## Conversion Webhooks -:::warning Preview Feature +:::warning[Preview Feature] Conversion webhooks are currently in preview. The API is not stable and may change in future versions. ::: diff --git a/docs/docs/operator/cli.mdx b/docs/docs/operator/cli.mdx index 70764336..a0c44d36 100644 --- a/docs/docs/operator/cli.mdx +++ b/docs/docs/operator/cli.mdx @@ -23,7 +23,7 @@ dotnet new tool-manifest dotnet tool install --local KubeOps.Cli ``` -:::note Command syntax +:::note[Command syntax] Examples below use the global `kubeops` command. If you installed the tool locally, replace `kubeops ...` with `dotnet tool run kubeops ...`. ::: @@ -45,7 +45,7 @@ This command: - Generates the necessary CRDs - Installs them into your current Kubernetes context -:::warning Production Usage +:::warning[Production Usage] The `install` and `uninstall` commands are primarily intended for development purposes. In production, you should use the generated Kubernetes manifests and your preferred deployment method (e.g., Helm, Kustomize, or GitOps). ::: @@ -80,7 +80,7 @@ This generates: - Namespace configuration - Kustomization files -:::note Build Integration +:::note[Build Integration] The resource generation is automatically included in the build process. You don't need to run the generate command manually unless you want to customize the output location or format. See [Build Customization](./build-customization) for details on configuring the build process. ::: diff --git a/docs/docs/operator/getting-started.mdx b/docs/docs/operator/getting-started.mdx index 4ff62738..3b6572f8 100644 --- a/docs/docs/operator/getting-started.mdx +++ b/docs/docs/operator/getting-started.mdx @@ -15,7 +15,7 @@ Before you begin, ensure you have the following installed: - [kubectl](https://kubernetes.io/docs/tasks/tools/) - A local Kubernetes cluster (like [kind](https://kind.sigs.k8s.io/) or [minikube](https://minikube.sigs.k8s.io/)) -:::warning Development Environment +:::warning[Development Environment] For local development, we recommend using `kind` or Docker Desktop, which provide lightweight Kubernetes clusters ideal for operator development. Ensure your cluster is running before proceeding with the installation steps. ::: @@ -70,7 +70,7 @@ dotnet tool install --local KubeOps.Cli The CLI provides several useful commands: -:::note Command syntax +:::note[Command syntax] Examples below use the global `kubeops` command. If you installed the tool locally, replace `kubeops ...` with `dotnet tool run kubeops ...`. ::: @@ -82,7 +82,7 @@ Generate all necessary Kubernetes resources for your operator: kubeops generate operator MyOperator ./MyFirstOperator.csproj ``` -:::note Automatic Generation +:::note[Automatic Generation] The resource generation is automatically included in the build process. You don't need to run the generate command manually unless you want to customize the output location or format. ::: @@ -95,7 +95,7 @@ This command generates: - Namespace configuration - Kustomization files -:::warning Webhook Support +:::warning[Webhook Support] If your operator includes webhooks, additional resources are generated: - CA and Server certificates @@ -189,7 +189,7 @@ public class DemoFinalizer : IEntityFinalizer } ``` -:::info Next Steps +:::info[Next Steps] The following sections will dive deeper into: - [CLI Usage](./cli) - Detailed CLI commands and options @@ -202,6 +202,6 @@ The following sections will dive deeper into: Make sure to read these sections before deploying your operator to production. ::: -:::tip Learning Path +:::tip[Learning Path] Take your time to understand each concept. Building operators is a complex task, but KubeOps makes it more approachable for .NET developers. -::: +::: \ No newline at end of file diff --git a/docs/docs/operator/rbac.mdx b/docs/docs/operator/rbac.mdx index 922c2c5f..141eaec1 100644 --- a/docs/docs/operator/rbac.mdx +++ b/docs/docs/operator/rbac.mdx @@ -21,7 +21,7 @@ Kubernetes RBAC works through four main resources: When you generate installation files for your operator, KubeOps automatically creates the necessary RBAC configurations for the operator's service account. These configurations define what resources and operations your operator is allowed to perform. -:::note Local Development +:::note[Local Development] During local development, you typically use an admin account that has full cluster access. Therefore, RBAC restrictions don't apply, and you don't need to worry about permissions. However, it's still good practice to define the required RBAC rules for production use. ::: @@ -140,4 +140,4 @@ KubeOps automatically adds default RBAC rules for: 3. **Incorrect Resource Definitions**: - Wrong API groups - Incorrect resource names - - Missing subresources + - Missing subresources \ No newline at end of file diff --git a/docs/docs/operator/utilities.mdx b/docs/docs/operator/utilities.mdx index 3e05b3d0..f133af90 100644 --- a/docs/docs/operator/utilities.mdx +++ b/docs/docs/operator/utilities.mdx @@ -48,7 +48,7 @@ This helper ensures your custom entities are always serialized and deserialized ## CRD Installer Utility -:::warning Destructive Utility +:::warning[Destructive Utility] The CRD Installer is a powerful utility intended **only for development environments**. Depending on its settings, it can overwrite or delete existing CRDs, which may lead to data loss or cluster instability. **Never use this in production!** ::: @@ -72,4 +72,4 @@ builder.Services ``` - `OverwriteExisting`: If `true`, existing CRDs with the same name will be **overwritten**. This is useful for development but can be destructive if used in production, as it may cause data loss. -- `DeleteOnShutdown`: If `true`, all CRDs installed by the operator will be **deleted** when the operator shuts down. This is extremely destructive and should only be used in disposable development environments. +- `DeleteOnShutdown`: If `true`, all CRDs installed by the operator will be **deleted** when the operator shuts down. This is extremely destructive and should only be used in disposable development environments. \ No newline at end of file