Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document extended resources and OIR deprecation. #5399

Merged
merged 2 commits into from
Sep 13, 2017
Merged

Document extended resources and OIR deprecation. #5399

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
31794d3
Document extended resources and OIR deprecation.
ConnorDoyle Sep 12, 2017
d6ded8a
Updated extended resources doc per reviews.
ConnorDoyle Sep 12, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 97 additions & 19 deletions docs/concepts/configuration/manage-compute-resources-container.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -305,6 +305,8 @@ where `OOM` stands for Out Of Memory.

## Opaque integer resources (Alpha feature)

{% include feature-state-deprecated.md %}

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.
Expand All @@ -313,9 +315,12 @@ Users can consume these resources in Pod specs just like CPU and memory.
The scheduler takes care of the resource accounting so that no more than the
available amount is simultaneously allocated to Pods.

**Note:** Opaque integer resources are Alpha in Kubernetes version 1.5.
Only resource accounting is implemented; node-level isolation is still
under active development.
**Note:** Opaque Integer Resources will be removed in version 1.9.
[Extended Resources](#extended-resources) are a replacement for Opaque Integer
Resources. Users can use any domain name prefix outside of the `kubernetes.io/`
domain instead of the previous `pod.alpha.kubernetes.io/opaque-int-resource-`
prefix.
{: .note}

Opaque integer resources are resources that begin with the prefix
`pod.alpha.kubernetes.io/opaque-int-resource-`. The API server
Expand All @@ -339,22 +344,9 @@ first pod that requests the resource to be scheduled on that node.

**Example:**

Here is an HTTP request that advertises five "foo" resources on node `k8s-node-1` whose master is `k8s-master`.

```http
PATCH /api/v1/nodes/k8s-node-1/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-foo",
"value": "5"
}
]
```
Here is an example showing how to use `curl` to form an HTTP request that
advertises five "foo" resources on node `k8s-node-1` whose master is
`k8s-master`.

```shell
curl --header "Content-Type: application/json-patch+json" \
Expand Down Expand Up @@ -395,6 +387,92 @@ spec:
pod.alpha.kubernetes.io/opaque-int-resource-foo: 1
```

## Extended Resources

Kubernetes version 1.8 introduces Extended Resources. Extended Resources are
fully-qualified resource names outside the `kubernetes.io` domain. Extended
Resources allow cluster operators to advertise new node-level resources that
would be otherwise unknown to the system. Extended Resource quantities must be
integers and cannot be overcommitted.

Users can consume Extended Resources in Pod specs just like CPU and memory.
The scheduler takes care of the resource accounting so that no more than the
available amount is simultaneously allocated to Pods.

The API server restricts quantities of Extended Resources to whole numbers.
Examples of _valid_ quantities are `3`, `3000m` and `3Ki`. Examples of
_invalid_ quantities are `0.5` and `1500m`.

**Note:** Extended Resources replace [Opaque Integer
Resources](#opaque-integer-resources-alpha-feature). Users can use any domain
name prefix outside of the `kubernetes.io/` domain instead of the previous
`pod.alpha.kubernetes.io/opaque-int-resource-` prefix.
{: .note}

There are two steps required to use Extended Resources. First, the
cluster operator must advertise a per-node Extended Resource on one or more
nodes. Second, users must request the Extended Resource in Pods.

To advertise a new Extended Resource, the cluster operator should
submit a `PATCH` HTTP request to the API server to specify the available
quantity in the `status.capacity` for 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
asynchronously by the kubelet. Note that because the scheduler uses the
node `status.allocatable` value when evaluating Pod fitness, there may
be a short delay between patching the node capacity with a new resource and the
first pod that requests the resource to be scheduled on that node.

**Example:**

Here is an example showing how to use `curl` to form an HTTP request that
advertises five "example.com/foo" resources on node `k8s-node-1` whose master
is `k8s-master`.

```shell
curl --header "Content-Type: application/json-patch+json" \
--request PATCH \
--data '[{"op": "add", "path": "/status/capacity/example.com~1foo", "value": "5"}]' \
http://k8s-master:8080/api/v1/nodes/k8s-node-1/status
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the '/status' part should be removed?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ConnorDoyle
I think at least 50% common user do not know how to config OIR or Extended Resouce by curl quickly. So remaining it is very necessary. I meet many users ask how to config OIR, so I add it in OIR docs. =)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tengqm the URL shown is the correct way to patch the node 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, section 3](https://tools.ietf.org/html/rfc6901#section-3).
{: .note}

To consume an Extended Resource in a Pod, include the resource name as a key
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

better be explicit here: .. include the resource name example.com/foo as a key ...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I meant this sentence to be more general than the specific resource from the example. Did that not come across? This is the second of two steps required to use ERs. The previous section began with "To advertise a new Extended Resource..."

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alright, if it is referring to general cases, i.e. "an Extended Resource", it is fine.
I was reading it as "the Extended Resource".

in the `spec.containers[].resources.requests` map.

**Note:** Extended resources cannot be overcommitted, so request and limit
must be equal if both are present in a container spec.
{: .note}

The Pod is scheduled only if all of the resource requests are
satisfied, including cpu, memory and any Extended Resources. The Pod will
remain in the `PENDING` state as long as the resource request cannot be met by
any node.

**Example:**

The Pod below requests 2 cpus and 1 "example.com/foo" (an extended resource.)

```yaml
apiVersion: v1
kind: Pod
metadata:
name: my-pod
spec:
containers:
- name: my-container
image: myimage
resources:
requests:
cpu: 2
example.com/foo: 1
```

## Planned Improvements

Kubernetes version 1.5 only allows resource quantities to be specified on a
Expand Down
2 changes: 1 addition & 1 deletion docs/tasks/administer-cluster/opaque-integer-resource-node.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ 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 %}
{% include feature-state-deprecated.md %}

{% endcapture %}

Expand Down
2 changes: 1 addition & 1 deletion docs/tasks/configure-pod-container/opaque-integer-resource.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ title: Assign Opaque Integer Resources to a Container

This page shows how to assign opaque integer resources to a Container.

{% include feature-state-alpha.md %}
{% include feature-state-deprecated.md %}

{% endcapture %}

Expand Down