|
| 1 | +# Multiversion CRD |
| 2 | + |
| 3 | +The purpose of this README is to discuss the current/future experience of transitioning between |
| 4 | +versions of the postgrescluster CRD, as well as to identify future work. |
| 5 | + |
| 6 | +## Version sorting and how that affects retrieval |
| 7 | + |
| 8 | +[Version sorting in Kubernetes](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#version-priority) means that v1 takes |
| 9 | +precedence over v1beta1. Version sorting disregards storage version. |
| 10 | + |
| 11 | +So if you run `kubectl explain postgrescluster.spec.userInterface` you will get the v1 explainer. |
| 12 | +In order to get the explainer in a particular version form, you need to add the `--api-version` flag: |
| 13 | + |
| 14 | +```bash |
| 15 | +kubectl explain postgrescluster.spec.userInterface --api-version=postgres-operator.crunchydata.com/v1 |
| 16 | +``` |
| 17 | + |
| 18 | +For `kubectl get`, the way to specify api version is in the resource name. That is, rather than |
| 19 | +`kubectl get postgrescluster`, you could put |
| 20 | + |
| 21 | +```bash |
| 22 | +kubectl get postgrescluster.v1beta1.postgres-operator.crunchydata.com hippo -o yaml |
| 23 | +``` |
| 24 | + |
| 25 | +That will return the `v1beta1` representation of that cluster. |
| 26 | + |
| 27 | +**Future work**: The CLI tool calls kubectl, so we may need to expose/add a flag to allow people to specify |
| 28 | +versions; we may also need to update some of the create and other commands to allow multiple versions (if desired). |
| 29 | + |
| 30 | +### K9s and other GUIs |
| 31 | + |
| 32 | +I'm not sure what other tools people use, but I know k9s is pretty popular. Unfortunately, |
| 33 | +I cannot find a way to specify the form a K8s object is retrieved in. See [here](https://github.com/derailed/k9s/issues/838). |
| 34 | + |
| 35 | +## Transitioning from v1beta1 to v1 |
| 36 | + |
| 37 | +If you have a v1beta1 cluster and want to save it as v1, you can change the `apiVersion` field: |
| 38 | + |
| 39 | +Change |
| 40 | + |
| 41 | +```yaml |
| 42 | +apiVersion: postgres-operator.crunchydata.com/v1beta1 |
| 43 | +``` |
| 44 | +
|
| 45 | +to |
| 46 | +
|
| 47 | +```yaml |
| 48 | +apiVersion: postgres-operator.crunchydata.com/v1 |
| 49 | +``` |
| 50 | +
|
| 51 | +And if the cluster is acceptable as a v1 object, it will be saved. |
| 52 | +
|
| 53 | +It may return a warning if some new XValidation rule is being tested. For instance, since we've added a rule |
| 54 | +that the `spec.userInterface` field should be null in v1, if you have a postgrescluster with that field |
| 55 | +in a v1beta1 but _do not_ change that field, then you can save your cluster as a v1 version even though it will |
| 56 | +return a warning that that field should be null. |
| 57 | + |
| 58 | +(This is a result of using validation ratcheting, which should be enabled in K8s 1.30+ / OCP 4.17+.) |
| 59 | + |
| 60 | +If you want to test whether a save or adjustment will be successful, you can run a dry-run first. That is, |
| 61 | +add `--dry-run=server` to your create/apply command. This will check against the object as it currently exists |
| 62 | +for the server. |
| 63 | + |
| 64 | +If you get blocked or if you get a warning and want to eliminate that warning, the way to do that is to update |
| 65 | +the spec or make changes that will enable that spec to be valid. Hopefully the error messages from the K8s |
| 66 | +API will help determine the change that are required. |
| 67 | + |
| 68 | +That is, if you have a `spec.userInterface`, and the error informs you that this field is no longer available in v1, |
| 69 | +you may need to check our documentation on the preferred way to deploy a pgAdmin4 deployment. |
| 70 | + |
| 71 | +(We may in the future want to actually provide steps for all of the fields that we are changing, |
| 72 | +e.g., a migration guide.) |
| 73 | + |
0 commit comments