docs: pause docs on repo (#1518)

* docs: add feature docs

Signed-off-by: Alex Pana <[email protected]>

* docs: also link from release notes

Signed-off-by: Alex Pana <[email protected]>

* Apply suggestions from code review

---------

Signed-off-by: Alex Pana <[email protected]>

docs/features/index.md

@@ -0,0 +1,3 @@
+# Contents
+
+* [Pause actuation of resources onto the cloud provider](./pause.md)

docs/features/pause.md

@@ -0,0 +1,42 @@
+# Pause KCC
+
+> `Feature State`: `alpha` as of version v1.114
+
+KCC can be configured to pause actuation of resouces on the cloud provider
+(GCP). K8s objects continue to be reconciled with the api server but any
+interaction with the cloud provider should be paused. This can be helpful for
+debugging purposes or to have a hot standby.
+
+## Pausing
+
+We extended the API definitions for the ConfigConnector and ConfigConnectorContext resources to
+support a new field, `spec.actuationMode`. The field's current supported values are `Reconciling`
+and `Paused` with `Reconciling` being the default for backwards compatiblity.
+As such, KCC can be "paused" both globally and on a per-namespace level if running in namespace mode
+
+### Pausing Globally
+
+To pause KCC across namespaces it is sufficient to set the ConfigConnector's `actuationMode: Paused`. This will work when KCC runs in `Cluster` and `Namespaced` mode. To eventually resume actuation just set the field back to `Reconciling`.
+
+### Pausing Per Namespace
+
+When KCC is running in `Namespaced` mode (and only then), operators can set
+`actuationMode: Paused` on the  `ConfigConnectorContext` resource. To eventually
+resume actuation for that namespace set the field back to `Reconciling`. The `actuationMode`
+value on the `ConfigConnectorContext` takes precedence over the value in `ConfigConnector`.
+
+### Reconciling Per Namespace (only)
+
+It can be handy to have KCC globally paused but reconciling on a per
+namespace level. To do this make sure KCC is running in `Namespaced` mode
+and the `actuationMode: Paused` on the `ConfigConnector` resource. Then
+reconciling can be turned on for a namespace by changing the `actuationMode`
+field for the`ConfigConnectorContext` to `Reconciling` for that namespace.
+NOTE: you can avoid any pausing in actuation by first changing the
+`ConfigConnectorContext` actuationMode.
+
+## Caveats
+
+### Eventual state transitions & Jitter
+
+When you un-pause actuation, reconciliation will not happen immediately, but will instead start happening on the normal re-reconciliation interval (with jitter). We may enhance this behavior in future 

docs/releasenotes/release-1.114.md

@@ -9,6 +9,7 @@
 * Initial support (alpha stability) for pausing actuation of resources onto Google Cloud. Operators
   can set ConfigConnector's or ConfigConnectorContext's spec.actuationMode to `Paused`, depending
   on whether to pause on the whole cluster or just a namespace.
+  See the [pause feature docs](./../features/pause.md) for more information.
 
 * Initial support (alpha stability) for defaulting state-into-spec to absent (the recommended setting),
   by setting `spec.stateIntoSpec: Absent` in the ConfigConnectorContext.