Added API support and compatability docs

Author: ahardin-rh

_topic_map.yml

@@ -2108,6 +2108,10 @@ Name: API reference
 Dir: rest_api
 Distros: openshift-enterprise,openshift-origin
 Topics:
+- Name: Understanding API tiers
+  File: understanding-api-support-tiers
+- Name: API compatibility guidelines
+  File: understanding-compatibility-guidelines
 - Name: Editing kubelet log level verbosity and gathering logs
   File: editing-kubelet-log-level-verbosity
 - Name: API list

modules/api-compatibility-common-terminology.adoc

@@ -0,0 +1,54 @@
+// Module included in the following assemblies:
+//
+// * rest_api/understanding-compatibility-guidelines.adoc
+
+[id="api-compatibility-common-terminology_{context}"]
+= API compatibility common terminology
+
+[id="api-compatibility-common-terminology-api_{context}"]
+== Application Programming Interface (API)
+
+An API is a public interface implemented by a software program that enables it to interact with other software. In {product-title}, the API is served from a centralized API server and is used as the hub for all system interaction.
+
+[id="api-compatibility-common-terminology-aoe_{context}"]
+== Application Operating Environment (AOE)
+
+An AOE is the integrated environment that executes the end-user application program. The AOE is a containerized environment that provides isolation from the host operating system (OS). At a minimum, AOE allows the application to run in an isolated manner from the host OS libraries and binaries, but still share the same OS kernel as all other containers on the host. The AOE is enforced at runtime and it describes the interface between an application and its operating environment. It includes intersection points between the platform, operating system and environment, with the user application including projection of downward API, DNS, resource accounting, device access, platform workload identity, isolation among containers, isolation between containers and host OS.
+
+The AOE does not include components that might vary by installation, such as Container Network Interface (CNI) plug-in selection or extensions to the product such as admission hooks. Components that integrate with the cluster at a level below the container environment might be subjected to additional variation between versions.
+
+[id="api-compatibility-common-terminology-virtualized_{context}"]
+== Compatibility in a virtualized environment
+
+Virtual environments emulate bare-metal environments such that unprivileged applications that run on bare-metal environments will run, unmodified, in corresponding virtual environments. Virtual environments present simplified abstracted views of physical resources, so some differences might exist.
+
+[id="api-compatibility-common-terminology-cloud_{context}"]
+== Compatibility in a cloud environment
+
+{product-title} might choose to offer integration points with a hosting cloud environment via cloud provider specific integrations. The compatibility of these integration points are specific to the guarantee provided by the native cloud vendor and its intersection with the {product-title} compatibility window.  Where {product-title} provides an integration with a cloud environment natively as part of the default installation, Red Hat develops against stable cloud API endpoints to provide commercially reasonable support with forward looking compatibility that includes stable deprecation policies. Example areas of integration between the cloud provider and {product-title} include, but are not limited to, dynamic volume provisioning, service load balancer integration, pod workload identity, dynamic management of compute, and infrastructure provisioned as part of initial installation.
+
+[id="api-compatibility-common-terminology-releases_{context}"]
+== Major, minor, and z-stream releases
+
+A Red Hat major release represents a significant step in the development of a product. Minor releases appear more frequently within the scope of a major release and represent deprecation boundaries that might impact future application compatibility. A z-stream release is an update to a minor release which provides a stream of continuous fixes to an associated minor release. API and AOE compatibility is never broken in a z-stream release except when this policy is explicitly overridden in order to respond to an unforeseen security impact.
+
+For example, in the release 4.3.2:
+
+* 4 is the major release version
+* 3 is the minor release version
+* 2 is the z-stream release version
+
+[id="api-compatibility-common-terminology-eus_{context}"]
+== Extended user support (EUS)
+
+A minor release in an {product-title} major release that has an extended support window for critical bug fixes. Users are able to migrate between EUS releases by incrementally adopting minor versions between EUS releases. It is important to note that the deprecation policy is defined across minor releases and not EUS releases. As a result, an EUS user might have to respond to a deprecation when migrating to a future EUS while sequentially upgrading through each minor release.
+
+[id="api-compatibility-common-terminology-dev-preview_{context}"]
+== Developer Preview
+
+An optional product capability that is not officially supported by Red Hat, but is intended to provide a mechanism to explore early phase technology. By default, Developer Preview functionality is opt-in, and subject to removal at any time. Enabling a Developer Preview feature might render a cluster unsupportable dependent upon the scope of the feature.
+
+[id="api-compatibility-common-terminology-tech-preview_{context}"]
+== Technology Preview
+
+An optional product capability that provides early access to upcoming product innovations to test functionality and provide feedback during the development process. The feature is not fully supported, might not be functionally complete, and is not intended for production use. Usage of a Technology Preview function requires explicit opt-in. Learn more about the link:https://access.redhat.com/support/offerings/techpreview[Technology Preview Features Support Scope].

