feat: pausing reconciliation of controlled objects (#874)

* feat: pausing reconciliation of controlled objects

Objects such as TenantControlPlane and Secret can be annotated with
kamaji.clastix.io/paused to prevent controllers from processing them.

This will stop reconciling objects for debugging or other purposes.
Annotation value is irrelevant, just the key presence is evaluated.

Signed-off-by: Dario Tranchitella <dario@tranchitella.eu>

* docs: pausing reconciliation of controlled objects

Signed-off-by: Dario Tranchitella <dario@tranchitella.eu>

* chore(logs): typo for deleted resources

Signed-off-by: Dario Tranchitella <dario@tranchitella.eu>

---------

Signed-off-by: Dario Tranchitella <dario@tranchitella.eu>

docs/content/guides/pausing.md

@@ -0,0 +1,33 @@
+# Pausing Reconciliations
+
+Kamaji follows the Kubernetes Operator pattern, which includes implementing a reconciliation loop.
+This loop continuously reacts to events such as creation, updates, and deletions of resources.
+
+To temporarily disable reconciliation for a resource, you can use the following annotation:
+> `kamaji.clastix.io/paused`
+
+!!! info "Annotation value"
+    The annotation key is sufficient on its own: no value is required.
+    Its mere presence disables controller reconciliations.
+
+## Pausing `TenantControlPlane` reconciliations
+
+When you add the `kamaji.clastix.io/paused` annotation to a TenantControlPlane object,
+Kamaji will halt all reconciliation processes for that object.
+
+This affects **all controllers**, including:
+
+- The primary controller responsible for provisioning resources in the management cluster
+- Secondary (soot) controllers responsible for bootstrapping the control plane, deploying addons, and managing any additional resources handled by Kamaji.
+
+## Pausing Secret rotation
+
+Kamaji automatically generates and manages several `Secret` resources, such as:
+
+- `x509` certificates
+- `kubeconfig` credentials
+
+These secrets are automatically rotated by Kamaji's built-in **Certificate Lifecycle** feature.
+
+To temporarily disable secret rotation for these resources,
+apply the `kamaji.clastix.io/paused` annotation to the corresponding object.

docs/content/llms.txt

@@ -94,7 +94,7 @@ Clastix Labs no longer provides release artifacts following its own semantic ver
 - [Releases and Versions](https://github.com/clastix/kamaji/blob/master/docs/content/reference/versioning.md): Kamaji versions are available in different types of release artifacts
 - [API Reference](https://github.com/clastix/kamaji/blob/master/docs/content/reference/api.md): Kamaji Custom Resources full API documentation
 
-## GitHub
+## GitHubK
 
 - [Readme](https://github.com/clastix/kamaji/blob/master/README.md): GitHub Readme file
 - [License](https://github.com/clastix/kamaji/blob/master/LICENSE): Apache 2.0 license

docs/mkdocs.yml

@@ -73,6 +73,7 @@ nav:
   - guides/alternative-datastore.md
   - guides/backup-and-restore.md
   - guides/certs-lifecycle.md
+  - guides/pausing.md
   - guides/datastore-migration.md
   - guides/gitops.md
   - guides/console.md