Add CRD Upgrade Safety documentation

Signed-off-by: Tayler Geiger <[email protected]>

Author: trgeiger

docs/refs/crd-upgrade-safety.md

@@ -0,0 +1,207 @@
+# Custom Resource Definition Upgrade Safety
+
+OLM implements several validation checks when upgrading Custom Resource Definitions
+in order to maintain backwards compatibility with previous versions of that CRD.
+These validation checks are known collectively as the CRD Upgrade Safety preflight check.
+
+The CRD Upgrade Safety preflight check consists of several individual field validations
+that are performed before an upgrade to a CRD is allowed to progress on a cluster.
+
+## Disallowed CRD Upgrade Changes
+
+The following changes to an existing CRD will be caught by the CRD Upgrade
+Safety preflight check and prevent the upgrade:
+- The scope changes from Cluster to Namespace or from Namespace to Cluster
+- An existing stored version of the CRD is removed
+- A new required field is added to an existing version of the CRD
+- An existing field is removed from an existing version of the CRD
+- An existing field type is changed in an existing version of the CRD
+- A new default value is added to a field that did not previously have a default value
+- The default value of a field is changed
+- An existing default value of a field is removed
+- New enum restrictions are added to an existing field which did not previously have enum restrictions
+- Existing enum values from an existing field are removed
+- The minimum value of an existing field is incrased in an existing version
+- The maximum value of an existing field is decreased in an existing version
+- Minimum or maximum field constraints are added to a field that did not previously have constraints
+
+If the CRD Upgrade Safety preflight check encounters one of the disallowed upgrade changes,
+it will log an error for each disallowed change detected in the CRD upgrade.
+
+In cases where a change to the CRD does not fall into one of the disallowed change categories
+but is also unable to be properly detected as allowed, the CRD Upgrade Safety preflight check
+will prevent the upgrade and log an error for an "unknown change."
+
+**Note:** the rules for changes to minimum and maximum values apply to `minimum`, `minLength`,
+`minProperties`, `minItems`, `maximum`, `maxLength`, `maxProperties`, and `maxItems` constrants.
+
+## Allowed CRD Upgrade Changes
+
+The following changes to an existing CRD are safe for backwards compatibility and will
+not cause the CRD Upgrade Safety preflight check to halt the upgrade:
+- Adding new enum values to the list of allowed enum values in a field
+- An existing required field is changed to optional in an existing version
+- The minimum value of an existing field is decreased in an existing version
+- The maximum value of an existing field is increased in an existing version
+- A new version of the CRD is added with no modifications to existing versions
+
+
+## Disabling CRD Upgrade Safety
+
+The CRD Upgrade Safety preflight check can be entirely disabled by adding the
+`preflight.crdUpgradeSafety.disabled` field with a value of "true" to the ClusterExtension of the CRD.
+
+```yaml
+apiVersion: olm.operatorframework.io/v1alpha1
+kind: ClusterExtension
+metadata:
+    name: clusterextension-sample
+spec:
+    installNamespace: default
+    packageName: argocd-operator
+    version: 0.6.0
+    preflight:
+        crdUpgradeSafety:
+            disabled: true
+```
+
+Only the entire CRD Upgrade Safety preflight check can be disabled, not individual field validators.
+
+**Note**: Disabling the CRD Upgrade Safety preflight check could break backwards compatibility with previous
+versions of the CRD and cause other unintended consequences on the cluster.
+
+
+## Examples of Unsafe CRD Changes
+
+Take the following CRD as our starting version:
+
+```yaml
+---
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  annotations:
+    controller-gen.kubebuilder.io/version: v0.13.0
+  name: example.test.example.com
+spec:
+  group: test.example.com
+  names:
+    kind: Sample
+    listKind: SampleList
+    plural: samples
+    singular: sample
+  scope: Namespaced
+  versions:
+  - name: v1alpha1
+    schema:
+      openAPIV3Schema:
+        properties:
+          apiVersion:
+            type: string
+          kind:
+            type: string
+          metadata:
+            type: object
+          spec:
+            type: object
+          status:
+            type: object
+          pollInterval:
+            type: string
+        type: object
+    served: true
+    storage: true
+    subresources:
+      status: {}
+```
+
+The following examples will demonstrate specific changes to sections of the example CRD
+that would be caught by the CRD Upgrade Safety preflight check.
+
+### Changing Scope
+
+In this example, `scope` has been changed from `Namespaced` to `Cluster`.
+```yaml
+spec:
+  group: test.example.com
+  names:
+    kind: Sample
+    listKind: SampleList
+    plural: samples
+    singular: sample
+  scope: Cluster
+  versions:
+  - name: v1alpha1
+```
+
+### Removing a previous version
+
+In this example, the only previous version, `v1alpha1`, has been replaced with the new version:
+```yaml
+  versions:
+  - name: v1alpha2
+    schema:
+      openAPIV3Schema:
+        properties:
+          apiVersion:
+            type: string
+          kind:
+            type: string
+          metadata:
+            type: object
+          spec:
+            type: object
+          status:
+            type: object
+          pollInterval:
+            type: string
+        type: object
+```
+
+### Removing an existing field
+
+In this example, the `pollInterval` field has been removed from `v1alpha1`:
+```yaml
+  versions:
+  - name: v1alpha1
+    schema:
+      openAPIV3Schema:
+        properties:
+          apiVersion:
+            type: string
+          kind:
+            type: string
+          metadata:
+            type: object
+          spec:
+            type: object
+          status:
+            type: object
+        type: object
+```
+
+### Adding a required field
+
+In this example, `pollInterval` has been changed to a required field:
+```yaml
+  versions:
+  - name: v1alpha2
+    schema:
+      openAPIV3Schema:
+        properties:
+          apiVersion:
+            type: string
+          kind:
+            type: string
+          metadata:
+            type: object
+          spec:
+            type: object
+          status:
+            type: object
+          pollInterval:
+            type: string
+        type: object
+        required:
+        - pollInterval
+```