docs(v1): instructions for api conversion tool #12072
Conversation
Signed-off-by: prmellor <[email protected]>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #12072 +/- ##
=========================================
Coverage 74.78% 74.79%
- Complexity 6614 6616 +2
=========================================
Files 376 376
Lines 25325 25325
Branches 3389 3389
=========================================
+ Hits 18939 18941 +2
Misses 4998 4998
+ Partials 1388 1386 -2 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Thanks @PaulRMellor. I left few nits, but looks good otherwise.
| * A later release (planned for 0.52 or 1.0.0) removes the `v1beta2` API and updates all components to use `v1`. | ||
|
|
||
| Complete the conversion of custom resources and CRDs after upgrading to version 0.49 or later, and before upgrading to the later release that removes the `v1beta2` API (Strimzi 0.52 / 1.0.0). | ||
| Resources converted to `v1` are compatible with Strimzi versions 0.49, 0.50, and 0.51. |
There was a problem hiding this comment.
Should we say something like this instead:
| Resources converted to `v1` are compatible with Strimzi versions 0.49, 0.50, and 0.51. | |
| Resources converted to `v1` are compatible with Strimzi versions 0.49 and higher. |
The v1 resources will be compatible with the future versions as well.
| IMPORTANT: When upgrading to Strimzi version 0.49 or later, convert all custom resources and CRDs to the `v1` API. | ||
| The `v1beta2` API is deprecated and will be removed in a future release. | ||
| Conversion must be performed after upgrading the Cluster Operator, so that the Cluster Operator can interpret the resources. | ||
| Custom resources can be updated before or after the Kafka upgrade. | ||
| For more information, see xref:assembly-api-conversion-{context}[Converting Strimzi custom resources to the `v1` API]. |
There was a problem hiding this comment.
I think this is a bit confusing as when upgrading to Strimzi might be read as before or directly with the upgrade. But it cannot be done before as the old version does not have the new fields etc.
So we need to say the following:
- If you have
KafkaUserresources using the.spec.authorization.acls[]operationfields, they should be updated to use.spec.authorization.acls[]operationsbefore upgrading to 0.49.0 or later. - All other resource updates should be done only after the upgrade to 0.49. And they can be done at any point in time before upgrade to 0.52/1.0.0.
| Kubernetes `Job`:: | ||
| Runs the conversion tool as a Kubernetes job inside the cluster. | ||
| Use this command when local access to the cluster is unavailable or restricted. |
There was a problem hiding this comment.
This is not a command of the conversion tool. But as an alternative to running the tool locally, users can run it as Kubernetes Job. So I would for example add it to the end as a note saying something like ...
NOTE: You can also run the tool as a Kubernetes Job instead of running it locally from your computer.
For more information, check the `README.md` file in the Conversion Tool.
| . Verify that the converted resources now use the `kafka.strimzi.io/v1` API version: | ||
| + | ||
| [source,shell] | ||
| ---- | ||
| kubectl get kafkas,kafkaconnects,kafkabridges,kafkamirrormaker2s,kafkarebalances,kafkatopics,kafkausers,kafkanodepools -A \ | ||
| -o custom-columns="VERSION:.apiVersion,KIND:.kind,NAMESPACE:.metadata.namespace,NAME:.metadata.name" \ | ||
| | grep "kafka.strimzi.io/v1" | ||
| ---- |
There was a problem hiding this comment.
This would IMHO always show v1, even if the resources are not converted. So I would remove this.
There was a problem hiding this comment.
Maybe we should add here a clarification that this should be really used just before upgrading to 0.52 / 1.0.0.
2 participants
Documentation
Adds instructions for the Strimzi API conversion tool.
Notes:
Checklist
Please go through this checklist and make sure all applicable tasks have been done