diff --git a/docs/admin/daemons.md b/docs/admin/daemons.md index 28e0d357f89..2877d65811c 100644 --- a/docs/admin/daemons.md +++ b/docs/admin/daemons.md @@ -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. + diff --git a/docs/api.md b/docs/api.md index 55aaa3e86e9..2a0586dbf4e 100644 --- a/docs/api.md +++ b/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 diff --git a/docs/devel/api_changes.md b/docs/devel/api_changes.md index 6b96b0e27e4..24430f267a6 100644 --- a/docs/devel/api_changes.md +++ b/docs/devel/api_changes.md @@ -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 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/devel/api_changes.md?pixel)]() diff --git a/docs/user-guide/jobs.md b/docs/user-guide/jobs.md index 5cf28fd0b36..6896e331244 100644 --- a/docs/user-guide/jobs.md +++ b/docs/user-guide/jobs.md @@ -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