Documentation for opaque integer resources (alpha feature in 1.5) #1783

ConnorDoyle · 2016-11-24T00:14:31Z

Feature issue: 76
Implementation PR: 31652

cc @kubernetes/sig-scheduling @timothysc

Also touches multiple instances of the API object path for pod containers. Can break this up into a separate commit/PR on request.

This change is

davidopp · 2016-11-24T08:11:07Z

docs/user-guide/compute-resources.md

+Second, users must request the opaque resource in pods.
+
+To advertise a new opaque integer resource, the cluster operator should
+submit a `PATCH` HTTP request to the API server to specify the available


you should mention specifically that you patch the capacity, even though the next sentence mentions it.

davidopp · 2016-11-24T08:11:29Z

docs/user-guide/compute-resources.md

+quantity on a node in the cluster. After this operation, the node's
+`status.capacity` will include a new resource. The `status.allocatable`
+field is updated automatically with the new resource asychronously by
+the Kubelet.


mention that it can be used in scheduling only once this happens.

davidopp · 2016-11-24T08:12:24Z

LGTM

I had two minor nits but since the doc deadline is very soon I think it's OK as is and you can fix that later.

ConnorDoyle · 2016-11-24T09:05:00Z

I can update this over the long weekend or submit a follow-up. Either way, will fix the comments. Thanks for the quick review.

…

On Nov 24, 2016, at 00:12, David Oppenheimer ***@***.***> wrote: LGTM I had two minor nits but since the doc deadline is very soon I think it's OK as is and you can fix that later. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or mute the thread.

ConnorDoyle · 2016-11-28T15:31:54Z

@davidopp addressed your comments (amended commit)

ConnorDoyle · 2016-11-28T15:40:02Z

cc @kubernetes/docs

hongchaodeng · 2016-11-28T18:59:52Z

docs/user-guide/compute-resources.md