modules/api-compatibility-exceptions.adoc

@@ -0,0 +1,37 @@
+// Module included in the following assemblies:
+//
+// * rest_api/understanding-compatibility-guidelines.adoc
+
+[id="api-compatibility-exceptions_{context}"]
+= API compatibility exceptions
+
+The following are exceptions to compatibility in {product-title}:
+
+[discrete]
+[id="OS-file-system-modifications-not-made_{context}"]
+== RHEL CoreOS file system modifications not made with a supported Operator
+
+No assurances are made at this time that a modification made to the host operating file system is preserved across minor releases except for where that modification is made through the public interface exposed via a supported Operator, such as the Machine Config Operator or Node Tuning Operator.
+
+[discrete]
+[id="modifications-to-cluster-infrastructure-in-cloud_{context}"]
+== Modifications to cluster infrastructure in cloud or virtualized environments
+
+No assurances are made at this time that a modification to the cloud hosting environment that supports the cluster is preserved except for where that modification is made through a public interface exposed in the product or is documented as a supported configuration. Cluster infrastructure providers are responsible for preserving their cloud or virtualized infrastructure except for where they delegate that authority to the product through an API.
+
+[discrete]
+[id="Functional-defaults-between-upgraded-cluster-new-installation_{context}"]
+== Functional defaults between an upgraded cluster and a new installation
+
+No assurances are made at this time that a new installation of a product minor release will have the same functional defaults as a version of the product that was installed with a prior minor release and upgraded to the equivalent version. For example, future versions of the product may provision cloud infrastructure with different defaults than prior minor versions. In addition, different default security choices may be made in future versions of the product than those made in past versions of the product. Past versions of the product will forward upgrade, but preserve legacy choices where appropriate specifically to maintain backwards compatibility.
+
+[discrete]
+[id="API-fields-that-have-the-prefix-unsupported-annotations_{context}"]
+== Usage of API fields that have the prefix "unsupported” or undocumented annotations
+
+Select APIs in the product expose fields with the prefix `unsupported<FieldName>`. No assurances are made at this time that usage of this field is supported across releases or within a release. Product support can request a customer to specify a value in this field when debugging specific problems, but its usage is not supported outside of that interaction. Usage of annotations on objects that are not explicitly documented are not assured support across minor releases.
+
+[discrete]
+[id="API-availability-per-product-installation-topology_{context}"]
+== API availability per product installation topology
+The OpenShift distribution will continue to evolve its supported installation topology, and not all APIs in one install topology will necessarily be included in another. For example, certain topologies may restrict read/write access to particular APIs if they are in conflict with the product installation topology or not include a particular API at all if not pertinent to that topology. APIs that exist in a given topology will be supported in accordance with the compatibility tiers defined above.

modules/api-compatibility-guidelines.adoc

@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// * rest_api/understanding-compatibility-guidelines.adoc
+
+[id="api-compatibility-guidelines_{context}"]
+= API compatibility guidelines
+
+Red Hat recommends that application developers adopt the following principles in order to improve compatibility with {product-title}:
+
+* Use APIs and components with support tiers that match the application's need.
+* Build applications using the published client libraries where possible.
+* Applications are only guaranteed to run correctly if they execute in an environment that is as new as the environment it was built to execute against. An application that was built for {product-title} 4.7 is not guaranteed to function properly on {product-title} 4.6.
+* 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.
+
+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:
+
+* Do not depend on a specific Linux kernel or {product-title} version.
+* Avoid reading from `proc`, `sys`, and `debug` file systems, or any other pseudo file system.
+* Avoid using `ioctls` to directly interact with hardware.
+* Avoid direct interaction with `cgroups` in order to not conflict with {product-title} host-agents that provide the container execution environment.
+
+[NOTE]
+====
+During the lifecycle of a release, Red Hat makes commercially reasonable efforts to maintain API and application operating environment (AOE) compatibility across all minor releases and z-stream releases. If necessary, Red Hat might make exceptions to this compatibility goal for critical impact security or other significant issues.
+====

