From 86391397c071ff7efe86f62d6f453045ae9d131c Mon Sep 17 00:00:00 2001
From: Crossplane <info@crossplane.io>
Date: Tue, 11 Oct 2022 11:29:57 +0000
Subject: [PATCH] docs snapshot for crossplane version `master`

---
 .../docs/master/concepts/managed-resources.md | 20 ++++++++++
 content/docs/master/reference/composition.md  | 39 +++++++++++++++++++
 2 files changed, 59 insertions(+)

diff --git a/content/docs/master/concepts/managed-resources.md b/content/docs/master/concepts/managed-resources.md
index 19b94caf..2ffb3124 100644
--- a/content/docs/master/concepts/managed-resources.md
+++ b/content/docs/master/concepts/managed-resources.md
@@ -310,6 +310,25 @@ never deletes the external resource in the provider.
 > means Crossplane will allow immutable fields to be changed, but will not
 > actually make the desired change. This is tracked in [this issue][issue-727].
 
+#### Pausing Reconciliations
+If a managed resource being reconciled by the [managed reconciler], has the
+`crossplane.io/paused` annotation with its value set to `true` as in the
+following example, then further reconciliations are paused on that resource
+after emitting an event with the type `Synced`, the status `False`,
+and the reason `ReconcilePaused`:
+```yaml
+apiVersion: ec2.aws.upbound.io/v1beta1
+kind: VPC
+metadata:
+  name: paused-vpc
+  annotations:
+    crossplane.io/paused: "true"
+...
+```
+Reconciliations on the managed resource will resume once the 
+`crossplane.io/paused` annotation is removed or its value is set
+to anything other than `true`.
+
 ### External Name
 
 By default the name of the managed resource is used as the name of the external
@@ -462,3 +481,4 @@ including Velero.
 [issue-727]: https://github.com/crossplane/crossplane/issues/727
 [issue-1143]: https://github.com/crossplane/crossplane/issues/1143
 [managed-api-patterns]: https://github.com/crossplane/crossplane/blob/master/design/one-pager-managed-resource-api-design.md
+[managed reconciler]: https://github.com/crossplane/crossplane-runtime/blob/84e629b9589852df1322ff1eae4c6e7639cf6e99/pkg/reconciler/managed/reconciler.go#L637
\ No newline at end of file
diff --git a/content/docs/master/reference/composition.md b/content/docs/master/reference/composition.md
index 7359af9d..d03dfe86 100644
--- a/content/docs/master/reference/composition.md
+++ b/content/docs/master/reference/composition.md
@@ -373,6 +373,45 @@ spec:
       fromFieldPath: metadata.labels[some-important-label]
 ```
 
+### Pause Annotation
+There is an annotation named `crossplane.io/paused` that you can use on
+Composite Resources and Composite Resource Claims to temporarily pause
+reconciliations of their respective controllers on them. An example
+for a Composite Resource Claim is as follows:
+```yaml
+apiVersion: test.com/v1alpha1
+kind: MyResource
+metadata:
+  annotations:
+     crossplane.io/paused: true
+  namespace: upbound-system
+  name: my-resource
+spec:
+  parameters:
+    tagValue: demo-test
+  compositionRef:
+    name: example
+```
+where `MyResource` is a Composite Resource Claim kind.
+When a Composite Resource or a Claim has the `crossplane.io/paused` annotation
+with its value set to `true`, the Composite Resource controller or the Claim
+controller pauses reconciliations on the resource until
+the annotation is removed or its value set to something other than `true`.
+Before temporarily pausing reconciliations, an event with the type `Synced`,
+the status `False`, and the reason `ReconcilePaused` is emitted
+on the resource.
+Please also note that annotations on a Composite Resource Claim are propagated
+to the associated Composite Resource but when the
+`crossplane.io/paused: true` annotation is added to a Claim, because
+reconciliations on the Claim are now paused, this newly added annotation
+will not be propagated. However, whenever the annotation's value is set to a
+non-`true` value, reconciliations on the Claim will now resume, and thus the
+annotation will now be propagated to the associated Composite Resource
+with a non-`true` value. An implication of the described behavior is that
+pausing reconciliations on the Claim will not inherently pause reconciliations
+on the associated Composite Resource.
+
+
 ### Patch Types
 
 You can use the following types of patch in a `Composition`: