diff --git a/scripts/generate_site_sidebar/sidebar_template.md.tmpl b/scripts/generate_site_sidebar/sidebar_template.md.tmpl index bfa74c8da2..89cd5e9791 100644 --- a/scripts/generate_site_sidebar/sidebar_template.md.tmpl +++ b/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") diff --git a/site/book/06-deploying-packages/00.md b/site/book/06-deploying-packages/00.md index 2727abf73f..eada6587da 100644 --- a/site/book/06-deploying-packages/00.md +++ b/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/ diff --git a/site/reference/schema/config-connector-status-convention/README.md b/site/reference/schema/config-connector-status-convention/README.md new file mode 100644 index 0000000000..aa501eb5e9 --- /dev/null +++ b/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 diff --git a/site/sidebar.md b/site/sidebar.md index 2c1e8afb9d..c3cde5c2e3 100644 --- a/site/sidebar.md +++ b/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")