---
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 %}