@@ -269,6 +269,86 @@ LastState: map[terminated:map[exitCode:137 reason:OOM Killed startedAt:2015-07-0

 We can see that this container was terminated because `reason:OOM Killed`, where *OOM* stands for Out Of Memory.

+## Alpha Features


This isn't rendered correctly, at least from my browser:

@ConnorDoyle @davidopp Did you also see the same?

Yup I see it this way too.

Are you using the GHFM preview or viewing the netify rendered output (see https://deploy-preview-1783--kubernetes-io-vnext-staging.netlify.com/docs/user-guide/compute-resources/)

I see the same issue in github as others.

@aveshagarwal please read my comment. Github markdown preview and jekyll aren't the same. Also, the point at which the rendering is broken isn't part of the change set.

Current master looks the same when rendered with vanilla Github markdown preview (see https://github.com/kubernetes/kubernetes.github.io/blob/7112d4c53d8a6e34f3a43c8f4449403617f091e7/docs/user-guide/compute-resources.md#my-container-is-terminated)

timothysc · 2016-11-28T20:44:01Z

docs/user-guide/compute-resources.md

@@ -269,6 +269,86 @@ LastState: map[terminated:map[exitCode:137 reason:OOM Killed startedAt:2015-07-0

 We can see that this container was terminated because `reason:OOM Killed`, where *OOM* stands for Out Of Memory.

+## Alpha Features
+
+### Opaque Integer Resources (Alpha Feature)


Seems weird to add "Alpha Feature" to the title when it's under the TOC.

Was following precedent set here: http://kubernetes.io/docs/user-guide/node-selection#node-affinity-alpha-feature

One or the other. Either don't have an Alpha Features heading (and mark features Alpha), or don't include "Alpha" in each feature's individual heading.

Also, avoid nesting headings directly under one another; that's indicative of structural problems. If you have a header with nothing under it but another header, one or the other is not necessary.

timothysc · 2016-11-28T21:04:57Z

docs/user-guide/compute-resources.md

+
+The HTTP request below advertises 5 "foo" resources on node `k8s-node-1`.
+
+_NOTE: `~1` is the encoding for the character `/` in the patch path._


This is going to be confusing to users.

Which part, this doc or the way slash is encoded in JSON-pointer?

slash encoding.

Would a link to the JSON-pointer RFC help?

You'll never hear me say 'no' on the argument of add verbosity for clarity.

OK, will add some more info about it (fact that JSON-patch makes use of JSON-pointer may be fairly niche)

devin-donnelly · 2016-12-01T21:13:58Z

docs/user-guide/compute-resources.md

@@ -269,6 +269,86 @@ LastState: map[terminated:map[exitCode:137 reason:OOM Killed startedAt:2015-07-0

 We can see that this container was terminated because `reason:OOM Killed`, where *OOM* stands for Out Of Memory.

+## Alpha Features
+
+### Opaque Integer Resources (Alpha Feature)


One or the other. Either don't have an Alpha Features heading (and mark features Alpha), or don't include "Alpha" in each feature's individual heading.

Also, avoid nesting headings directly under one another; that's indicative of structural problems. If you have a header with nothing under it but another header, one or the other is not necessary.

devin-donnelly · 2016-12-01T21:14:16Z

docs/user-guide/compute-resources.md

+
+### Opaque Integer Resources (Alpha Feature)
+
+Opaque integer resources were introduced as an alpha feature in Kubernetes


Stick with present tense; no past or future.

"Kubernetes version 1.5 introduces Opaque integer resources. Opaque integer resources allow cluster operators to advertise new node-level resources that would be otherwise unknown to the system."

Move the last sentence: "So far only resource accounting is implemented" into a note about the Alpha state underneath the first paragraph, like so:

"Note: Opaque integer resources are Alpha in Kubernetes version 1.5. Only resource accounting is implemented; node-level isolation is still under active development."

ConnorDoyle · 2016-12-02T18:38:35Z

@devin-donnelly thanks for the review comments, please take another look.

devin-donnelly · 2016-12-02T19:08:46Z

Awesome, thanks. I can go ahead and merge this for 1.5.

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Nov 24, 2016

k8s-github-robot assigned thockin Nov 24, 2016

davidopp assigned davidopp and unassigned thockin Nov 24, 2016

davidopp reviewed Nov 24, 2016

View reviewed changes

davidopp added the Tech Review LGTM label Nov 24, 2016

ConnorDoyle mentioned this pull request Nov 28, 2016

Opaque integer resources kubernetes/enhancements#76

Closed

22 tasks

hongchaodeng reviewed Nov 28, 2016

View reviewed changes

timothysc reviewed Nov 28, 2016

View reviewed changes

devin-donnelly suggested changes Dec 1, 2016

View reviewed changes

devin-donnelly added the Docs Review: Open Issues label Dec 1, 2016

Doc for alpha opaque integer resources.

9430805

devin-donnelly approved these changes Dec 2, 2016

View reviewed changes

devin-donnelly added Docs LGTM and removed Docs Review: Open Issues labels Dec 2, 2016

devin-donnelly merged commit 5b0c6dc into kubernetes:release-1.5 Dec 2, 2016

ConnorDoyle deleted the oir-alpha branch December 2, 2016 23:57

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation for opaque integer resources (alpha feature in 1.5) #1783

Documentation for opaque integer resources (alpha feature in 1.5) #1783

ConnorDoyle commented Nov 24, 2016 •

edited by thockin

Loading

davidopp Nov 24, 2016

davidopp Nov 24, 2016

davidopp commented Nov 24, 2016

ConnorDoyle commented Nov 24, 2016 via email

ConnorDoyle commented Nov 28, 2016

ConnorDoyle commented Nov 28, 2016

hongchaodeng Nov 28, 2016

hongchaodeng Nov 28, 2016

timothysc Nov 28, 2016

ConnorDoyle Nov 29, 2016

aveshagarwal Nov 30, 2016

ConnorDoyle Nov 30, 2016

ConnorDoyle Nov 30, 2016

timothysc Nov 28, 2016 •

edited

Loading

ConnorDoyle Nov 29, 2016

devin-donnelly Dec 1, 2016

timothysc Nov 28, 2016

ConnorDoyle Nov 29, 2016

timothysc Nov 30, 2016

ConnorDoyle Nov 30, 2016

timothysc Nov 30, 2016

ConnorDoyle Nov 30, 2016

ConnorDoyle Nov 30, 2016

devin-donnelly Dec 1, 2016

devin-donnelly Dec 1, 2016

ConnorDoyle commented Dec 2, 2016

devin-donnelly commented Dec 2, 2016

		@@ -269,6 +269,86 @@ LastState: map[terminated:map[exitCode:137 reason:OOM Killed startedAt:2015-07-0

		We can see that this container was terminated because `reason:OOM Killed`, where OOM stands for Out Of Memory.

		## Alpha Features


		The HTTP request below advertises 5 "foo" resources on node `k8s-node-1`.

		_NOTE: `~1` is the encoding for the character `/` in the patch path._


		### Opaque Integer Resources (Alpha Feature)

		Opaque integer resources were introduced as an alpha feature in Kubernetes

Documentation for opaque integer resources (alpha feature in 1.5) #1783

Documentation for opaque integer resources (alpha feature in 1.5) #1783

Conversation

ConnorDoyle commented Nov 24, 2016 • edited by thockin Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

davidopp commented Nov 24, 2016

ConnorDoyle commented Nov 24, 2016 via email

ConnorDoyle commented Nov 28, 2016

ConnorDoyle commented Nov 28, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

timothysc Nov 28, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ConnorDoyle commented Dec 2, 2016

devin-donnelly commented Dec 2, 2016

ConnorDoyle commented Nov 24, 2016 •

edited by thockin

Loading

timothysc Nov 28, 2016 •

edited

Loading