{"action":"created","comment":{"url":"https://api.github.com/repos/kubernetes/kubernetes/pulls/comments/41650071","id":41650071,"diff_hunk":"@@ -53,13 +53,79 @@ In our experience, any system that is successful needs to grow and change as new\n \n What constitutes a compatible change and how to change the API are detailed by the [API change document](devel/api_changes.md).\n \n+\n+## API groups\n+\n+To make it easier to extend the Kubernetes API, we are in the process of implementing *API groups*.\n+The API group is specified in a REST path and in the `apiVersion` field of a serialized object.\n+\n+Currently there are two API groups in use:\n+\n+1. the \"core\" group, which is at REST path `/api/v1` and is not specified as part of the `apiVersion` field, e.g.\n+   `apiVersion: v1`.\n+1. the \"experimental\" group, which is at REST path `/apis/experimental/$VERSION`, and which uses\n+  `apiVersion: experimental/$VERSION`, where currently `apiVersion: experimental/v1alpha1`.\n+  The name `experimental` implies that API groups themselves are currently under development.  The actual\n+  stability of the version of objects within that group is determined by its [API\n+  version](#api-versioning)\n+\n+In the future we expect that there will be more API groups, all at REST path `/apis/$API_GROUP` and\n+using `apiVersion: $API_GROUP/$VERSION`.  We expect that there will be a way for third parties to\n+create their own API groups, and to avoid naming collisions.\n+\n+Not all kubernetes clusters will support all API groups.  However, we intend that if an API server\n+supports a group, it supports all the Kinds in the group, and all of them at the same version(s).\n+\n ## API versioning\n \n-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.\n+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`.\n \n 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.\n \n-The [API and release versioning proposal](design/versioning.md) describes the current thinking on the API version evolution process.\n+Note that API versioning and Software versioning are only indirectly related.  The [API and release\n+versioning proposal](design/versioning.md) describes the current thinking on the API version\n+evolution process.\n+\n+Different API versions imply different levels of support and stability:\n+ - Alpha level:\n+   - The version names contain `alpha` (e.g. `v1alpha1`).\n+   - The object schema may change significantly in the next API version.\n+   - We may not give any tools or instructions for migrating your objects from one version to the next\n+     &emdash; you may have to delete, rewrite, and re-create your objects when you upgrade your cluster to the next\n+     version.\n+   - Support for object/feature may be dropped entirely in next software release.\n+   - Do not count on overlapping support for \"previous\" and \"current\" version; supported version\n+     may change abruptly on a new software release.\n+   - Flag changes may be needed to enable alpha versions.\n+   - Hosted clusters (e.g. GKE) may not support alpha versions.\n+   - Code that implements alpha objects may be less well tested.  Enabling alpha support may active bugs","path":"docs/api.md","position":51,"original_position":51,"commit_id":"415b4f34b0e04b84fe9e40dcfc1a65dfb40462c5","original_commit_id":"415b4f34b0e04b84fe9e40dcfc1a65dfb40462c5","user":{"login":"quinton-hoole","id":10390785,"avatar_url":"https://avatars.githubusercontent.com/u/10390785?v=3","gravatar_id":"","url":"https://api.github.com/users/quinton-hoole","html_url":"https://github.com/quinton-hoole","followers_url":"https://api.github.com/users/quinton-hoole/followers","following_url":"https://api.github.com/users/quinton-hoole/following{/other_user}","gists_url":"https://api.github.com/users/quinton-hoole/gists{/gist_id}","starred_url":"https://api.github.com/users/quinton-hoole/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/quinton-hoole/subscriptions","organizations_url":"https://api.github.com/users/quinton-hoole/orgs","repos_url":"https://api.github.com/users/quinton-hoole/repos","events_url":"https://api.github.com/users/quinton-hoole/events{/privacy}","received_events_url":"https://api.github.com/users/quinton-hoole/received_events","type":"User","site_admin":false},"body":"I think 'activate' is what you meant, which is slightly better then 'trigger', IMO.","created_at":"2015-10-09T16:32:28Z","updated_at":"2015-10-09T16:32:28Z","html_url":"https://github.com/kubernetes/kubernetes/pull/15339#discussion_r41650071","pull_request_url":"https://api.github.com/repos/kubernetes/kubernetes/pulls/15339","_links":{"self":{"href":"https://api.github.com/repos/kubernetes/kubernetes/pulls/comments/41650071"},"html":{"href":"https://github.com/kubernetes/kubernetes/pull/15339#discussion_r41650071"},"pull_request":{"href":"https://api.github.com/repos/kubernetes/kubernetes/pulls/15339"}}},"pull_request":{"url":"https://api.github.com/repos/kubernetes/kubernetes/pulls/15339","id":47221314,"html_url":"https://github.com/kubernetes/kubernetes/pull/15339","diff_url":"https://github.com/kubernetes/kubernetes/pull/15339.diff","patch_url":"https://github.com/kubernetes/kubernetes/pull/15339.patch","issue_url":"https://api.github.com/repos/kubernetes/kubernetes/issues/15339","number":15339,"state":"open","locked":false,"title":"Doc: apigroups, alpha, beta, experimental/v1alpha1","user":{"login":"erictune","id":8105590,"avatar_url":"https://avatars.githubusercontent.com/u/8105590?v=3","gravatar_id":"","url":"https://api.github.com/users/erictune","html_url":"https://github.com/erictune","followers_url":"https://api.github.com/users/erictune/followers","following_url":"https://api.github.com/users/erictune/following{/other_user}","gists_url":"https://api.github.com/users/erictune/gists{/gist_id}","starred_url":"https://api.github.com/users/erictune/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/erictune/subscriptions","organizations_url":"https://api.github.com/users/erictune/orgs","repos_url":"https://api.github.com/users/erictune/repos","events_url":"https://api.github.com/users/erictune/events{/privacy}","received_events_url":"https://api.github.com/users/erictune/received_events","type":"User","site_admin":false},"body":"My attempt to summarize ongoing discussions about versions and stability for a user audience.","created_at":"2015-10-09T00:02:31Z","updated_at":"2015-10-09T16:32:28Z","closed_at":null,"merged_at":null,"merge_commit_sha":"ac6744c0c340722e84bccca52680d9898e4aedde","assignee":{"login":"bgrant0607","id":7725777,"avatar_url":"https://avatars.githubusercontent.com/u/7725777?v=3","gravatar_id":"","url":"https://api.github.com/users/bgrant0607","html_url":"https://github.com/bgrant0607","followers_url":"https://api.github.com/users/bgrant0607/followers","following_url":"https://api.github.com/users/bgrant0607/following{/other_user}","gists_url":"https://api.github.com/users/bgrant0607/gists{/gist_id}","starred_url":"https://api.github.com/users/bgrant0607/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bgrant0607/subscriptions","organizations_url":"https://api.github.com/users/bgrant0607/orgs","repos_url":"https://api.github.com/users/bgrant0607/repos","events_url":"https://api.github.com/users/bgrant0607/events{/privacy}","received_events_url":"https://api.github.com/users/bgrant0607/received_events","type":"User","site_admin":false},"milestone":null,"commits_url":"https://api.github.com/repos/kubernetes/kubernetes/pulls/15339/commits","review_comments_url":"https://api.github.com/repos/kubernetes/kubernetes/pulls/15339/comments","review_comment_url":"https://api.github.com/repos/kubernetes/kubernetes/pulls/comments{/number}","comments_url":"https://api.github.com/repos/kubernetes/kubernetes/issues/15339/comments","statuses_url":"https://api.github.com/repos/kubernetes/kubernetes/statuses/415b4f34b0e04b84fe9e40dcfc1a65dfb40462c5","head":{"label":"erictune:exp-api","ref":"exp-api","sha":"415b4f34b0e04b84fe9e40dcfc1a65dfb40462c5","user":{"login":"erictune","id":8105590,"avatar_url":"https://avatars.githubusercontent.com/u/8105590?v=3","gravatar_id":"","url":"https://api.github.com/users/erictune","html_url":"https://github.com/erictune","followers_url":"https://api.github.com/users/erictune/followers","following_url":"https://api.github.com/users/erictune/following{/other_user}","gists_url":"https://api.github.com/users/erictune/gists{/gist_id}","starred_url":"https://api.github.com/users/erictune/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/erictune/subscriptions","organizations_url":"https://api.github.com/users/erictune/orgs","repos_url":"https://api.github.com/users/erictune/repos","events_url":"https://api.github.com/users/erictune/events{/privacy}","received_events_url":"https://api.github.com/users/erictune/received_events","type":"User","site_admin":false},"repo":{"id":21629362,"name":"kubernetes","full_name":"erictune/kubernetes","owner":{"login":"erictune","id":8105590,"avatar_url":"https://avatars.githubusercontent.com/u/8105590?v=3","gravatar_id":"","url":"https://api.github.com/users/erictune","html_url":"https://github.com/erictune","followers_url":"https://api.github.com/users/erictune/followers","following_url":"https://api.github.com/users/erictune/following{/other_user}","gists_url":"https://api.github.com/users/erictune/gists{/gist_id}","starred_url":"https://api.github.com/users/erictune/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/erictune/subscriptions","organizations_url":"https://api.github.com/users/erictune/orgs","repos_url":"https://api.github.com/users/erictune/repos","events_url":"https://api.github.com/users/erictune/events{/privacy}","received_events_url":"https://api.github.com/users/erictune/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/erictune/kubernetes","description":"Container Cluster Manager","fork":true,"url":"https://api.github.com/repos/erictune/kubernetes","forks_url":"https://api.github.com/repos/erictune/kubernetes/forks","keys_url":"https://api.github.com/repos/erictune/kubernetes/keys{/key_id}","collaborators_url":"https://api.github.com/repos/erictune/kubernetes/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/erictune/kubernetes/teams","hooks_url":"https://api.github.com/repos/erictune/kubernetes/hooks","issue_events_url":"https://api.github.com/repos/erictune/kubernetes/issues/events{/number}","events_url":"https://api.github.com/repos/erictune/kubernetes/events","assignees_url":"https://api.github.com/repos/erictune/kubernetes/assignees{/user}","branches_url":"https://api.github.com/repos/erictune/kubernetes/branches{/branch}","tags_url":"https://api.github.com/repos/erictune/kubernetes/tags","blobs_url":"https://api.github.com/repos/erictune/kubernetes/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/erictune/kubernetes/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/erictune/kubernetes/git/refs{/sha}","trees_url":"https://api.github.com/repos/erictune/kubernetes/git/trees{/sha}","statuses_url":"https://api.github.com/repos/erictune/kubernetes/statuses/{sha}","languages_url":"https://api.github.com/repos/erictune/kubernetes/languages","stargazers_url":"https://api.github.com/repos/erictune/kubernetes/stargazers","contributors_url":"https://api.github.com/repos/erictune/kubernetes/contributors","subscribers_url":"https://api.github.com/repos/erictune/kubernetes/subscribers","subscription_url":"https://api.github.com/repos/erictune/kubernetes/subscription","commits_url":"https://api.github.com/repos/erictune/kubernetes/commits{/sha}","git_commits_url":"https://api.github.com/repos/erictune/kubernetes/git/commits{/sha}","comments_url":"https://api.github.com/repos/erictune/kubernetes/comments{/number}","issue_comment_url":"https://api.github.com/repos/erictune/kubernetes/issues/comments{/number}","contents_url":"https://api.github.com/repos/erictune/kubernetes/contents/{+path}","compare_url":"https://api.github.com/repos/erictune/kubernetes/compare/{base}...{head}","merges_url":"https://api.github.com/repos/erictune/kubernetes/merges","archive_url":"https://api.github.com/repos/erictune/kubernetes/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/erictune/kubernetes/downloads","issues_url":"https://api.github.com/repos/erictune/kubernetes/issues{/number}","pulls_url":"https://api.github.com/repos/erictune/kubernetes/pulls{/number}","milestones_url":"https://api.github.com/repos/erictune/kubernetes/milestones{/number}","notifications_url":"https://api.github.com/repos/erictune/kubernetes/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/erictune/kubernetes/labels{/name}","releases_url":"https://api.github.com/repos/erictune/kubernetes/releases{/id}","created_at":"2014-07-08T21:00:59Z","updated_at":"2015-05-01T23:13:23Z","pushed_at":"2015-10-09T00:19:26Z","git_url":"git://github.com/erictune/kubernetes.git","ssh_url":"git@github.com:erictune/kubernetes.git","clone_url":"https://github.com/erictune/kubernetes.git","svn_url":"https://github.com/erictune/kubernetes","homepage":null,"size":113321,"stargazers_count":0,"watchers_count":0,"language":"Go","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"kubernetes:master","ref":"master","sha":"86fdc3f85c3bfa9cc848d996d909f81d894e49bf","user":{"login":"kubernetes","id":13629408,"avatar_url":"https://avatars.githubusercontent.com/u/13629408?v=3","gravatar_id":"","url":"https://api.github.com/users/kubernetes","html_url":"https://github.com/kubernetes","followers_url":"https://api.github.com/users/kubernetes/followers","following_url":"https://api.github.com/users/kubernetes/following{/other_user}","gists_url":"https://api.github.com/users/kubernetes/gists{/gist_id}","starred_url":"https://api.github.com/users/kubernetes/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kubernetes/subscriptions","organizations_url":"https://api.github.com/users/kubernetes/orgs","repos_url":"https://api.github.com/users/kubernetes/repos","events_url":"https://api.github.com/users/kubernetes/events{/privacy}","received_events_url":"https://api.github.com/users/kubernetes/received_events","type":"Organization","site_admin":false},"repo":{"id":20580498,"name":"kubernetes","full_name":"kubernetes/kubernetes","owner":{"login":"kubernetes","id":13629408,"avatar_url":"https://avatars.githubusercontent.com/u/13629408?v=3","gravatar_id":"","url":"https://api.github.com/users/kubernetes","html_url":"https://github.com/kubernetes","followers_url":"https://api.github.com/users/kubernetes/followers","following_url":"https://api.github.com/users/kubernetes/following{/other_user}","gists_url":"https://api.github.com/users/kubernetes/gists{/gist_id}","starred_url":"https://api.github.com/users/kubernetes/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kubernetes/subscriptions","organizations_url":"https://api.github.com/users/kubernetes/orgs","repos_url":"https://api.github.com/users/kubernetes/repos","events_url":"https://api.github.com/users/kubernetes/events{/privacy}","received_events_url":"https://api.github.com/users/kubernetes/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/kubernetes/kubernetes","description":"Container Cluster Manager from Google","fork":false,"url":"https://api.github.com/repos/kubernetes/kubernetes","forks_url":"https://api.github.com/repos/kubernetes/kubernetes/forks","keys_url":"https://api.github.com/repos/kubernetes/kubernetes/keys{/key_id}","collaborators_url":"https://api.github.com/repos/kubernetes/kubernetes/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/kubernetes/kubernetes/teams","hooks_url":"https://api.github.com/repos/kubernetes/kubernetes/hooks","issue_events_url":"https://api.github.com/repos/kubernetes/kubernetes/issues/events{/number}","events_url":"https://api.github.com/repos/kubernetes/kubernetes/events","assignees_url":"https://api.github.com/repos/kubernetes/kubernetes/assignees{/user}","branches_url":"https://api.github.com/repos/kubernetes/kubernetes/branches{/branch}","tags_url":"https://api.github.com/repos/kubernetes/kubernetes/tags","blobs_url":"https://api.github.com/repos/kubernetes/kubernetes/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/kubernetes/kubernetes/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/kubernetes/kubernetes/git/refs{/sha}","trees_url":"https://api.github.com/repos/kubernetes/kubernetes/git/trees{/sha}","statuses_url":"https://api.github.com/repos/kubernetes/kubernetes/statuses/{sha}","languages_url":"https://api.github.com/repos/kubernetes/kubernetes/languages","stargazers_url":"https://api.github.com/repos/kubernetes/kubernetes/stargazers","contributors_url":"https://api.github.com/repos/kubernetes/kubernetes/contributors","subscribers_url":"https://api.github.com/repos/kubernetes/kubernetes/subscribers","subscription_url":"https://api.github.com/repos/kubernetes/kubernetes/subscription","commits_url":"https://api.github.com/repos/kubernetes/kubernetes/commits{/sha}","git_commits_url":"https://api.github.com/repos/kubernetes/kubernetes/git/commits{/sha}","comments_url":"https://api.github.com/repos/kubernetes/kubernetes/comments{/number}","issue_comment_url":"https://api.github.com/repos/kubernetes/kubernetes/issues/comments{/number}","contents_url":"https://api.github.com/repos/kubernetes/kubernetes/contents/{+path}","compare_url":"https://api.github.com/repos/kubernetes/kubernetes/compare/{base}...{head}","merges_url":"https://api.github.com/repos/kubernetes/kubernetes/merges","archive_url":"https://api.github.com/repos/kubernetes/kubernetes/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/kubernetes/kubernetes/downloads","issues_url":"https://api.github.com/repos/kubernetes/kubernetes/issues{/number}","pulls_url":"https://api.github.com/repos/kubernetes/kubernetes/pulls{/number}","milestones_url":"https://api.github.com/repos/kubernetes/kubernetes/milestones{/number}","notifications_url":"https://api.github.com/repos/kubernetes/kubernetes/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/kubernetes/kubernetes/labels{/name}","releases_url":"https://api.github.com/repos/kubernetes/kubernetes/releases{/id}","created_at":"2014-06-06T22:56:04Z","updated_at":"2015-10-09T15:57:08Z","pushed_at":"2015-10-09T16:23:52Z","git_url":"git://github.com/kubernetes/kubernetes.git","ssh_url":"git@github.com:kubernetes/kubernetes.git","clone_url":"https://github.com/kubernetes/kubernetes.git","svn_url":"https://github.com/kubernetes/kubernetes","homepage":"http://kubernetes.io","size":447911,"stargazers_count":10617,"watchers_count":10617,"language":"Go","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":2678,"mirror_url":null,"open_issues_count":1996,"forks":2678,"open_issues":1996,"watchers":10617,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/kubernetes/kubernetes/pulls/15339"},"html":{"href":"https://github.com/kubernetes/kubernetes/pull/15339"},"issue":{"href":"https://api.github.com/repos/kubernetes/kubernetes/issues/15339"},"comments":{"href":"https://api.github.com/repos/kubernetes/kubernetes/issues/15339/comments"},"review_comments":{"href":"https://api.github.com/repos/kubernetes/kubernetes/pulls/15339/comments"},"review_comment":{"href":"https://api.github.com/repos/kubernetes/kubernetes/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/kubernetes/kubernetes/pulls/15339/commits"},"statuses":{"href":"https://api.github.com/repos/kubernetes/kubernetes/statuses/415b4f34b0e04b84fe9e40dcfc1a65dfb40462c5"}}}}