Chapter 1. Understanding API tiers
This guidance does not cover layered MicroShift offerings.
Red Hat requests that application developers validate that any behavior they depend on is explicitly defined in the formal API documentation to prevent introducing dependencies on unspecified implementation-specific behavior or dependencies on bugs in a particular implementation of an API. For example, new releases of an ingress router may not be compatible with older releases if an application uses an undocumented API or relies on undefined behavior.
1.1. API tiers
All commercially supported APIs, components, and features are associated under one of the following support levels:
API tier 1
APIs and application operating environments (AOEs) are stable within a major release. They may be deprecated within a major release, but they will not be removed until a subsequent major release.
API tier 2
APIs and AOEs are stable within a major release for a minimum of 9 months or 3 minor releases from the announcement of deprecation, whichever is longer.
API tier 3
This level applies to languages, tools, applications, and optional Operators included with MicroShift through Operator Hub. Each component will specify a lifetime during which the API and AOE will be supported. Newer versions of language runtime specific components will attempt to be as API and AOE compatible from minor version to minor version as possible. Minor version to minor version compatibility is not guaranteed, however.
Components and developer tools that receive continuous updates through the Operator Hub, referred to as Operators and operands, should be considered API tier 3. Developers should use caution and understand how these components may change with each minor release. Users are encouraged to consult the compatibility guidelines documented by the component.
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) should be specified to signal that the corresponding resource is internal use only and the CRD may be explicitly labeled as tier 4.
1.2. 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 and is not specifically discussed below is assigned API tier 3 by default except for v1alpha1 APIs which are assigned tier 4 by default.
1.2.1. Support for Kubernetes API groups
API groups that end with the suffix *.k8s.io or have the form version.<name> with no suffix are governed by the Kubernetes deprecation policy and follow a general mapping between API version exposed and corresponding support tier unless otherwise specified.
| API version example | API tier |
|---|---|
|
| Tier 1 |
|
| Tier 2 |
|
| Tier 4 |
1.2.2. Support for OpenShift API groups
API groups that end with the suffix *.openshift.io are governed by the MicroShift deprecation policy and follow a general mapping between API version exposed and corresponding compatibility level unless otherwise specified.
| API version example | API tier |
|---|---|
|
| Tier 1 |
|
|
Tier 1 except for |
1.3. API deprecation policy
MicroShift 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.
1.3.1. Deprecating parts of the API
MicroShift 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 MicroShift 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:
| API tier | Duration |
|---|---|
| Tier 1 | 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. |
| 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.
1.3.2. 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 or the CLI depends on a lower tier API.
| 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 |
1.3.3. 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.
| API tier | Duration |
|---|---|
| Tier 1 | 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. |
| Tier 3 | See the component-specific schedule. |
| Tier 4 | None. No compatibility is guaranteed. |
