BZ1973377: Add OSDK / OCP compat notices & steps #34166
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,88 @@ | ||
| // Module included in the following assemblies: | ||
| // | ||
| // * operators/operator_sdk/osdk-working-bundle-images.adoc | ||
|
|
||
| [id="osdk-control-compat_{context}"] | ||
| = Controlling Operator compatibility with {product-title} versions | ||
|
|
||
| [IMPORTANT] | ||
| ==== | ||
| Kubernetes periodically deprecates certain APIs that are removed in subsequent releases. As a result, your Operator projects are unable to use removed APIs starting with the version of {product-title} that uses the Kubernetes version that removed the API. | ||
|
|
||
| As an Operator author, it is strongly recommended that you review the link:https://kubernetes.io/docs/reference/using-api/deprecation-guide/[Deprecated API Migration Guide] in Kubernetes documentation and keep your projects up to date to avoid using deprecated and removed APIs. Ideally, you should update your Operator before the release of a future version of {product-title} that would make the Operator incompatible. | ||
| ==== | ||
adellape marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| When an API is removed from an {product-title} version, Operators running on that cluster version that are still using removed APIs will no longer work properly. As an Operator author, you should plan to update your Operator projects to accommodate API deprecation and removal to avoid interruptions for users of your Operator. | ||
|
|
||
| [TIP] | ||
| ==== | ||
| You can check the event alerts of your Operators running on {product-title} 4.8 and later to find whether there are any warnings about APIs currently in use. The following alerts fire when they detect an API in use that will be removed in the next release: | ||
|
|
||
| `APIRemovedInNextReleaseInUse`:: | ||
| APIs that will be removed in the next OpenShift Container Platform release. | ||
|
|
||
| `APIRemovedInNextEUSReleaseInUse`:: | ||
| APIs that will be removed in the next OpenShift Container Platform link:https://access.redhat.com/support/policy/updates/openshift#ocp4_phases[Extended Update Support (EUS)] release. | ||
| ==== | ||
|
|
||
| If a cluster administrator has installed your Operator, before they upgrade to the next version of {product-title}, they must ensure a version of your Operator is installed that is compatible with that next cluster version. While it is recommended that you update your Operator projects to no longer use deprecated or removed APIs, if you still need to publish your Operator bundles with removed APIs for continued use on earlier versions of {product-title}, ensure that the bundle is configured accordingly. | ||
|
|
||
| The following procedure helps prevent administrators from installing versions of your Operator on an incompatible version of {product-title}. These steps also prevent administrators from upgrading to a newer version of {product-title} that is incompatible with the version of your Operator that is currently installed on their cluster. | ||
|
There was a problem hiding this comment. We need to highlight here something like: IMPORTANT: You should only following the next steps if you have 100% sure that your operator will not work in the specific OPC version. For example, if you need to publish a version using v1betav1 CRD APIs then you know that it will be removed in 1.22 and consequently you should define that the Max OCP Version valid for your operator is 4.8. There was a problem hiding this comment. I think this is better addressed now between the changes mentioned in #34166 (comment) and #34166 (comment). |
||
|
|
||
| [IMPORTANT] | ||
| ==== | ||
| You should configure the following settings in your Operator project as soon as possible. Users running workloads with deprecated APIs that are planning to eventually upgrade to a future version of {product-title} must be running an Operator that has the proper configuration to avoid a cluster upgrade to an incompatible version and potentially adversely impact their critical workloads. | ||
| ==== | ||
adellape marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| .Prerequisites | ||
|
|
||
| - Operator SDK CLI installed on a development workstation | ||
| - Operator project initialized by using the Operator SDK | ||
|
Comment on lines
+37
to
+40
There was a problem hiding this comment. We do not have these pre-requisites for this scenario. We need to remove that. Sorry for not get this before. There was a problem hiding this comment. Removed "Operator project initialized by using the Operator SDK" via https://github.com/openshift/openshift-docs/pull/34348/files#diff-9a5395e4fb38f80963c37a932625ff0a705ed827f3e2ecc59296e085d709ab44L40. |
||
|
|
||
| .Procedure | ||
|
|
||
| . Configure the maximum version of {product-title} that your Operator is compatible with. In your Operator project's cluster service version (CSV), set the `olm.openShiftMaxVersion` annotation to prevent administrators from upgrading their cluster before upgrading the installed Operator to a compatible version: | ||
adellape marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment. Also just noticed that on this line it's Seems like There was a problem hiding this comment. Yes, that is the example sent by OLM team. "olm.properties": '[{"type": "olm.maxOpenShiftVersion", "value": "4.8"}]'
|
||
| + | ||
| .Example CSV with `olm.maxOpenShiftVersion` annotation | ||
| [source,yaml] | ||
| ---- | ||
| apiVersion: operators.coreos.com/v1alpha1 | ||
| kind: ClusterServiceVersion | ||
| metadata: | ||
| annotations: | ||
| "olm.properties": '[{"type": "olm.maxOpenShiftVersion", "value": "4.8"}]' <1> | ||
|
There was a problem hiding this comment. We are not specifying the scenario of v1beta1 in 4.9, so wdyt about we clarify that and replace the 4.8 for OCP tag version, something such as:
Also, we might indeed take advantage of the scenario that we like to cover by providing some e.g. There was a problem hiding this comment. |
||
| ---- | ||
| <1> Setting `value` to `4.8` prevents cluster upgrades to {product-title} versions later than 4.8 when this bundle is installed on a cluster. | ||
|
There was a problem hiding this comment. By looking at that, seems that need to supplement it with info to make clear that they should only use that when they know for sure that the specific bundle is not supported and will not work out in versions upper of the informed versions. There was a problem hiding this comment. Added some qualification to the very beginning of this first step (new part in bold just to highlight here):
|
||
|
|
||
| . If your bundle is intended for distribution in a Red Hat-provided Operator catalog, configure the compatible versions of {product-title} for your Operator by setting the following properties. This configuration ensures your Operator is only included in catalogs that target compatible versions of {product-title}: | ||
| + | ||
| [NOTE] | ||
| ==== | ||
| This step is only valid when publishing Operators in Red Hat-provided catalogs. If your bundle is only intended for distribution in a custom catalog, you can skip this step. For more details, see "Red Hat-provided Operator catalogs". | ||
| ==== | ||
|
|
||
| .. Set the `com.redhat.openshift.versions` annotation in your project's `bundle/metadata/annotations.yaml` file: | ||
| + | ||
| .Example `bundle/metadata/annotations.yaml` file with compatible versions | ||
| [source,yaml] | ||
| ---- | ||
| com.redhat.openshift.versions: "v4.6-v4.8" <1> | ||
| ---- | ||
| <1> Set to a range or single version. | ||
|
|
||
| .. To prevent your bundle from being carried on to an incompatible version of {product-title}, ensure that the index image is generated with the proper `com.redhat.openshift.versions` label in your project's `bundle.Dockerfile`: | ||
|
||
| + | ||
| .Example `bundle.Dockerfile` with compatible versions | ||
| + | ||
| [source,yaml] | ||
| ---- | ||
| LABEL com.redhat.openshift.versions="v4.6-v4.8" <1> | ||
adellape marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| ---- | ||
| <1> Set to a range or single version. | ||
| + | ||
| [NOTE] | ||
| ==== | ||
| This label is also useful when you know that the current version of your Operator will not work well, for any reason, on a specific {product-title} version. By using it, you define the cluster versions where the Operator should be distributed, and the Operator does not appear in a catalog of a cluster version which is outside of the range. | ||
|
There was a problem hiding this comment. The text There was a problem hiding this comment. Took this out of the "NOTE" format and moved it up into the proper intro paragraphs right before the beginning of the procedure. See https://github.com/openshift/openshift-docs/pull/34348/files#diff-9a5395e4fb38f80963c37a932625ff0a705ed827f3e2ecc59296e085d709ab44R32. |
||
| ==== | ||
|
|
||
| You can now bundle a new version of your Operator and publish the updated version to a catalog for distribution. | ||
Uh oh!
There was an error while loading. Please reload this page.