Start new task for Opaque Integer Resources. (#4363)

_data/tasks.yml

@@ -14,6 +14,8 @@ toc:
   - docs/tasks/configure-pod-container/assign-memory-resource.md
   - docs/tasks/configure-pod-container/assign-cpu-resource.md
   - docs/tasks/configure-pod-container/quality-service-pod.md
+  - docs/tasks/configure-pod-container/assign-cpu-ram-container.md
+  - docs/tasks/configure-pod-container/opaque-integer-resource.md
   - docs/tasks/configure-pod-container/configure-volume-storage.md
   - docs/tasks/configure-pod-container/configure-persistent-volume-storage.md
   - docs/tasks/configure-pod-container/configure-projected-volume-storage.md
@@ -120,6 +122,7 @@ toc:
     - docs/tasks/administer-cluster/quota-memory-cpu-namespace.md
     - docs/tasks/administer-cluster/quota-pod-namespace.md
     - docs/tasks/administer-cluster/quota-api-object.md
+    - docs/tasks/administer-cluster/opaque-integer-resource-node.md
   - docs/tasks/administer-cluster/access-cluster-api.md
   - docs/tasks/administer-cluster/access-cluster-services.md
   - docs/tasks/administer-cluster/securing-a-cluster.md

docs/tasks/administer-cluster/opaque-integer-resource-node.md

@@ -0,0 +1,210 @@
+---
+title: Advertise Opaque Integer Resources for a Node
+---
+
+
+{% capture overview %}
+
+This page shows how to specify opaque integer resources for a Node.
+Opaque integer resources allow cluster administrators to advertise node-level
+resources that would otherwise be unknown to Kubernetes.
+
+{% include feature-state-alpha.md %}
+
+{% endcapture %}
+
+
+{% capture prerequisites %}
+
+{% include task-tutorial-prereqs.md %}
+
+{% endcapture %}
+
+
+{% capture steps %}
+
+## Get the names of your Nodes
+
+```shell
+kubectl get nodes
+```
+
+Choose one of your Nodes to use for this exercise.
+
+## Advertise a new opaque integer resource on one of your Nodes
+
+To advertise a new opaque integer resource on a Node, send an HTTP PATCH request to
+the Kubernetes API server. For example, suppose one of your Nodes has four dongles
+attached. Here's an example of a PATCH request that advertises four dongle resources
+for your Node.
+
+```shell
+PATCH /api/v1/nodes/<your-node-name>/status HTTP/1.1
+Accept: application/json
+Content-Type: application/json-patch+json
+Host: k8s-master:8080
+
+[
+  {
+    "op": "add",
+    "path": "/status/capacity/pod.alpha.kubernetes.io~1opaque-int-resource-dongle",
+    "value": "4"
+  }
+]
+```
+
+Note that Kubernetes does not need to know what a dongle is or what a dongle is for.
+The preceding PATCH request just tells Kubernetes that your Node has four things that
+you call dongles.
+
+Start a proxy, so that you can easily send requests to the Kubernetes API server:
+
+```
+kubectl proxy
+```
+
+In another command window, send the HTTP PATCH request.
+Replace `<your-node-name>` with the name of your Node:
+
+```shell
+curl --header "Content-Type: application/json-patch+json" \
+--request PATCH \
+--data '[{"op": "add", "path": "/status/capacity/pod.alpha.kubernetes.io~1opaque-int-resource-dongle", "value": "4"}]' \
+http://localhost:8001/api/v1/nodes/<your-node-name>/status
+```
+
+**Note**: In the preceding request, `~1` is the encoding for the character / in
+the patch path. The operation path value in JSON-Patch is interpreted as a
+JSON-Pointer. For more details, see
+[IETF RFC 6901](https://tools.ietf.org/html/rfc6901), section 3.
+
+The output shows that the Node has a capacity of 4 dongles:
+
+```
+"capacity": {
+  "alpha.kubernetes.io/nvidia-gpu": "0",
+  "cpu": "2",
+  "memory": "2049008Ki",
+  "pod.alpha.kubernetes.io/opaque-int-resource-dongle": "4",
+```
+
+Describe your Node:
+
+```
+kubectl describe node <your-node-name>
+```
+
+Once again, the output shows the dongle resource:
+
+```yaml
+Capacity:
+ alpha.kubernetes.io/nvidia-gpu:      0
+ cpu:             2
+ memory:            2049008Ki
+ pod.alpha.kubernetes.io/opaque-int-resource-dongle:  4
+```
+
+Now, application developers can create Pods that request a certain
+number of dongles. See
+[Assign Opaque Integer Resources to a Container](/docs/tasks/configure-pod-container/opaque-integer-resource/).
+
+## Discussion
+
+Opaque integer resources are similar to memory and CPU resources. For example,
+just as  a Node has a certain amount of memory and CPU to be shared by all components
+running on the Node, it can have a certain number of dongles to be shared
+by all components running on the Node. And just as application developers
+can create Pods that request a certain amount of memory and CPU, they can
+create Pods that request a certain number of dongles.
+
+Opaque integer resources are called opaque because Kubernetes does not
+know anything about what they are. Kubernetes knows only that a Node
+has a certain number of them. They are called integer resources because
+they must be advertised in integer amounts. For example, a Node can advertise
+four dongles, but not 4.5 dongles.
+
+### Storage example
+
+Suppose a Node has 800 GiB of a special kind of disk storage. You could
+create a name for the special storage, say opaque-int-resource-special-storage.
+Then you could advertise it in chunks of a certain size, say 100 GiB. In that case,
+your Node would advertise that it has eight resources of type
+opaque-int-resource-special-storage.
+
+```yaml
+Capacity:
+ ...
+ pod.alpha.kubernetes.io/opaque-int-special-storage:  8
+```
+
+If you want to allow arbitrary requests for special storage, you
+could advertise special storage in chunks of size 1 byte. In that case, you would advertise
+800Gi resources of type opaque-int-resource-special-storage.
+
+```yaml
+Capacity:
+ ...
+ pod.alpha.kubernetes.io/opaque-int-special-storage:  8Gi
+```
+
+Then a Container could request any number of bytes of special storage, up to 800Gi.
+
+## Clean up
+
+Here is a PATCH request that removes the dongle advertisement from a Node.
+
+```shell
+PATCH /api/v1/nodes/<your-node-name>/status HTTP/1.1
+Accept: application/json
+Content-Type: application/json-patch+json
+Host: k8s-master:8080
+
+[
+  {
+    "op": "remove",
+    "path": "/status/capacity/pod.alpha.kubernetes.io~1opaque-int-resource-dongle",
+  }
+]
+```
+
+Start a proxy, so that you can easily send requests to the Kubernetes API server:
+
+```
+kubectl proxy
+```
+
+In another command window, send the HTTP PATCH request.
+Replace `<your-node-name>` with the name of your Node:
+
+```shell
+curl --header "Content-Type: application/json-patch+json" \
+--request PATCH \
+--data '[{"op": "remove", "path": "/status/capacity/pod.alpha.kubernetes.io~1opaque-int-resource-dongle"}]' \
+http://localhost:8001/api/v1/nodes/<your-node-name>/status
+```
+
+Verify that the dongle advertisement has been removed:
+
+```
+kubectl describe node <your-node-name> | grep dongle
+```
+
+{% endcapture %}
+
+
+{% capture whatsnext %}
+
+### For application developers
+
+* [Assign Opaque Integer Resources to a Container](/docs/tasks/configure-pod-container/opaque-integer-resource/)
+
+### For cluster administrators
+
+* [Configure Minimum and Maximum Memory Constraints for a Namespace](/docs/tasks/administer-cluster/memory-constraint-namespace/)
+* [Configure Minimum and Maximum CPU Constraints for a Namespace](/docs/tasks/administer-cluster/cpu-constraint-namespace/)
+
+
+{% endcapture %}
+
+
+{% include templates/task.md %}

docs/tasks/configure-pod-container/oir-pod-2.yaml

@@ -0,0 +1,11 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: oir-demo-2
+spec:
+  containers:
+  - name: oir-demo-2-ctr
+    image: nginx
+    resources:
+      requests:
+        pod.alpha.kubernetes.io/opaque-int-resource-dongle: 2

docs/tasks/configure-pod-container/oir-pod.yaml

@@ -0,0 +1,11 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: oir-demo
+spec:
+  containers:
+  - name: oir-demo-ctr
+    image: nginx
+    resources:
+      requests:
+        pod.alpha.kubernetes.io/opaque-int-resource-dongle: 3

docs/tasks/configure-pod-container/opaque-integer-resource.md

@@ -0,0 +1,141 @@
+---
+title: Assign Opaque Integer Resources to a Container
+---
+
+{% capture overview %}
+
+This page shows how to assign opaque integer resources to a Container.
+
+{% include feature-state-alpha.md %}
+
+{% endcapture %}
+
+
+{% capture prerequisites %}
+
+{% include task-tutorial-prereqs.md %}
+
+Before you do this exercise, do the exercise in
+[Advertise Opaque Integer Resources for a Node](/docs/tasks/administer-cluster/opaque-integer-resource-node/).
+That will configure one of your Nodes to advertise a dongle resource.
+
+{% endcapture %}
+
+
+{% capture steps %}
+
+## Assign an opaque integer resource to a Pod
+
+To request an opaque integer resource, include the `resources:requests` field in your
+Container manifest. Opaque integer resources have the prefix `pod.alpha.kubernetes.io/opaque-int-resource-`.
+
+Here is the configuration file for a Pod that has one Container:
+
+{% include code.html language="yaml" file="oir-pod.yaml" ghlink="/docs/tasks/configure-pod-container/oir-pod.yaml" %}
+
+In the configuration file, you can see that the Container requests 3 dongles.
+
+Create a Pod:
+
+```shell
+kubectl create -f https://k8s.io/docs/tasks/configure-pod-container/oir-pod.yaml
+```
+
+Verify that the Pod is running:
+
+```shell
+kubectl get pod oir-demo
+```
+
+Describe the Pod:
+
+```shell
+kubectl describe pod oir-demo
+```
+
+The output shows the memory, CPU, and dongle requests:
+
+```yaml
+Requests:
+  pod.alpha.kubernetes.io/opaque-int-resource-dongle: 3
+```
+
+## Attempt to create a second Pod
+
+Here is the configuration file for a Pod that has one Container. The Container requests
+two dongles.
+
+{% include code.html language="yaml" file="oir-pod-2.yaml" ghlink="/docs/tasks/configure-pod-container/oir-pod-2.yaml" %}
+
+Kubernetes will not be able to satisfy the request for two dongles, because the first Pod
+used three of the four available dongles.
+
+Attempt to create a Pod:
+
+```shell
+kubectl create -f https://k8s.io/docs/tasks/configure-pod-container/oir-pod-2.yaml
+```
+
+Describe the Pod
+
+```shell
+kubectl describe pod oir-demo-2
+```
+
+The output shows that the Pod cannot be scheduled, because there is no Node that has
+2 dongles available:
+
+
+```
+Conditions:
+  Type    Status
+  PodScheduled  False
+...
+Events:
+  ...
+  ... Warning   FailedScheduling  pod (oir-demo-2) failed to fit in any node
+fit failure summary on nodes : Insufficient pod.alpha.kubernetes.io/opaque-int-resource-dongle (1)
+```
+
+View the Pod status:
+
+```shell
+kubectl get pod oir-demo-2
+```
+
+The output shows that the Pod was created, but not scheduled to run on a Node.
+It has a status of Pending:
+
+```yaml
+NAME         READY     STATUS    RESTARTS   AGE
+oir-demo-2   0/1       Pending   0          6m
+```
+
+## Clean up
+
+Delete the Pod that you created for this exercise:
+
+```shell
+kubectl delete pod oir-demo
+```
+
+{% endcapture %}
+
+{% capture whatsnext %}
+
+### For application developers
+
+* [Assign Memory Resources to Containers and Pods](/docs/tasks/configure-pod-container/assign-memory-resource/)
+* [Assign CPU Resources to Containers and Pods](docs/tasks/configure-pod-container/assign-cpu-resource/)
+
+### For cluster administrators
+
+* [Advertise Opaque Integer Resources for a Node](/docs/tasks/administer-cluster/opaque-integer-resource-node/)
+
+{% endcapture %}
+
+
+{% include templates/task.md %}
+
+
+