Merge pull request #41803 from bparees/apidocs

Author: Bob Furu

modules/api-compatibility-guidelines.adoc

@@ -13,6 +13,7 @@ Red Hat recommends that application developers adopt the following principles in
 * Do not design applications that rely on configuration files provided by system packages or other components. These files can change between versions unless the upstream community is explicitly committed to preserving them. Where appropriate, depend on any Red Hat provided interface abstraction over those configuration files in order to maintain forward compatibility. Direct file system modification of configuration files is discouraged, and users are strongly encouraged to integrate with an Operator provided API where available to avoid dual-writer conflicts.
 * Do not depend on API fields prefixed with `unsupported<FieldName>` or annotations that are not explicitly mentioned in product documentation.
 * Do not depend on components with shorter compatibility guarantees than your application.
+* Do not perform direct storage operations on the etcd server. All etcd access must be performed via the api-server or through documented backup and restore procedures.
 
 Red Hat recommends that application developers follow the link:https://access.redhat.com/articles/rhel8-abi-compatibility#Guidelines[compatibility guidelines] defined by {op-system-base-full}. {product-title} strongly recommends the following guidelines when building an application or hosting an application on the platform:
 

modules/api-support-deprecation-policy.adoc

@@ -31,7 +31,7 @@ Other than the most recent API version in each group, older API versions must be
 |Duration
 
 |Tier 1
-|12 months or 3 releases from the announcement of deprecation, whichever is longer.
+|Stable within a major release. They may be deprecated within a major release, but they will not be removed until a subsequent major release.
 
 |Tier 2
 |9 months or 3 releases from the announcement of deprecation, whichever is longer.
@@ -55,7 +55,7 @@ The following rules apply to all tier 1 APIs:
 
 Client-facing CLI commands are not versioned in the same way as the API, but are user-facing component systems. The two major ways a user interacts with a CLI are through a command or flag, which is referred to in this context as CLI elements.
 
-All CLI elements default to API tier 1 unless otherwise noted.
+All CLI elements default to API tier 1 unless otherwise noted or the CLI depends on a lower tier API.
 
 [cols="3",options="header"]
 |===
@@ -89,7 +89,7 @@ The duration and schedule for deprecating an entire component maps directly to t
 |Duration
 
 |Tier 1
-|12 months or 3 releases from the announcement of deprecation, whichever is longer.
+|Stable within a major release. They may be deprecated within a major release, but they will not be removed until a subsequent major release.
 
 |Tier 2
 |9 months or 3 releases from the announcement of deprecation, whichever is longer.

modules/api-support-tiers-mapping.adoc

@@ -5,7 +5,7 @@
 [id="api-support-tiers-mapping_{context}"]
 = Mapping API tiers to API groups
 
-For each API tier defined by Red Hat, we provide a mapping table for specific API groups where the upstream communities are committed to maintain forward compatibility. Any API group that does not specify an explicit compatibility level is assigned API tier 3 by default.
+For each API tier defined by Red Hat, we provide a mapping table for specific API groups where the upstream communities are committed to maintain forward compatibility. Any API group that does not specify an explicit compatibility level and is not specifically discussed below is assigned API tier 3 by default except for `v1alpha1` APIs which are assigned tier 4 by default.
 
 [id="mapping-support-tiers-to-kubernetes-api-groups_{context}"]
 == Support for Kubernetes API groups

modules/api-support-tiers.adoc

@@ -29,4 +29,4 @@ Components and developer tools that receive continuous updates through the Opera
 == API tier 4
 No compatibility is provided. API and AOE can change at any point. These capabilities should not be used by applications needing long-term support.
 
-It is common practice for Operators to use custom resource definitions (CRDs) internally to accomplish a task.  These objects are not meant for use by actors external to the Operator and are intended to be hidden.  If any CRD is not meant for use by actors external to the Operator, the `operators.operatorframework.io/internal-objects` annotation in the Operators `ClusterServiceVersion` (CSV) must be specified, and that signals that the corresponding resource is internal use only.
+It is common practice for Operators to use custom resource definitions (CRDs) internally to accomplish a task. These objects are not meant for use by actors external to the Operator and are intended to be hidden. If any CRD is not meant for use by actors external to the Operator, the `operators.operatorframework.io/internal-objects` annotation in the Operators `ClusterServiceVersion` (CSV) should be specified to signal that the corresponding resource is internal use only and the CRD may be explicitly labeled as tier 4.