[QUESTION] What is the best practice of updating CRD fields?

[dayeguilaiye]

If I want to add a field in a exist CRD, can I just add the field without creating a new CRD version?
Will this work Or should I do like this?
If I do like this , when I upgrade operator, whill the CRD upgrade the new fields?

And If the best practice is to create a new CRD version, when versions are more than 2, which should I set to storage/served/unserved？
Which version should I choose to be the hub?The newest one or specific one?
Can I change hub from v2 to v3 after there is a new version v3? Or should I?

[camilamacedo86]

Adding a Field to an Existing CRD

When you want to change the schema of a Custom Resource, you have two main options:

1. Modify the Current CRD Version Directly: According to the Kubebuilder practices, it's possible to directly modify the current CRD version by adding new fields. However, there are backward compatibility concerns. If you have existing Custom Resources and controllers operating on them, introducing non-optional fields or removing existing fields can break things.

2. Introduce a New CRD Version: This is a common practice is when making breaking changes. A new version allows for smooth transitions between versions and provides an upgrade path without breaking existing functionality.

CRD Upgrades

When you make changes to a CRD and introduce a new version, you must update your operator's deployment to be aware of this new version. If the operator is set up correctly and you've provided conversion logic (if necessary), old resources will get converted to the new version upon read or write. See the tutorial: https://book.kubebuilder.io/multiversion-tutorial/tutorial

Some thoughts

• storage Version: Only one version can be the storage version. This version is where the resources are stored in etcd. When you introduce a new version, you'd typically mark the new version as the storage version. The API server automatically converts older versions to the current storage version on reads and writes.

• served Versions: You can specify which versions of the CRD are served, meaning they're available for clients. Typically, all versions except deprecated ones should be served.

The "Hub" and "Spoke" Model

You can use the "hub-and-spoke" model for conversion with webhooks:

• Hub: This is the main version to/from which all other versions are converted. When using Kubebuilder, you'd annotate a version's type as the hub using // +kubebuilder:storageversion.

• Spokes: These are other versions that can convert to/from the hub.

It's generally a good idea to make the newest stable version the hub. If you introduce a v3, for instance, and it's deemed stable, you might switch the hub from v2 to v3.

[camilamacedo86]

Closing this one as solved .
However, if you see that is need please re-open

Also, feel free to contribute with Kubebuilder and the docs if you need
We have now a best practices docs as well and you can find references for the kubernetes convention api doc which can be helpful, see: https://github.com/kubernetes-sigs/kubebuilder/blob/master/docs/book/src/reference/good-practices.md

[dayeguilaiye]

Thanks for your reply! That's really detailed and help a lot to me