mirror of
https://github.com/k3s-io/kubernetes.git
synced 2025-07-24 12:15:52 +00:00
Doc: apigroups, alpha, beta, experimental/v1alpha1
This commit is contained in:
Eric Tune
parent
11c735cefa
commit
ca6c950b89
@ -209,9 +209,13 @@ all or certain hosts, and when it needs to start before other pods.
|
||||
|
||||
## Caveats
|
||||
|
||||
DaemonSet is part of the experimental API group, so it is not subject to the same compatibility
|
||||
guarantees as objects in the main API. It may not be enabled. Enable by setting
|
||||
`--runtime-config=experimental/v1alpha1` on the apiserver.
|
||||
DaemonSet objects are in the [`extensions` API Group](../api.md#api-groups). This API group may or
|
||||
may not be enabled on your cluster.
|
||||
|
||||
DaemonSet objects effectively have [API version `v1alpha1`](../api.md#api-versioning).
|
||||
Alpha objects may change or even be discontinued in future software releases.
|
||||
However, due to to a known issue, they may appear as API version `v1beta1` if enabled.
|
||||
|
||||
|
||||
|
||||
<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
|
||||
|
||||
56
docs/api.md
56
docs/api.md
@ -55,11 +55,63 @@ What constitutes a compatible change and how to change the API are detailed by t
|
||||
|
||||
## API versioning
|
||||
|
||||
To make it easier to eliminate fields or restructure resource representations, Kubernetes supports multiple API versions, each at a different API path prefix, such as `/api/v1beta3`. These are simply different interfaces to read and/or modify the same underlying resources. In general, all API resources are accessible via all API versions, though there may be some cases in the future where that is not true.
|
||||
To make it easier to eliminate fields or restructure resource representations, Kubernetes supports
|
||||
multiple API versions, each at a different API path, such as `/api/v1` or
|
||||
`/apis/extensions/v1beta1`.
|
||||
|
||||
We chose to version at the API level rather than at the resource or field level to ensure that the API presents a clear, consistent view of system resources and behavior, and to enable controlling access to end-of-lifed and/or experimental APIs.
|
||||
|
||||
The [API and release versioning proposal](design/versioning.md) describes the current thinking on the API version evolution process.
|
||||
Note that API versioning and Software versioning are only indirectly related. The [API and release
|
||||
versioning proposal](design/versioning.md) describes the relationship between API versioning and
|
||||
software versioning.
|
||||
|
||||
|
||||
Different API versions imply different levels of stability and support. The criteria for each level are described
|
||||
in more detail in the [API Changes documentation](devel/api_changes.md#alpha-beta-and-stable-versions). They are summarized here:
|
||||
|
||||
- Alpha level:
|
||||
- The version names contain `alpha` (e.g. `v1alpha1`).
|
||||
- May be buggy. Enabling the feature may expose bugs. Disabled by default.
|
||||
- Support for feature may be dropped at any time without notice.
|
||||
- The API may change in incompatible ways in a later software release without notice.
|
||||
- Recommended for use only in short-lived testing clusters, due to increased risk of bugs and lack of long-term support.
|
||||
- Beta level:
|
||||
- The version names contain `beta` (e.g. `v2beta3`).
|
||||
- Code is well tested. Enabling the feature is considered safe. Enabled by default.
|
||||
- Support for the overall feature will not be dropped, though details may change.
|
||||
- The schema and/or semantics of objects may change in incompatible ways in a subsequent beta or stable release. When this happens,
|
||||
we will provide instructions for migrating to the next version. This may require deleting, editing, and re-creating
|
||||
API objects. The editing process may require some thought. This may require downtime for appplications that rely on the feature.
|
||||
- Recommended for only non-business-critical uses because of potential for incompatible changes in subsequent releases. If you have
|
||||
multiple clusters which can be upgraded independently, you may be able to relax this restriction.
|
||||
- **Please do try our beta features and give feedback on them! Once they exit beta, it may not be practical for us to make more changes.**
|
||||
- Stable level:
|
||||
- The version name is `vX` where `X` is an integer.
|
||||
- Stable versions of features will appear in released software for many subsequent versions.
|
||||
|
||||
## API groups
|
||||
|
||||
To make it easier to extend the Kubernetes API, we are in the process of implementing [*API
|
||||
groups*](proposals/api-groups.md). These are simply different interfaces to read and/or modify the
|
||||
same underlying resources. The API group is specified in a REST path and in the `apiVersion` field
|
||||
of a serialized object.
|
||||
|
||||
Currently there are two API groups in use:
|
||||
|
||||
1. the "core" group, which is at REST path `/api/v1` and is not specified as part of the `apiVersion` field, e.g.
|
||||
`apiVersion: v1`.
|
||||
1. the "extensions" group, which is at REST path `/apis/extensions/$VERSION`, and which uses
|
||||
`apiVersion: extensions/$VERSION` (e.g. currently `apiVersion: extensions/v1beta1`).
|
||||
|
||||
In the future we expect that there will be more API groups, all at REST path `/apis/$API_GROUP` and
|
||||
using `apiVersion: $API_GROUP/$VERSION`. We expect that there will be a way for (third parties to
|
||||
create their own API groups](design/extending-api.md), and to avoid naming collisions.
|
||||
|
||||
## Enabling the extensions group
|
||||
|
||||
Enable `extensions/v1beta1` objects by adding the following flags to your API server:
|
||||
|
||||
- `--runtime-config=extensions/v1beta1=true`
|
||||
|
||||
## v1beta1, v1beta2, and v1beta3 are deprecated; please move to v1 ASAP
|
||||
|
||||
|
||||
@ -535,6 +535,69 @@ The API spec changes should be in a commit separate from your other changes.
|
||||
|
||||
TODO(smarterclayton): write this.
|
||||
|
||||
## Alpha, Beta, and Stable Versions
|
||||
|
||||
New feature development proceeds through a series of stages of increasing maturity:
|
||||
|
||||
- Development level
|
||||
- Object Versioning: no convention
|
||||
- Availability: not commited to main kubernetes repo, and thus not available in offical releases
|
||||
- Audience: other developers closely collaborating on a feature or proof-of-concept
|
||||
- Upgradeability, Reliability, Completeness, and Support: no requirements or guarantees
|
||||
- Alpha level
|
||||
- Object Versioning: API version name contains `alpha` (e.g. `v1alpha1`)
|
||||
- Availability: committed to main kubernetes repo; appears in an official release; feature is
|
||||
disabled by default, but may be enabled by flag
|
||||
- Audience: developers and expert users interested in giving early feedback on features
|
||||
- Completeness: some API operations, CLI commands, or UI support may not be implemented; the API
|
||||
need not have had an *API review* (an intensive and targeted review of the API, on top of a normal
|
||||
code review)
|
||||
- Upgradeability: the object schema and semantics may change in a later software release, without
|
||||
any provision for preserving objects in an existing cluster;
|
||||
removing the upgradability concern allows developers to make rapid progress; in particular,
|
||||
API versions can increment faster than the minor release cadence and the developer need not
|
||||
maintain multiple versions; developers should still increment the API version when object schema
|
||||
or semantics change in an [incompatible way](#on-compatibility)
|
||||
- Cluster Reliability: because the feature is relatively new, and may lack complete end-to-end
|
||||
tests, enabling the feature via a flag might expose bugs with destabilize the cluster (e.g. a
|
||||
bug in a control loop might rapidly create excessive numbers of object, exhausting API storage).
|
||||
- Support: there is *no commitment* from the project to complete the feature; the feature may be
|
||||
dropped entirely in a later software release
|
||||
- Recommended Use Cases: only in short-lived testing clusters, due to complexity of upgradeability
|
||||
and lack of long-term support and lack of upgradability.
|
||||
- Beta level:
|
||||
- Object Versioning: API version name contains `beta` (e.g. `v2beta3`)
|
||||
- Availability: in official Kubernetes releases, and enabled by default
|
||||
- Audience: users interested in providing feedback on features
|
||||
- Completeness: all API operations, CLI commands, and UI support should be implemented; end-to-end
|
||||
tests complete; the API has had a thorough API review and is thought to be complete, though use
|
||||
during beta may frequently turn up API issues not thought of during review
|
||||
- Upgradeability: the object schema and semantics may change in a later software release; when
|
||||
this happens, an upgrade path will be documentedr; in some cases, objects will be automatically
|
||||
converted to the new version; in other cases, a manual upgrade may be necessary; a manual
|
||||
upgrade may require downtime for anything relying on the new feature, and may require
|
||||
manual conversion of objects to the new version; when manual conversion is necessary, the
|
||||
project will provide documentation on the process (for an example, see [v1 conversion
|
||||
tips](../api.md))
|
||||
- Cluster Reliability: since the feature has e2e tests, enabling the feature via a flag should not
|
||||
create new bugs in unrelated features; because the feature is new, it may have minor bugs
|
||||
- Support: the project commits to complete the feature, in some form, in a subsequent Stable
|
||||
version; typically this will happen within 3 months, but sometimes longer; releases should
|
||||
simultaneously support two consecutive versions (e.g. `v1beta1` and `v1beta2`; or `v1beta2` and
|
||||
`v1`) for at least one minor release cycle (typically 3 months) so that users have enough time
|
||||
to upgrade and migrate objects
|
||||
- Recommended Use Cases: in short-lived testing clusters; in production clusters as part of a
|
||||
short-lived evaluation of the feature in order to provide feedback
|
||||
- Stable level:
|
||||
- Object Versioning: API version `vX` where `X` is an integer (e.g. `v1`)
|
||||
- Availability: in official Kubernetes releases, and enabled by default
|
||||
- Audience: all users
|
||||
- Completeness: same as beta
|
||||
- Upgradeability: only [strictly compatible](#on-compatibility) changes allowed in subsequent
|
||||
software releases
|
||||
- Cluster Reliability: high
|
||||
- Support: API version will continue to be present for many subsequent software releases;
|
||||
- Recommended Use Cases: any
|
||||
|
||||
<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
|
||||
[]()
|
||||
|
||||
@ -241,9 +241,12 @@ value is `Always`.)
|
||||
|
||||
## Caveats
|
||||
|
||||
Job is part of the experimental API group, so it is not subject to the same compatibility
|
||||
guarantees as objects in the main API. It may not be enabled. Enable by setting
|
||||
`--runtime-config=experimental/v1alpha1` on the apiserver.
|
||||
Job objects are in the [`extensions` API Group](../api.md#api-groups). This API group may or
|
||||
may not be enabled on your cluster.
|
||||
|
||||
Job objects have [API version `v1beta1`](../api.md#api-versioning). Beta objects may
|
||||
undergo changes to their schema and/or semantics in future software releases, but
|
||||
similar functionality will be supported.
|
||||
|
||||
## Future work
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user