From 2576f404f001b3dd4286efe5ffa561ad111bfa5a Mon Sep 17 00:00:00 2001 From: Steve Perry Date: Tue, 8 Aug 2017 01:05:23 -0700 Subject: [PATCH] Start new task for Opaque Integer Resources. (#4363) --- _data/tasks.yml | 3 + .../opaque-integer-resource-node.md | 210 ++++++++++++++++++ .../configure-pod-container/oir-pod-2.yaml | 11 + .../configure-pod-container/oir-pod.yaml | 11 + .../opaque-integer-resource.md | 141 ++++++++++++ 5 files changed, 376 insertions(+) create mode 100644 docs/tasks/administer-cluster/opaque-integer-resource-node.md create mode 100644 docs/tasks/configure-pod-container/oir-pod-2.yaml create mode 100644 docs/tasks/configure-pod-container/oir-pod.yaml create mode 100644 docs/tasks/configure-pod-container/opaque-integer-resource.md diff --git a/_data/tasks.yml b/_data/tasks.yml index cb8efc918b..9452aaad35 100644 --- a/_data/tasks.yml +++ b/_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 diff --git a/docs/tasks/administer-cluster/opaque-integer-resource-node.md b/docs/tasks/administer-cluster/opaque-integer-resource-node.md new file mode 100644 index 0000000000..71925c1642 --- /dev/null +++ b/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//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 `` 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//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 +``` + +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//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 `` 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//status +``` + +Verify that the dongle advertisement has been removed: + +``` +kubectl describe node | 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 %} diff --git a/docs/tasks/configure-pod-container/oir-pod-2.yaml b/docs/tasks/configure-pod-container/oir-pod-2.yaml new file mode 100644 index 0000000000..cfe4b96076 --- /dev/null +++ b/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 diff --git a/docs/tasks/configure-pod-container/oir-pod.yaml b/docs/tasks/configure-pod-container/oir-pod.yaml new file mode 100644 index 0000000000..bd85a5d4f6 --- /dev/null +++ b/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 diff --git a/docs/tasks/configure-pod-container/opaque-integer-resource.md b/docs/tasks/configure-pod-container/opaque-integer-resource.md new file mode 100644 index 0000000000..7451f3b774 --- /dev/null +++ b/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 %} + + +