Merge pull request #34348 from adellape/osdk_apidep2

Author: adellape

modules/osdk-control-compat.adoc

@@ -7,9 +7,9 @@
 
 [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.
+Kubernetes periodically deprecates certain APIs that are removed in subsequent releases. If your Operator is using a deprecated API, it might no longer work after the {product-title} cluster is upgraded to the Kubernetes version where the API has been removed.
 
-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.
+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 Operator 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.
 ====
 
 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.
@@ -29,19 +29,20 @@ If a cluster administrator has installed your Operator, before they upgrade to t
 
 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.
 
+This procedure 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 defining the cluster versions where the Operator should be distributed, you ensure that the Operator does not appear in a catalog of a cluster version which is outside of the allowed range.
+
 [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.
+Operators that use deprecated APIs can adversely impact critical workloads when cluster administrators upgrade to a future version of {product-title} where the API is no longer supported. If your Operator is using deprecated APIs, you should configure the following settings in your Operator project as soon as possible.
 ====
 
 .Prerequisites
 
-- Operator SDK CLI installed on a development workstation
-- Operator project initialized by using the Operator SDK
+- An existing Operator project
 
 .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:
+. If you know that a specific bundle of your Operator is not supported and will not work correctly on {product-title} later than a certain cluster version, 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.maxOpenShiftVersion` annotation to prevent administrators from upgrading their cluster before upgrading the installed Operator to a compatible version:
 +
 .Example CSV with `olm.maxOpenShiftVersion` annotation
 [source,yaml]
@@ -50,9 +51,9 @@ apiVersion: operators.coreos.com/v1alpha1
 kind: ClusterServiceVersion
 metadata:
   annotations:
-    "olm.properties": '[{"type": "olm.maxOpenShiftVersion", "value": "4.8"}]' <1>
+    "olm.properties": '[{"type": "olm.maxOpenShiftVersion", "value": "<cluster_version>"}]' <1>
 ----
-<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.
+<1> Specify the maximum cluster version of {product-title} that your Operator is compatible with. For example, setting `value` to `4.8` prevents cluster upgrades to {product-title} versions later than 4.8 when this bundle is installed on a cluster.
 
 . 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}:
 +
@@ -70,19 +71,14 @@ 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`:
+.. 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 Operator's bundle image. For example, if your project was generated using the Operator SDK, update the `bundle.Dockerfile` file:
 +
 .Example `bundle.Dockerfile` with compatible versions
 +
 [source,yaml]
 ----
-LABEL com.redhat.openshift.versions="v4.6-v4.8" <1>
+LABEL com.redhat.openshift.versions="<versions>" <1>
 ----
-<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.
-====
+<1> Set to a range or single version, for example, `v4.6-v4.8`. This setting defines 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.
 
 You can now bundle a new version of your Operator and publish the updated version to a catalog for distribution.