Doc: apigroups, alpha, beta, experimental/v1alpha1

nikhiljindal · Oct 14, 2015 · ca6c950 · ca6c950
1 parent 11c735c
commit ca6c950
Show file tree

Hide file tree

Showing 4 changed files with 130 additions and 8 deletions.
diff --git 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.
+
 
 
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->

diff --git 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
@@ -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 -->
 [![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
@@ -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