{"action":"created","comment":{"url":"https://api.github.com/repos/kubernetes/kubernetes/pulls/comments/60986563","id":60986563,"diff_hunk":"@@ -0,0 +1,166 @@\n+<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->\n+\n+<!-- BEGIN STRIP_FOR_RELEASE -->\n+\n+<img src=\"http://kubernetes.io/img/warning.png\" alt=\"WARNING\"\n+     width=\"25\" height=\"25\">\n+<img src=\"http://kubernetes.io/img/warning.png\" alt=\"WARNING\"\n+     width=\"25\" height=\"25\">\n+<img src=\"http://kubernetes.io/img/warning.png\" alt=\"WARNING\"\n+     width=\"25\" height=\"25\">\n+<img src=\"http://kubernetes.io/img/warning.png\" alt=\"WARNING\"\n+     width=\"25\" height=\"25\">\n+<img src=\"http://kubernetes.io/img/warning.png\" alt=\"WARNING\"\n+     width=\"25\" height=\"25\">\n+\n+<h2>PLEASE NOTE: This document applies to the HEAD of the source tree</h2>\n+\n+If you are using a released version of Kubernetes, you should\n+refer to the docs that go with that version.\n+\n+Documentation for other releases can be found at\n+[releases.k8s.io](http://releases.k8s.io).\n+</strong>\n+--\n+\n+<!-- END STRIP_FOR_RELEASE -->\n+\n+<!-- END MUNGE: UNVERSIONED_WARNING -->\n+\n+# Resource Metrics API\n+\n+*This proposal is based on and supersedes [compute-resource-metrics-api.md](compute-resource-metrics-api.md).*\n+\n+This document describes API part of MVP version of Resource Metrics API effort in Kubernetes.\n+Once the agreement will be made the document will be extended to also cover implementation details.\n+The shape of the effort may be also a subject of changes once we will have more well-defined use cases.\n+\n+## Goal\n+\n+The goal for the effort is to provide resource usage metrics for pods and nodes through the API server.\n+This will be a stable, versioned API which core Kubernetes components can rely on.\n+In the first version only the well-defined use cases will be handled,\n+altough the API should be easily extensible for potential future use cases.\n+\n+## Main use cases\n+\n+This paragraph describes well-defined use cases which should be handled in the first version.\n+Use cases which are not listed below are out of the scope of MVP version of Resource Metrics API.\n+\n+#### Horizontal Pod Autoscaler\n+\n+HPA uses the latest value of cpu usage as an average aggregated across 1 minute\n+(the window may change in the future). The data for a given set of pods\n+(defined either by pod list or label selector) should be accesible in one request\n+due to performance issues.\n+\n+#### Scheduler\n+\n+Scheduler in order to schedule best-effort pods requires node level resource usage metrics\n+as an average aggreated across 1 minute (the window may change in the future).\n+The metrics should be available for all resources supported in the scheduler.\n+\n+## Other considered use cases\n+\n+This paragraph describes the other considered use cases and explains why they are out\n+of the scope MVP version.\n+\n+#### Custom metrics in HPA\n+\n+HPA requires the latest value of application level metrics.\n+\n+The effort is suspended and it's no clear whether application level metrics should be\n+available in API server so the use case initially won't be supported.\n+\n+#### Ubernetes\n+\n+In order to schedule best-effort pods in Ubernetes cluster the Ubernetes scheduler\n+requires the same metrics that the Kubernetes scheduler. To effort is in planning phase\n+so it's out the scope of Resource Metrics API effort however the support should be sufficient\n+once Kubernetes scheduler is supported.\n+\n+#### kubectl top\n+\n+This feature is not yet specified/implemented although it seems reasonable to support the following options:\n+- ```kubectl top node <id>``` - list all pods running on the given node accompanied with theirs cpu/mem usage\n+- ```kubectl top pod <id>``` - print cpu usage stats for the given pod\n+- ```kubectl top pod --selector=<label-query>``` - list all pods defined by the label query accompanied with theirs cpu/mem usage\n+\n+Since there are not hard requirements in this case it will be not supported initally in the API although\n+it will be probably possible to provide a reasonable implementation of the feature anyway.\n+\n+#### Kubernetes dashboard\n+\n+[Kubernetes dashboard](https://github.com/kubernetes/dashboard) in order to draw graps requires resource usage\n+in timeseries format from relatively long period of time. The aggreations should be also possible on various levels\n+including replication controllers, deployments, services, etc.\n+\n+Since the use case is complicated it will not be supported initally in the API and they will query Heapster\n+directly using some custom API there.\n+\n+## Proposed API\n+\n+Initially the metrics API will be in a separate [API group](api-group.md) called ```metrics```.\n+Later if we decided to have Node and Pod in different API groups also\n+NodeMetrics and PodMetrics should be in different API groups.\n+\n+#### Schema\n+\n+The proposed schema is as follow. Each top-level object has `TypeMeta` and `ObjectMeta` fields\n+to be compatible with Kubernetes API standards.\n+\n+```go\n+type NodeMetrics struct {\n+  unversioned.TypeMeta\n+  ObjectMeta\n+\n+  Timestamp unversioned.Time\n+  Window    unversioned.Duration\n+  \n+  Usage map[ResourceType]Resource.Quantity\n+}\n+\n+type PodMetrics struct {\n+  unversioned.TypeMeta\n+  ObjectMeta\n+\n+  Timestamp unversioned.Time\n+  Window    unversioned.Duration\n+\n+  Containers []ContainerMetrics\n+}","path":"docs/proposals/resource-metrics-api.md","position":139,"original_position":131,"commit_id":"7244865566a030c0e38019d258dc44baee9a4ace","original_commit_id":"9f124139f4c4e9fe149075b1bef55824c7a2092f","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":"If we later add volume resources, then it pod metrics would be sum of container and volume metrics for the pod.  So, if we plan to add volume later, it might be better to add Pod metrics here, so that when we add volume accounting, users who use Pod metrics immediately see this new usage. OTOH, it might be breaking for users to change the Pod accounting.  So maybe better to not add it until we are sure what it will contain.\r\n\r\n\r\n\r\nAlso, if we later add 95th as an aggregation, the user cannot compute this herself.  The kubelet has to do that.  So, if 95th, or other non-user-computable aggregations are needed, then I agree we will need a PodMetrics.  However, I am fine with leaving those out of the MVP until we have a stronger use case.","created_at":"2016-04-25T20:50:33Z","updated_at":"2016-04-25T20:50:33Z","html_url":"https://github.com/kubernetes/kubernetes/pull/24253#discussion_r60986563","pull_request_url":"https://api.github.com/repos/kubernetes/kubernetes/pulls/24253","_links":{"self":{"href":"https://api.github.com/repos/kubernetes/kubernetes/pulls/comments/60986563"},"html":{"href":"https://github.com/kubernetes/kubernetes/pull/24253#discussion_r60986563"},"pull_request":{"href":"https://api.github.com/repos/kubernetes/kubernetes/pulls/24253"}}},"pull_request":{"url":"https://api.github.com/repos/kubernetes/kubernetes/pulls/24253","id":66504856,"html_url":"https://github.com/kubernetes/kubernetes/pull/24253","diff_url":"https://github.com/kubernetes/kubernetes/pull/24253.diff","patch_url":"https://github.com/kubernetes/kubernetes/pull/24253.patch","issue_url":"https://api.github.com/repos/kubernetes/kubernetes/issues/24253","number":24253,"state":"open","locked":false,"title":"Resource Metrics API proposal","user":{"login":"piosz","id":10819974,"avatar_url":"https://avatars.githubusercontent.com/u/10819974?v=3","gravatar_id":"","url":"https://api.github.com/users/piosz","html_url":"https://github.com/piosz","followers_url":"https://api.github.com/users/piosz/followers","following_url":"https://api.github.com/users/piosz/following{/other_user}","gists_url":"https://api.github.com/users/piosz/gists{/gist_id}","starred_url":"https://api.github.com/users/piosz/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/piosz/subscriptions","organizations_url":"https://api.github.com/users/piosz/orgs","repos_url":"https://api.github.com/users/piosz/repos","events_url":"https://api.github.com/users/piosz/events{/privacy}","received_events_url":"https://api.github.com/users/piosz/received_events","type":"User","site_admin":false},"body":"ref #23376\r\n\r\nThe proposal should be signed off by:\r\n- [ ] @davidopp\r\n- [ ] @erictune\r\n\r\nThe scope of proposal is just API not the implementation.\r\n\r\nI'm happy to change any name in the API definition.","created_at":"2016-04-14T15:30:59Z","updated_at":"2016-04-25T20:50:33Z","closed_at":null,"merged_at":null,"merge_commit_sha":"a8fbcc234d73d906ed418b6804083cb5c634fdf3","assignee":{"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},"milestone":null,"commits_url":"https://api.github.com/repos/kubernetes/kubernetes/pulls/24253/commits","review_comments_url":"https://api.github.com/repos/kubernetes/kubernetes/pulls/24253/comments","review_comment_url":"https://api.github.com/repos/kubernetes/kubernetes/pulls/comments{/number}","comments_url":"https://api.github.com/repos/kubernetes/kubernetes/issues/24253/comments","statuses_url":"https://api.github.com/repos/kubernetes/kubernetes/statuses/7244865566a030c0e38019d258dc44baee9a4ace","head":{"label":"piosz:master-metrics-proposal","ref":"master-metrics-proposal","sha":"7244865566a030c0e38019d258dc44baee9a4ace","user":{"login":"piosz","id":10819974,"avatar_url":"https://avatars.githubusercontent.com/u/10819974?v=3","gravatar_id":"","url":"https://api.github.com/users/piosz","html_url":"https://github.com/piosz","followers_url":"https://api.github.com/users/piosz/followers","following_url":"https://api.github.com/users/piosz/following{/other_user}","gists_url":"https://api.github.com/users/piosz/gists{/gist_id}","starred_url":"https://api.github.com/users/piosz/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/piosz/subscriptions","organizations_url":"https://api.github.com/users/piosz/orgs","repos_url":"https://api.github.com/users/piosz/repos","events_url":"https://api.github.com/users/piosz/events{/privacy}","received_events_url":"https://api.github.com/users/piosz/received_events","type":"User","site_admin":false},"repo":{"id":30922782,"name":"kubernetes","full_name":"piosz/kubernetes","owner":{"login":"piosz","id":10819974,"avatar_url":"https://avatars.githubusercontent.com/u/10819974?v=3","gravatar_id":"","url":"https://api.github.com/users/piosz","html_url":"https://github.com/piosz","followers_url":"https://api.github.com/users/piosz/followers","following_url":"https://api.github.com/users/piosz/following{/other_user}","gists_url":"https://api.github.com/users/piosz/gists{/gist_id}","starred_url":"https://api.github.com/users/piosz/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/piosz/subscriptions","organizations_url":"https://api.github.com/users/piosz/orgs","repos_url":"https://api.github.com/users/piosz/repos","events_url":"https://api.github.com/users/piosz/events{/privacy}","received_events_url":"https://api.github.com/users/piosz/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/piosz/kubernetes","description":"Container Cluster Manager","fork":true,"url":"https://api.github.com/repos/piosz/kubernetes","forks_url":"https://api.github.com/repos/piosz/kubernetes/forks","keys_url":"https://api.github.com/repos/piosz/kubernetes/keys{/key_id}","collaborators_url":"https://api.github.com/repos/piosz/kubernetes/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/piosz/kubernetes/teams","hooks_url":"https://api.github.com/repos/piosz/kubernetes/hooks","issue_events_url":"https://api.github.com/repos/piosz/kubernetes/issues/events{/number}","events_url":"https://api.github.com/repos/piosz/kubernetes/events","assignees_url":"https://api.github.com/repos/piosz/kubernetes/assignees{/user}","branches_url":"https://api.github.com/repos/piosz/kubernetes/branches{/branch}","tags_url":"https://api.github.com/repos/piosz/kubernetes/tags","blobs_url":"https://api.github.com/repos/piosz/kubernetes/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/piosz/kubernetes/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/piosz/kubernetes/git/refs{/sha}","trees_url":"https://api.github.com/repos/piosz/kubernetes/git/trees{/sha}","statuses_url":"https://api.github.com/repos/piosz/kubernetes/statuses/{sha}","languages_url":"https://api.github.com/repos/piosz/kubernetes/languages","stargazers_url":"https://api.github.com/repos/piosz/kubernetes/stargazers","contributors_url":"https://api.github.com/repos/piosz/kubernetes/contributors","subscribers_url":"https://api.github.com/repos/piosz/kubernetes/subscribers","subscription_url":"https://api.github.com/repos/piosz/kubernetes/subscription","commits_url":"https://api.github.com/repos/piosz/kubernetes/commits{/sha}","git_commits_url":"https://api.github.com/repos/piosz/kubernetes/git/commits{/sha}","comments_url":"https://api.github.com/repos/piosz/kubernetes/comments{/number}","issue_comment_url":"https://api.github.com/repos/piosz/kubernetes/issues/comments{/number}","contents_url":"https://api.github.com/repos/piosz/kubernetes/contents/{+path}","compare_url":"https://api.github.com/repos/piosz/kubernetes/compare/{base}...{head}","merges_url":"https://api.github.com/repos/piosz/kubernetes/merges","archive_url":"https://api.github.com/repos/piosz/kubernetes/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/piosz/kubernetes/downloads","issues_url":"https://api.github.com/repos/piosz/kubernetes/issues{/number}","pulls_url":"https://api.github.com/repos/piosz/kubernetes/pulls{/number}","milestones_url":"https://api.github.com/repos/piosz/kubernetes/milestones{/number}","notifications_url":"https://api.github.com/repos/piosz/kubernetes/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/piosz/kubernetes/labels{/name}","releases_url":"https://api.github.com/repos/piosz/kubernetes/releases{/id}","deployments_url":"https://api.github.com/repos/piosz/kubernetes/deployments","created_at":"2015-02-17T15:23:02Z","updated_at":"2016-01-12T14:51:54Z","pushed_at":"2016-04-22T14:04:45Z","git_url":"git://github.com/piosz/kubernetes.git","ssh_url":"git@github.com:piosz/kubernetes.git","clone_url":"https://github.com/piosz/kubernetes.git","svn_url":"https://github.com/piosz/kubernetes","homepage":"http://kubernetes.io","size":177074,"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":"66dc446ba0e4b51f4118233e67220ef6b94f92cb","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}","deployments_url":"https://api.github.com/repos/kubernetes/kubernetes/deployments","created_at":"2014-06-06T22:56:04Z","updated_at":"2016-04-25T18:42:18Z","pushed_at":"2016-04-25T20:42:57Z","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":386521,"stargazers_count":14057,"watchers_count":14057,"language":"Go","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":4168,"mirror_url":null,"open_issues_count":3479,"forks":4168,"open_issues":3479,"watchers":14057,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/kubernetes/kubernetes/pulls/24253"},"html":{"href":"https://github.com/kubernetes/kubernetes/pull/24253"},"issue":{"href":"https://api.github.com/repos/kubernetes/kubernetes/issues/24253"},"comments":{"href":"https://api.github.com/repos/kubernetes/kubernetes/issues/24253/comments"},"review_comments":{"href":"https://api.github.com/repos/kubernetes/kubernetes/pulls/24253/comments"},"review_comment":{"href":"https://api.github.com/repos/kubernetes/kubernetes/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/kubernetes/kubernetes/pulls/24253/commits"},"statuses":{"href":"https://api.github.com/repos/kubernetes/kubernetes/statuses/7244865566a030c0e38019d258dc44baee9a4ace"}}}}