docs: Describe how reconcile status is computed for Config Connector resources (#2739)

Author: mortent

scripts/generate_site_sidebar/sidebar_template.md.tmpl

@@ -30,6 +30,7 @@
     - [FunctionResultList](reference/schema/function-result-list/)
     - [ResourceList](reference/schema/resource-list/)
     - [CRD Status Convention](reference/schema/crd-status-convention/)
+    - [Config Connector Status Convention](reference/schema/config-connector-status-convention/)
 - [Functions Catalog](https://catalog.kpt.dev/ ":target=_self")
   - [Curated](https://catalog.kpt.dev/ ":target=_self")
   - [Contrib](https://catalog.kpt.dev/contrib/ ":target=_self")

site/book/06-deploying-packages/00.md

@@ -56,14 +56,15 @@ number of pods have been created and become available.
 For core kubernetes types, reconcile status is computed using hardcoded rules.
 For CRDs, the status computation is based on recommended [convention for status
 fields] that needs to be followed by custom resource publishers. If CRDs follow
-these conventions, `live apply` will be able to correctly compute status.
+these conventions, `live apply` will be able to correctly compute status. `kpt` also
+has special rules for computing status for [Config Connector resources].
 
-Once you know the reconcile status of a single resource, then you really want to
-answer the following question:
-
-- Did all the resources in the local package reconcile successfully?
-
-This is referred to as _aggregated status_.
+Usually multiple resources are being applied together, and we want to know
+when all of those resources have been successfully reconciled. `live apply` computes
+the aggregate status and will wait until either they are all reconciled, the timeout
+expires, or all the remaining unreconciled resources have reached a state where they
+are unlikely to successfully reconcile. An example of the latter for `Deployment`
+resources is when the progress deadline is exceeded.
 
 ## Dependency ordering
 
@@ -76,3 +77,4 @@ any resources that depend on it are applied.
 
 
 [convention for status fields]: /reference/schema/crd-status-convention/
+[Config Connector resources]: /reference/schema/config-connector-status-convention/

site/reference/schema/config-connector-status-convention/README.md

@@ -0,0 +1,36 @@
+# Config Connector Status Convention
+
+`kpt` includes custom rules for [Config Connector] resources to make them easier to work
+with. This document describes how kpt uses fields and conditions on Config Connector
+resources to compute [reconcile status].
+
+Config Connector resources expose the `observedGeneration` field in the status
+object, and `kpt` will always report a resource as being `InProgress` if the
+`observedGeneration` doesn't match the value of `metadata.generation`.
+
+If the `Ready` condition is `True`, a Config Connector resource will be reported
+as `Current`, i.e it has been successfully reconciled.
+
+If the `Ready` condition is `False`, `kpt` will look at the `Reason` field on the
+condition object to determine whether the resource is making progress towards
+reconciliation. The possible values mirrors those used by [Config Connector events].
+If the value is one of the following, the resource is considered to have failed
+reconciliation:
+- `ManagementConflict`
+- `UpdateFailed`
+- `DeleteFailed`
+- `DependencyInvalid`
+
+Note that this doesn't necessarily mean it could never successfully reconcile. 
+The Config Connector controller will keep retrying. But it does mean that the
+resource is in a state where an external change is most likely needed to resolve
+the issue. Typical examples would be missing permissions or an API that has not
+been enabled.
+
+Similar to all other resources, a Config Connector resource will be in the `Terminating`
+state if the `metadata.deletionTimestamp` is set, and considered fully deleted when
+the resource no longer exists in the cluster.
+
+[reconcile status]: /book/06-deploying-packages/?id=reconcile-status
+[Config Connector]: https://cloud.google.com/config-connector/docs/overview
+[Config Connector events]: https://cloud.google.com/config-connector/docs/how-to/monitoring-your-resources

site/sidebar.md

@@ -63,6 +63,7 @@
     - [FunctionResultList](reference/schema/function-result-list/)
     - [ResourceList](reference/schema/resource-list/)
     - [CRD Status Convention](reference/schema/crd-status-convention/)
+    - [Config Connector Status Convention](reference/schema/config-connector-status-convention/)
 - [Functions Catalog](https://catalog.kpt.dev/ ":target=_self")
   - [Curated](https://catalog.kpt.dev/ ":target=_self")
   - [Contrib](https://catalog.kpt.dev/contrib/ ":target=_self")