modules/api-support-deprecation-policy.adoc

@@ -0,0 +1,103 @@
+// Module included in the following assemblies:
+//
+// * rest_api/understanding-api-support-tiers.adoc
+
+[id="api-deprecation-policy_{context}"]
+= API deprecation policy
+
+{product-title} is composed of many components sourced from many upstream communities. It is anticipated that the set of components, the associated API interfaces, and correlated features will evolve over time and might require formal deprecation in order to remove the capability.
+
+[id="deprecating-parts-of-the-api_{context}"]
+== Deprecating parts of the API
+
+{product-title} is a distributed system where multiple components interact with a shared state managed by the cluster control plane through a set of structured APIs. Per Kubernetes conventions, each API presented by {product-title} is associated with a group identifier and each API group is independently versioned.  Each API group is managed in a distinct upstream community including Kubernetes, Metal3, Multus, Operator Framework, Open Cluster Management, OpenShift itself, and more.
+
+While each upstream community might define their own unique deprecation policy for a given API group and version, Red Hat normalizes the community specific policy to one of the compatibility levels defined prior based on our integration in and awareness of each upstream community to simplify end-user consumption and support.
+
+The deprecation policy and schedule for APIs vary by compatibility level.
+
+The deprecation policy covers all elements of the API including:
+
+* REST resources, also known as API objects
+* Fields of REST resources
+* Annotations on REST resources, excluding version-specific qualifiers
+* Enumerated or constant values
+
+Other than the most recent API version in each group, older API versions must be supported after their announced deprecation for a duration of no less than:
+
+[cols="2",options="header"]
+|===
+|API tier
+|Duration
+
+|Tier 1
+|12 months or 3 releases from the announcement of deprecation, whichever is longer.
+
+|Tier 2
+|9 months or 3 releases from the announcement of deprecation, whichever is longer.
+
+|Tier 3
+|See the component-specific schedule.
+
+|Tier 4
+|None. No compatibility is guaranteed.
+
+|===
+
+The following rules apply to all tier 1 APIs:
+
+* API elements can only be removed by incrementing the version of the group.
+* API objects must be able to round-trip between API versions without information loss, with the exception of whole REST resources that do not exist in some versions.  In cases where equivalent fields do not exist between versions, data will be preserved in the form of annotations during conversion.
+* API versions in a given group can not deprecate until a new API version at least as stable is released, except in cases where the entire API object is being removed.
+
+[id="deprecating-cli-elements_{context}"]
+== Deprecating CLI elements
+
+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.
+
+[cols="3",options="header"]
+|===
+
+|
+|Element
+|API tier
+
+|Generally available (GA)
+|Flags and commands
+|Tier 1
+
+|Technology Preview
+|Flags and commands
+|Tier 3
+
+|Developer Preview
+|Flags and commands
+|Tier 4
+
+|===
+
+[id="deprecating-entire-component_{context}"]
+== Deprecating an entire component
+
+The duration and schedule for deprecating an entire component maps directly to the duration associated with the highest API tier of an API exposed by that component. For example, a component that surfaced APIs with tier 1 and 2 could not be removed until the tier 1 deprecation schedule was met.
+
+[cols="2",options="header"]
+|===
+|API tier
+|Duration
+
+|Tier 1
+|12 months or 3 releases from the announcement of deprecation, whichever is longer.
+
+|Tier 2
+|9 months or 3 releases from the announcement of deprecation, whichever is longer.
+
+|Tier 3
+|See the component-specific schedule.
+
+|Tier 4
+|None. No compatibility is guaranteed.
+
+|===