You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[](https://www.repostatus.org/#wip)
12
10
13
-
`kubectl` plugin lists allocations for resources (cpu, memory, gpu,...) as defined into the manifest of nodes and running pods. It doesn't list usage like `kubectl top`. It can provide result grouped by namespaces, nodes, pods and filtered by resources'name.
11
+
`kubectl` plugin for visualizing resource allocations across your cluster. Key differentiators:
14
12
15
-
Columns displayed :
13
+
-**All resources** — cpu, memory, gpu, and any custom resource; not limited to cpu/memory like most tools
14
+
-**Tree view** — group and aggregate by resource, node, namespace, or pod in any combination via `-g`
15
+
-**Full picture** — requested, limit, allocatable, free, and optionally live utilization (`-u`, requires metrics-server)
16
16
17
-
-`Requested` : Quantity of resources requested by the container in the pod's manifest. It's the sum group by pod, namespace, node where container is running. With percentage of resources requested over what is allocatable in the group.
18
-
-`Limit` : Quantity of resources max (limit) requestable by the container in the pod's manifest. It's the sum group by pod, namespace, node where container is running. With percentage of resources max / limit over what is allocatable in the group.
19
-
-`Allocatable` : Allocatable resources defined (or detected) on nodes.
20
-
-`Free` : `Allocatable - max (Limit, Requested)` (by default, see options `--used-mode`)
21
-
-`Utilization` : Quantity of resources (cpu & memory only) used as reported by Metrics API. It's disable by default, [metrics-server](https://github.com/kubernetes-incubator/metrics-server) is optional and should be setup into the cluster.
17
+
```sh
18
+
kubectl view-allocations
19
+
```
22
20
23
-
21
+
> **Note:** By default only nodes *without* taints are shown. If results look empty or incomplete, use `--ignore-taints` to include control-plane or tainted nodes — see [Filter by Node Taints](#filter-by-node-taints).
24
22
25
-
## Install
23
+
## Table of Contents
26
24
27
-
### Via download binary
25
+
-[Output Columns](#output-columns)
26
+
-[Install](#install) — krew · mise · binary · cargo
27
+
-[Usage](#usage)
28
+
-[Overview only](#overview-only)
29
+
-[Show GPU allocation](#show-gpu-allocation)
30
+
-[Show utilization](#show-utilization)
31
+
-[Group by namespaces](#group-by-namespaces)
32
+
-[Show as CSV](#show-as-csv)
33
+
-[Filter by node taints](#filter-by-node-taints)
34
+
-[Full option reference](#full-option-reference)
35
+
-[Alternatives](#alternatives)
28
36
29
-
Download from [github's release](https://github.com/davidB/kubectl-view-allocations/releases/latest) or use script
|`Requested`| Resources requested by containers in pod manifests, summed by pod/namespace/node. Includes percentage of the group's allocatable total. |
42
+
|`Limit`| Max resources (limit) set in pod manifests, summed by pod/namespace/node. Includes percentage of the group's allocatable total. |
43
+
|`Allocatable`| Allocatable resources defined (or detected) on nodes. |
44
+
|`Free`|`Allocatable - max(Limit, Requested)` by default — see `--used-mode` to change this. |
45
+
|`Utilization`| Actual cpu/memory usage from the Metrics API. Disabled by default; requires [metrics-server](https://github.com/kubernetes-incubator/metrics-server) on the cluster. |
This installs the assistant workflow for using `kubectl view-allocations`; it
59
-
does not install the `kubectl-view-allocations` binary itself.
60
-
61
-
### As lib in Cargo.toml
62
-
63
-
If you want to embed some function or struct of the plugin into an other rust code:
64
-
65
-
```toml
66
-
[dependencies]
67
-
kubectl-view-allocations = { version = "0.14", default-features = false }
68
-
69
-
[features]
70
-
default = ["k8s-openapi/v1_20"]
68
+
**cargo**
69
+
```sh
70
+
cargo install kubectl-view-allocations
71
71
```
72
72
73
73
## Usage
74
74
75
-
### Show help
76
-
77
-
```sh
78
-
> kubectl-view-allocations -h
79
-
kubectl plugin to list allocations (cpu, memory, gpu,...) X (utilization, requested, limit, allocatable,...)
75
+
All examples use `kubectl-view-allocations` directly; if installed via krew, substitute `kubectl view-allocations`.
80
76
81
-
Usage: kubectl-view-allocations [OPTIONS]
77
+
### Overview only
82
78
83
-
Options:
84
-
--kubeconfig <KUBECONFIG>
85
-
Path to the kubeconfig file to use for requests to kubernetes cluster
86
-
--context <CONTEXT>
87
-
The name of the kubeconfig context to use
88
-
-n, --namespace <NAMESPACE>...
89
-
Filter pods by namespace(s), by default pods in all namespaces are listed (comma separated list or multiple calls)
90
-
-l, --selector <SELECTOR>
91
-
Show only nodes match this label selector
92
-
--ignore-taints [<IGNORE_TAINTS>...]
93
-
Ignore nodes with specific taints; when not specified, only nodes without taints are shown; when used without values, show all nodes (comma-separated list)
94
-
-u, --utilization
95
-
Force to retrieve utilization (for cpu and memory), requires having metrics-server https://github.com/kubernetes-sigs/metrics-server
96
-
-z, --show-zero
97
-
Show lines with zero requested AND zero limit AND zero allocatable, OR pods with unset requested AND limit for`cpu` and `memory`
98
-
--used-mode <USED_MODE>
99
-
The way to compute the `used` part for free (`allocatable - used`) [default: max-request-limit] [possible values: max-request-limit, only-request]
100
-
--precheck
101
-
Pre-check access and refresh token on kubeconfig by running `kubectl cluster-info`
102
-
--accept-invalid-certs
103
-
Accept invalid certificates (dangerous)
104
-
-r, --resource-name <RESOURCE_NAME>...
105
-
Filter resources shown by name(s), by default all resources are listed (comma separated list or multiple calls)
106
-
-g, --group-by <GROUP_BY>...
107
-
Group information in a hierarchical manner; defaults to `-g resource,node,pod` (comma-separated list or multiple calls) [possible values: resource, node, pod, namespace]
108
-
-o, --output <OUTPUT>
109
-
Output format [default: table] [possible values: table, csv]
110
-
-s, --sort <SORT>
111
-
Sort rows by column(s), SQL-like syntax: 'col [ASC|DESC]' (comma-separated). Valid columns: usage/utilization, requested, limits/limit, allocatable, free, name. Direction is optional (default ASC). name ASC is always the implicit final tiebreaker [default: "usage DESC, requested DESC, limits DESC, name ASC"]
- Utilization information are retrieve from [metrics-server](https://github.com/kubernetes-incubator/metrics-server) (should be setup on your cluster).
158
-
- Only report cpu and memory utilization
114
+
- Utilization information are retrieved from [metrics-server](https://github.com/kubernetes-incubator/metrics-server) (should be setup on your cluster).
-**Include control-plane**: Use `--ignore-taints node-role.kubernetes.io/control-plane` to see workload + control-plane nodes
273
230
-**Include specialized nodes**: Use `--ignore-taints dedicated,workload` to include dedicated or workload-specific nodes alongside regular workload nodes
274
231
232
+
### Full option reference
233
+
234
+
```sh
235
+
> kubectl-view-allocations -h
236
+
kubectl plugin to list allocations (cpu, memory, gpu,...) X (utilization, requested, limit, allocatable,...)
237
+
238
+
Usage: kubectl-view-allocations [OPTIONS]
239
+
240
+
Options:
241
+
--kubeconfig <KUBECONFIG>
242
+
Path to the kubeconfig file to use for requests to kubernetes cluster
243
+
--context <CONTEXT>
244
+
The name of the kubeconfig context to use
245
+
-n, --namespace <NAMESPACE>...
246
+
Filter pods by namespace(s), by default pods in all namespaces are listed (comma separated list or multiple calls)
247
+
-l, --selector <SELECTOR>
248
+
Show only nodes match this label selector
249
+
--ignore-taints [<IGNORE_TAINTS>...]
250
+
Ignore nodes with specific taints; when not specified, only nodes without taints are shown; when used without values, show all nodes (comma-separated list)
251
+
-u, --utilization
252
+
Force to retrieve utilization (for cpu and memory), requires having metrics-server https://github.com/kubernetes-sigs/metrics-server
253
+
-z, --show-zero
254
+
Show lines with zero requested AND zero limit AND zero allocatable, OR pods with unset requested AND limit for`cpu` and `memory`
255
+
--used-mode <USED_MODE>
256
+
The way to compute the `used` part for free (`allocatable - used`) [default: max-request-limit] [possible values: max-request-limit, only-request]
257
+
--precheck
258
+
Pre-check access and refresh token on kubeconfig by running `kubectl cluster-info`
259
+
--accept-invalid-certs
260
+
Accept invalid certificates (dangerous)
261
+
-r, --resource-name <RESOURCE_NAME>...
262
+
Filter resources shown by name(s), by default all resources are listed (comma separated list or multiple calls)
263
+
-g, --group-by <GROUP_BY>...
264
+
Group information in a hierarchical manner; defaults to `-g resource,node,pod` (comma-separated list or multiple calls) [possible values: resource, node, pod, namespace]
265
+
-o, --output <OUTPUT>
266
+
Output format [default: table] [possible values: table, csv]
267
+
-s, --sort <SORT>
268
+
Sort rows by column(s), SQL-like syntax: 'col [ASC|DESC]' (comma-separated). Valid columns: usage/utilization, requested, limits/limit, allocatable, free, name. Direction is optional (default ASC). name ASC is always the implicit final tiebreaker [default: "usage DESC, requested DESC, limits DESC, name ASC"]
- see the discussion [Need simple kubectl command to see cluster resource usage · Issue #17512 · kubernetes/kubernetes](https://github.com/kubernetes/kubernetes/issues/17512)
-[LeastAuthority/kubetop: A top(1)-like tool for Kubernetes.](https://github.com/LeastAuthority/kubetop)
288
+
- As a Rust library
289
+
-[kdash-rs/kdash](https://crates.io/crates/kdash) embeds `kubectl-view-allocations` as a dependency. To use it in your own Rust project: `kubectl-view-allocations = { version = "1.1.0", default-features = false }` (add `k8s-openapi/vX_YY` to your features).
290
+
- Via AI assistant (no binary needed)
291
+
- If your AI coding tool supports [skills.sh](https://skills.sh), install the assistant workflow with `npx skills add davidB/kubectl-view-allocations`. This lets your AI agent run and interpret `kubectl view-allocations` for you — it does not install the binary.
Copy file name to clipboardExpand all lines: skills/kubectl-view-allocations/SKILL.md
+17-3Lines changed: 17 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,13 +1,19 @@
1
1
---
2
2
name: kubectl-view-allocations
3
-
description: "Use when inspecting Kubernetes resource allocation with kubectl view-allocations. For allocation questions, use kubectl view-allocations first and do not replace it with native kubectl get/describe/top/jsonpath queries. Covers cluster/node/namespace/pod requests, limits, allocatable, free capacity, GPU or custom resources, taint-filtered node views, CSV exports, metrics-server utilization via kubectl view-allocations -u, kubeconfig/context access checks, and allocation-focused troubleshooting. Trigger for CPU, memory, GPU, pod capacity, overcommit, missing requests/limits, tainted nodes, or comparing requested/limit/utilization data in a Kubernetes cluster."
3
+
description: "Use when inspecting Kubernetes resource allocation with kubectl view-allocations. For allocation questions, use kubectl view-allocations first and do not replace it with native kubectl get/describe/top/jsonpath queries. Covers cluster/node/namespace/pod requests, limits, allocatable, free capacity, ALL resources including GPU and custom resources (not just CPU/memory), taint-filtered node views, tree-view grouping via -g, multi-column sort via --sort, CSV exports, metrics-server utilization via kubectl view-allocations -u, kubeconfig/context access checks, and allocation-focused troubleshooting. Trigger for CPU, memory, GPU, pod capacity, overcommit, missing requests/limits, tainted nodes, or comparing requested/limit/utilization data in a Kubernetes cluster. WARNING: default output excludes tainted nodes — results may be empty or partial on clusters where all nodes have taints (e.g. control-plane-only, GPU, dedicated workload nodes)."
4
4
---
5
5
6
6
# Kubectl View Allocations
7
7
8
8
Use `kubectl view-allocations` as the required first tool for this repository's allocation workflow. Do not answer allocation questions by reconstructing the same data with native `kubectl get`, `kubectl describe`, `kubectl top`, JSONPath, or ad hoc scripts unless `kubectl view-allocations` cannot run and the user accepts a fallback.
9
9
10
-
`kubectl view-allocations` reports Kubernetes allocations from manifests and node allocatable resources; it is not a replacement for `kubectl top`, except when `-u/--utilization` is explicitly requested and Metrics API is available.
10
+
`kubectl view-allocations` reports Kubernetes allocations from manifests and node allocatable resources. Key differentiators over `kubectl top` and similar tools:
11
+
12
+
-**All resources**: cpu, memory, GPU, and any custom resource — not limited to cpu/memory
13
+
-**Tree view**: group and aggregate by resource, node, namespace, or pod in any combination via `-g`
14
+
-**Live utilization**: optional via `-u` (requires metrics-server), same as `kubectl top` but richer
15
+
16
+
> **Default taint filtering**: only nodes *without* taints are shown. On clusters where all nodes carry taints (control-plane-only, GPU nodes, dedicated workloads), the output may be empty or partial. Use `--ignore-taints` to include tainted nodes.
Add `--context CONTEXT` and `--kubeconfig PATH` when the user names a cluster or config file. Use `--precheck` when kube auth tokens may need refreshing because it runs `kubectl cluster-info` first.
-`Utilization`: live CPU/memory usage from Metrics API, shown only with `-u`.
70
82
-`__`: value is absent or not meaningful at that grouping level, not necessarily zero.
71
83
72
-
Default grouping is `resource,node,pod`; `resource` is always prepended when omitted. Default node filtering excludes tainted nodes. Use `--ignore-taints` with no value to include all nodes, or with taint keys/key-value pairs to include specific tainted nodes.
84
+
Default grouping is `resource,node,pod`; `resource` is always prepended when omitted. Default node filtering excludes tainted nodes — **if output is empty or missing nodes, try `--ignore-taints`**. Use `--ignore-taints` with no value to include all nodes, or with taint keys/key-value pairs to include specific tainted nodes.
85
+
86
+
`--sort` / `-s` accepts SQL-like syntax: `col [ASC|DESC]`, comma-separated for multi-column. Valid columns: `usage`/`utilization`, `requested`, `limits`/`limit`, `allocatable`, `free`, `name`. Default: `"usage DESC, requested DESC, limits DESC, name ASC"`. Sort applies within sibling groups at each tree level.
0 commit comments