Skip to content

Commit

Permalink
Better Readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@akrzos
akrzos committed Jan 27, 2021
1 parent ca34791 commit 8fe64d0
Show file tree
Hide file tree
Showing 2 changed files with 206 additions and 49 deletions.
247 changes: 199 additions & 48 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,63 +1,214 @@
# kubeSize

kubeSize is a kubernetes CLI plugin to easily expose sizing and capacity data for Kubernetes clusters.
kubeSize is a kubernetes CLI plugin to easily aggregate sizing and capacity data for a Kubernetes cluster.

## Develop
## Table of Contents

### Compile
- [Install](#install)
- [Usage](#usage)
- [License](#license)

```sh
make bin
```
## Install

### Krew install

### Run
If you have [krew](https://krew.sigs.k8s.io/) installed, you can install this plugin with the krew plugin yaml.

```sh
./bin/kubectl-capacity
```console
$ git clone https://github.com/akrzos/kubeSize.git
Cloning into 'kubeSize'...
remote: Enumerating objects: 256, done.
remote: Counting objects: 100% (256/256), done.
remote: Compressing objects: 100% (130/130), done.
remote: Total 256 (delta 130), reused 203 (delta 85), pack-reused 0
Receiving objects: 100% (256/256), 110.97 KiB | 3.83 MiB/s, done.
Resolving deltas: 100% (130/130), done.
$ kubectl krew install --manifest=kubeSize/deploy/krew/capacity.yaml
Installing plugin: capacity
Installed plugin: capacity
\
| Use this plugin:
| kubectl capacity
| Documentation:
| https://github.com/akrzos/kubeSize
/
$ kubectl capacity
```

### Install as a kubectl plugin
### Compile and install

```sh
cp bin/kubectl-capacity /usr/local/bin/kubectl-capacity
If you have a golang environment setup, you can compile the plugin and manually install it.

```console
$ git clone https://github.com/akrzos/kubeSize.git
Cloning into 'kubeSize'...
remote: Enumerating objects: 256, done.
remote: Counting objects: 100% (256/256), done.
remote: Compressing objects: 100% (130/130), done.
remote: Total 256 (delta 130), reused 203 (delta 85), pack-reused 0
Receiving objects: 100% (256/256), 110.97 KiB | 3.70 MiB/s, done.
Resolving deltas: 100% (130/130), done.
$ cd kubeSize/
$ make bin
go fmt ./cmd/...
go vet ./cmd/...
go build -o bin/kubectl-capacity github.com/akrzos/kubeSize/
$ mv bin/kubectl-capacity /usr/local/bin/
$ kubectl capacity
```

### Use
## Usage

```sh
kubeSize is used as a kubectl plugin and run from the kubectl CLI.

```console
$ kubectl capacity
Capacity exposes size and capacity data for Kubernetes clusters

Usage:
capacity [command]

Available Commands:
cluster Get cluster size and capacity
help Help about any command
namespace Get namespace size
node Get individual node capacity
node-role Get cluster capacity grouped by node role

Flags:
--as string Username to impersonate for the operation
--as-group stringArray Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
--cache-dir string Default HTTP cache directory (default "/Users/akrzos/.kube/http-cache")
--certificate-authority string Path to a cert file for the certificate authority
--client-certificate string Path to a client certificate file for TLS
--client-key string Path to a client key file for TLS
--cluster string The name of the kubeconfig cluster to use
--context string The name of the kubeconfig context to use
-d, --default-format Use default format of displaying resource quantities
-h, --help help for capacity
--insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
--kubeconfig string Path to the kubeconfig file to use for CLI requests.
-n, --namespace string If present, the namespace scope for this CLI request
--no-headers No headers in table output format
-o, --output string Output format. One of: table|json|yaml (default "table")
--request-timeout string The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
-s, --server string The address and port of the Kubernetes API server
--token string Bearer token for authentication to the API server
--user string The name of the kubeconfig user to use

Use "capacity [command] --help" for more information about a command.
```

Sub-commands aggregate cluster capacity data and display it for use. Flags can modify what data is collected or the format of the output.

### Cluster Capacity

Aggregated cluster capacity data can easily be displayed with the `cluster` sub-command.

```console
$ kubectl capacity cluster
NODES PODS CPU (cores) MEMORY (GiB)
Total Ready Unready Unsch Capacity Allocatable Total Non-Term Avail Capacity Allocatable Requests Limits Avail Capacity Allocatable Requests Limits Avail
3 3 0 0 330 330 13 13 317 12.0 12.0 1.1 0.3 10.9 5.8 5.8 0.3 0.5 5.5
```

### Node-Role Capacity

Capacity data aggregated and grouped by node-role can be displayed with the `node-role` sub-command. This is helpful to see the available space to deploy an application on your kubernetes cluster by looking at the worker or compute node's available metrics (pods, cpu, memory).

```console
$ kubectl capacity node-role
ROLE NODES PODS CPU (cores) MEMORY (GiB)
Total Ready Unready Unsch Capacity Allocatable Total Non-Term Avail Capacity Allocatable Requests Limits Avail Capacity Allocatable Requests Limits Avail
<none> 2 2 0 0 220 220 7 7 213 8.0 8.0 0.4 0.2 7.6 3.9 3.9 0.2 0.4 3.6
master 1 1 0 0 110 110 6 6 104 4.0 4.0 0.7 0.1 3.4 1.9 1.9 0.0 0.0 1.9
```

Use the `--unassigned` or `-u` flag to include data on non-terminated pods that have not been assigned to a node that could be confused if looking at cluster level capacity data.

### Node Capacity

Individual node capacity data can be displayed with the `node` sub-command.

```console
$ kubectl capacity node
NAME STATUS ROLES PODS CPU (cores) MEMORY (GiB)
Capacity Allocatable Total Non-Term Avail Capacity Allocatable Requests Limits Avail Capacity Allocatable Requests Limits Avail
3node-control-plane Ready master 110 110 6 6 104 4.0 4.0 0.7 0.1 3.4 1.9 1.9 0.0 0.0 1.9
3node-worker Ready <none> 110 110 3 3 107 4.0 4.0 0.2 0.1 3.8 1.9 1.9 0.1 0.2 1.8
3node-worker2 Ready <none> 110 110 4 4 106 4.0 4.0 0.2 0.1 3.8 1.9 1.9 0.1 0.2 1.8
```

Use the `--sort-by-role` or `-r` flag to sort by node-role rather than node name in the event your nodes are named randomly. Use the `--unassigned` or `-u` flag to include data on non-terminated pods that have not been assigned to a node that could be confused if looking at cluster level capacity data.

### Namespace Capacity

Individual namespace capacity usage can be viewed with the `namespace` sub-command.

```console
$ kubectl capacity namespace
NAMESPACE PODS CPU (cores) MEMORY (GiB)
Total Non-Term Unassigned Requests Limits Requests Limits
kube-system 12 12 0 1.1 0.3 0.3 0.5
local-path-storage 1 1 0 0.0 0.0 0.0 0.0
```

Use the `--all-namespaces` or `-A` to view all namespaces including those without any pods. Use the `--namespace` or `-n` flag to select a specific namespace.

### Shortened command names

All sub-commands have shortened aliases:

```console
$ kubectl capacity c # cluster
$ kubectl capacity nr # node-role
$ kubectl capacity no # node
$ kubectl capacity ns # namespace
```

### Output formats

kubeSize supports table, yaml, and json output formats. Table data is the default format and is designed to be read by humans. With table output, CPU metrics default to cores and Memory metrics into [GiB (gibibyte)](https://en.wikipedia.org/wiki/Byte#Multiple-byte_units).

Use the output flag to change output formats:

```console
$ kubectl capacity c
NODES PODS CPU (cores) MEMORY (GiB)
Total Ready Unready Unsch Capacity Allocatable Total Non-Term Avail Capacity Allocatable Requests Limits Avail Capacity Allocatable Requests Limits Avail
1 1 0 0 110 110 9 9 101 4.0 4.0 0.8 0.1 3.1 1.9 1.9 0.2 0.4 1.8
$ kubectl capacity c -o yaml
TotalAllocatableCPU: "4"
TotalAllocatableCPUCores: 4
TotalAllocatableMemory: 2036452Ki
TotalAllocatableMemoryGiB: 1.9421119689941406
TotalAllocatablePods: "110"
TotalAvailableCPU: 3150m
TotalAvailableCPUCores: 3.15
TotalAvailableMemory: 1841892Ki
TotalAvailableMemoryGiB: 1.7565650939941406
TotalAvailablePods: 101
TotalCapacityCPU: "4"
TotalCapacityCPUCores: 4
TotalCapacityMemory: 2036452Ki
TotalCapacityMemoryGiB: 1.9421119689941406
TotalCapacityPods: "110"
TotalLimitsCPU: 100m
TotalLimitsCPUCores: 0.1
TotalLimitsMemory: 390Mi
TotalLimitsMemoryGiB: 0.380859375
TotalNodeCount: 1
TotalNonTermPodCount: 9
TotalPodCount: 9
TotalReadyNodeCount: 1
TotalRequestsCPU: 850m
TotalRequestsCPUCores: 0.85
TotalRequestsMemory: 190Mi
TotalRequestsMemoryGiB: 0.185546875
TotalUnreadyNodeCount: 0
TotalUnschedulableNodeCount: 0
$ kubectl capacity c -o json
{
"TotalNodeCount": 1,
"TotalReadyNodeCount": 1,
"TotalUnreadyNodeCount": 0,
"TotalUnschedulableNodeCount": 0,
"TotalPodCount": 9,
"TotalNonTermPodCount": 9,
"TotalCapacityPods": "110",
"TotalCapacityCPU": "4",
"TotalCapacityCPUCores": 4,
"TotalCapacityMemory": "2036452Ki",
"TotalCapacityMemoryGiB": 1.9421119689941406,
"TotalAllocatablePods": "110",
"TotalAllocatableCPU": "4",
"TotalAllocatableCPUCores": 4,
"TotalAllocatableMemory": "2036452Ki",
"TotalAllocatableMemoryGiB": 1.9421119689941406,
"TotalAvailablePods": 101,
"TotalRequestsCPU": "850m",
"TotalRequestsCPUCores": 0.85,
"TotalLimitsCPU": "100m",
"TotalLimitsCPUCores": 0.1,
"TotalAvailableCPU": "3150m",
"TotalAvailableCPUCores": 3.15,
"TotalRequestsMemory": "190Mi",
"TotalRequestsMemoryGiB": 0.185546875,
"TotalLimitsMemory": "390Mi",
"TotalLimitsMemoryGiB": 0.380859375,
"TotalAvailableMemory": "1841892Ki",
"TotalAvailableMemoryGiB": 1.7565650939941406
}
```

Note that yaml and json formats automatically include the "human" Cores and GiB formats for each metric.

## License

This project has an [Apache 2.0 license](LICENSE).
8 changes: 7 additions & 1 deletion cmd/capacity/namespace.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,21 +50,27 @@ var namespaceCmd = &cobra.Command{

nsFlag, _ := cmd.Flags().GetString("namespace")
nsListOptions := metav1.ListOptions{}
podListOptions := metav1.ListOptions{}

if nsFlag != "" {
nsFieldSelector, err := fields.ParseSelector("metadata.name=" + nsFlag)
if err != nil {
return errors.Wrap(err, "failed to create fieldSelector")
}
podNamespaceFieldSelector, err := fields.ParseSelector("metadata.namespace=" + nsFlag)
if err != nil {
return errors.Wrap(err, "failed to create fieldSelector")
}
nsListOptions = metav1.ListOptions{FieldSelector: nsFieldSelector.String()}
podListOptions = metav1.ListOptions{FieldSelector: podNamespaceFieldSelector.String()}
}

namespaces, err := clientset.CoreV1().Namespaces().List(nsListOptions)
if err != nil {
return errors.Wrap(err, "failed to list namespaces")
}

pods, err := clientset.CoreV1().Pods("").List(metav1.ListOptions{})
pods, err := clientset.CoreV1().Pods("").List(podListOptions)
if err != nil {
return errors.Wrap(err, "failed to list pods")
}
Expand Down

0 comments on commit 8fe64d0

Please sign in to comment.