From a140bdf98b656c04dc31d6b7417684f8da61fb3e Mon Sep 17 00:00:00 2001
From: alex <8968914+acpana@users.noreply.github.com>
Date: Tue, 21 May 2024 09:59:24 -0700
Subject: [PATCH] docs: pause docs on repo (#1518)

* docs: add feature docs

Signed-off-by: Alex Pana <8968914+acpana@users.noreply.github.com>

* docs: also link from release notes

Signed-off-by: Alex Pana <8968914+acpana@users.noreply.github.com>

* Apply suggestions from code review

---------

Signed-off-by: Alex Pana <8968914+acpana@users.noreply.github.com>
---
 docs/features/index.md             |  3 +++
 docs/features/pause.md             | 42 ++++++++++++++++++++++++++++++
 docs/releasenotes/release-1.114.md |  1 +
 3 files changed, 46 insertions(+)
 create mode 100644 docs/features/index.md
 create mode 100644 docs/features/pause.md

diff --git a/docs/features/index.md b/docs/features/index.md
new file mode 100644
index 0000000000..3d540777bd
--- /dev/null
+++ b/docs/features/index.md
@@ -0,0 +1,3 @@
+# Contents
+
+* [Pause actuation of resources onto the cloud provider](./pause.md)
\ No newline at end of file
diff --git a/docs/features/pause.md b/docs/features/pause.md
new file mode 100644
index 0000000000..070e898322
--- /dev/null
+++ b/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 
\ No newline at end of file
diff --git a/docs/releasenotes/release-1.114.md b/docs/releasenotes/release-1.114.md
index 16d2969a17..f8d5cac132 100644
--- a/docs/releasenotes/release-1.114.md
+++ b/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.