Skip to content

Commit d732bdd

Browse files
trgeigertrgeiger
committed
Add CRD Upgrade Safety documentation
Signed-off-by: Tayler Geiger <[email protected]>
1 parent ff0ce68 commit d732bdd

File tree

2 files changed

+219
-0
lines changed

2 files changed

+219
-0
lines changed

‎docs/refs/crd-upgrade-safety.md

+218
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
# Custom Resource Definition Upgrade Safety
2+
3+
When you update a Custom Resource Definition (CRD), OLM runs a CRD Upgrade Safety preflight
4+
check to ensure backwards compatibility with previous versions of that CRD. The CRD update
5+
must pass the validation checks before the change is allowed to progress on a cluster.
6+
7+
## Prohibited CRD Upgrade Changes
8+
9+
The following changes to an existing CRD will be caught by the CRD Upgrade
10+
Safety preflight check and prevent the upgrade:
11+
- The scope changes from Cluster to Namespace or from Namespace to Cluster
12+
- An existing stored version of the CRD is removed
13+
- A new required field is added to an existing version of the CRD
14+
- An existing field is removed from an existing version of the CRD
15+
- An existing field type is changed in an existing version of the CRD
16+
- A new default value is added to a field that did not previously have a default value
17+
- The default value of a field is changed
18+
- An existing default value of a field is removed
19+
- New enum restrictions are added to an existing field which did not previously have enum restrictions
20+
- Existing enum values from an existing field are removed
21+
- The minimum value of an existing field is increased in an existing version
22+
- The maximum value of an existing field is decreased in an existing version
23+
- Minimum or maximum field constraints are added to a field that did not previously have constraints
24+
25+
!!! note
26+
The rules for changes to minimum and maximum values apply to `minimum`, `minLength`,
27+
`minProperties`, `minItems`, `maximum`, `maxLength`, `maxProperties`, and `maxItems` constrants.
28+
29+
If the CRD Upgrade Safety preflight check encounters one of the disallowed upgrade changes,
30+
it will log an error for each disallowed change detected in the CRD upgrade.
31+
32+
!!! tip
33+
In cases where a change to the CRD does not fall into one of the disallowed change categories
34+
but is also unable to be properly detected as allowed, the CRD Upgrade Safety preflight check
35+
will prevent the upgrade and log an error for an "unknown change."
36+
37+
If you identify any preflight checks that should be implemented to prevent issues during CRD upgrades, please [create a new issue](https://github.com/operator-framework/operator-controller/issues).
38+
39+
40+
## Allowed CRD Upgrade Changes
41+
42+
The following changes to an existing CRD are safe for backwards compatibility and will
43+
not cause the CRD Upgrade Safety preflight check to halt the upgrade:
44+
- Adding new enum values to the list of allowed enum values in a field
45+
- An existing required field is changed to optional in an existing version
46+
- The minimum value of an existing field is decreased in an existing version
47+
- The maximum value of an existing field is increased in an existing version
48+
- A new version of the CRD is added with no modifications to existing versions
49+
50+
51+
## Disabling CRD Upgrade Safety
52+
53+
The CRD Upgrade Safety preflight check can be entirely disabled by adding the
54+
`preflight.crdUpgradeSafety.disabled` field with a value of "true" to the ClusterExtension of the CRD.
55+
56+
```yaml
57+
apiVersion: olm.operatorframework.io/v1alpha1
58+
kind: ClusterExtension
59+
metadata:
60+
name: clusterextension-sample
61+
spec:
62+
installNamespace: default
63+
packageName: argocd-operator
64+
version: 0.6.0
65+
preflight:
66+
crdUpgradeSafety:
67+
disabled: true
68+
```
69+
70+
You cannot disable individual field validators. If you disable the CRD Upgrade Safety preflight check, all field validators are disabled.
71+
72+
!!! warning
73+
Disabling the CRD Upgrade Safety preflight check could break backwards compatibility with previous
74+
versions of the CRD and cause other unintended consequences on the cluster.
75+
76+
77+
## Examples of Unsafe CRD Changes
78+
79+
Take the following CRD as our starting version:
80+
81+
```yaml
82+
---
83+
apiVersion: apiextensions.k8s.io/v1
84+
kind: CustomResourceDefinition
85+
metadata:
86+
annotations:
87+
controller-gen.kubebuilder.io/version: v0.13.0
88+
name: example.test.example.com
89+
spec:
90+
group: test.example.com
91+
names:
92+
kind: Sample
93+
listKind: SampleList
94+
plural: samples
95+
singular: sample
96+
scope: Namespaced
97+
versions:
98+
- name: v1alpha1
99+
schema:
100+
openAPIV3Schema:
101+
properties:
102+
apiVersion:
103+
type: string
104+
kind:
105+
type: string
106+
metadata:
107+
type: object
108+
spec:
109+
type: object
110+
status:
111+
type: object
112+
pollInterval:
113+
type: string
114+
type: object
115+
served: true
116+
storage: true
117+
subresources:
118+
status: {}
119+
```
120+
121+
The following examples will demonstrate specific changes to sections of the example CRD
122+
that would be caught by the CRD Upgrade Safety preflight check.
123+
124+
### Changing Scope
125+
126+
In this example, `scope` has been changed from `Namespaced` to `Cluster`.
127+
128+
??? example
129+
```yaml
130+
spec:
131+
group: test.example.com
132+
names:
133+
kind: Sample
134+
listKind: SampleList
135+
plural: samples
136+
singular: sample
137+
scope: Cluster
138+
versions:
139+
- name: v1alpha1
140+
```
141+
142+
### Removing a previous version
143+
144+
In this example, the only previous version, `v1alpha1`, has been replaced with the new version:
145+
146+
??? example
147+
```yaml
148+
versions:
149+
- name: v1alpha2
150+
schema:
151+
openAPIV3Schema:
152+
properties:
153+
apiVersion:
154+
type: string
155+
kind:
156+
type: string
157+
metadata:
158+
type: object
159+
spec:
160+
type: object
161+
status:
162+
type: object
163+
pollInterval:
164+
type: string
165+
type: object
166+
```
167+
168+
### Removing an existing field
169+
170+
In this example, the `pollInterval` field has been removed from `v1alpha1`:
171+
172+
??? example
173+
```yaml
174+
versions:
175+
- name: v1alpha1
176+
schema:
177+
openAPIV3Schema:
178+
properties:
179+
apiVersion:
180+
type: string
181+
kind:
182+
type: string
183+
metadata:
184+
type: object
185+
spec:
186+
type: object
187+
status:
188+
type: object
189+
type: object
190+
```
191+
192+
### Adding a required field
193+
194+
In this example, `pollInterval` has been changed to a required field:
195+
196+
??? example
197+
```yaml
198+
versions:
199+
- name: v1alpha2
200+
schema:
201+
openAPIV3Schema:
202+
properties:
203+
apiVersion:
204+
type: string
205+
kind:
206+
type: string
207+
metadata:
208+
type: object
209+
spec:
210+
type: object
211+
status:
212+
type: object
213+
pollInterval:
214+
type: string
215+
type: object
216+
required:
217+
- pollInterval
218+
```

‎mkdocs.yml

+1
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ nav:
1818
- Deleting an extension: 'Tasks/uninstall-an-extension.md'
1919
- References:
2020
- Catalog queries: 'refs/catalog-queries.md'
21+
- CRD Upgrade Safety: 'refs/crd-upgrade-safety.md'
2122

2223
markdown_extensions:
2324
- pymdownx.highlight:

0 commit comments

Comments
 (0)