kgo: add UPGRADE.md and README section about CRD management (#1156)

* kgo: add UPGRADE.md and README section about CRD management

* chore(kgo): add exemplary incantations of CRD upgrade commands

charts/gateway-operator/README.md

@@ -10,3 +10,27 @@ helm repo update
 
 helm install kgo kong/gateway-operator -n kong-system --create-namespace
 ```
+
+### CRD management
+
+Helm 3 introduced a simplified CRD management method that is safer than what was
+available in Helm 2, but requires some manual work when a chart added or modified CRDs:
+CRDs are created on install if they are not already present, but are not modified during
+release upgrades or deletes. Our chart release upgrade instructions will call out
+when manual action is necessary to update CRDs. This CRD handling strategy is
+recommended for most users.
+
+Some users may wish to manage their CRDs automatically. If you manage your CRDs
+this way, we _strongly_ recommend that you back up all associated custom
+resources in the event you need to recover from unintended CRD deletion.
+
+Any changes requiring manual CRD updates will be called out in the release notes.
+Those manual steps can be found in [UPGRADE.md](UPGRADE.md).
+
+#### CRD sources
+
+This project uses CRDs from 3 sources at this moment:
+
+- [Gateway API](https://gateway-api.sigs.k8s.io/)
+- [Kong Kubernetes Configuration](https://github.com/Kong/kubernetes-configuration)
+- [Gateway Operator CRDs](https://github.com/Kong/gateway-operator)

charts/gateway-operator/UPGRADE.md

@@ -0,0 +1,41 @@
+# Upgrade considerations
+
+New versions of this chart may add significant new functionality or
+deprecate/entirely remove old functionality. This document covers how and why
+users should update their chart configuration to take advantage of new features
+or migrate away from deprecated features.
+
+In general, breaking changes deprecate their old features before removing them
+entirely. While support for the old functionality remains, the chart will show
+a warning about the outdated configuration when running
+`helm install/status/upgrade`.
+
+Note that not all versions contain breaking changes. If a version is not
+present in the table of contents, it requires no version-specific changes when
+upgrading from a previous version.
+
+## Updates to CRDs
+
+Helm installs CRDs at initial install but [does not update them after][hip0011].
+Some chart releases include updates to CRDs that must be applied to successfully
+upgrade. Because Helm does not handle these updates, you must manually apply
+them before upgrading your release.
+
+[hip0011]: https://github.com/helm/community/blob/main/hips/hip-0011.md
+
+For example, upgrading Kong's [kubernetes-configuration][kcfg] CRDs to v0.0.38 requires
+running:
+
+```
+kustomize build github.com/Kong/kubernetes-configuration/config/crd\?rev\=v0.0.38 | kubectl apply -f -
+```
+
+[kcfg]: https://github.com/Kong/kubernetes-configuration
+
+Upgrading [Gateway API][gwapi] to v1.2.0 requires running:
+
+```
+kustomize build github.com/kubernetes-sigs/gateway-api/config/crd\?ref=v1.2.0 | kubectl apply -f -
+```
+
+[gwapi]: https://github.com/kubernetes-sigs/gateway-api/