Skip to content

Commit 6fd2e75

Browse files
4rivappa4rivappa
committed
feat: add readme and release workflow
- Add LICENSE file
1 parent d1f6332 commit 6fd2e75

File tree

5 files changed

+163
-16
lines changed

5 files changed

+163
-16
lines changed

‎.github/workflows/release.yaml‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*.*.*'
7+
8+
permissions:
9+
contents: write
10+
11+
jobs:
12+
release:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v5
16+
17+
- name: Set up Go
18+
uses: actions/setup-go@v6
19+
with:
20+
go-version: '1.24.2'
21+
22+
- name: Build binaries and create archives
23+
env:
24+
CGO_ENABLED: 0
25+
run: |
26+
mkdir -p bin
27+
VERSION=${GITHUB_REF#refs/tags/}
28+
COMMIT=$(git rev-parse --short HEAD)
29+
DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
30+
LDFLAGS="-X main.version=$VERSION -X main.commit=$COMMIT -X main.date=$DATE"
31+
32+
GOOS=linux GOARCH=amd64 go build -ldflags "$LDFLAGS" -o kubectl-ip_check ./cmd/kubectl-ip-check
33+
tar -czf bin/kubectl-ip-check-linux-amd64.tar.gz kubectl-ip_check LICENSE
34+
rm kubectl-ip_check
35+
36+
GOOS=linux GOARCH=arm64 go build -ldflags "$LDFLAGS" -o kubectl-ip_check ./cmd/kubectl-ip-check
37+
tar -czf bin/kubectl-ip-check-linux-arm64.tar.gz kubectl-ip_check LICENSE
38+
rm kubectl-ip_check
39+
40+
GOOS=darwin GOARCH=amd64 go build -ldflags "$LDFLAGS" -o kubectl-ip_check ./cmd/kubectl-ip-check
41+
tar -czf bin/kubectl-ip-check-darwin-amd64.tar.gz kubectl-ip_check LICENSE
42+
rm kubectl-ip_check
43+
44+
GOOS=darwin GOARCH=arm64 go build -ldflags "$LDFLAGS" -o kubectl-ip_check ./cmd/kubectl-ip-check
45+
tar -czf bin/kubectl-ip-check-darwin-arm64.tar.gz kubectl-ip_check LICENSE
46+
rm kubectl-ip_check
47+
48+
GOOS=windows GOARCH=amd64 go build -ldflags "$LDFLAGS" -o kubectl-ip_check.exe ./cmd/kubectl-ip-check
49+
tar -czf bin/kubectl-ip-check-windows-amd64.tar.gz kubectl-ip_check.exe LICENSE
50+
rm kubectl-ip_check.exe
51+
52+
# Generate checksums
53+
cd bin
54+
sha256sum *.tar.gz > checksums.txt
55+
cat checksums.txt
56+
57+
- name: Create Release
58+
uses: softprops/action-gh-release@v2
59+
with:
60+
files: |
61+
bin/*.tar.gz
62+
bin/checksums.txt
63+
generate_release_notes: true
64+
env:
65+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 kubectl-ip-check
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 76 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,80 @@
1-
## kubectl-ip-check
1+
# kubectl ip-check
22

3-
A kubectl plugin to check ip address resources across the cluster nodes. Provides overall allocated, used and free IPs in cluster.
3+
A kubectl plugin to improve visibility on IP address utilization in EKS clusters with VPC CNI.
44

5-
Example:
5+
![IP Check Img](./img/ip-check.png "ip-check")
6+
7+
## Overview
8+
9+
`ip-check` plugin is designed to check the status of IP addresses in your Kubernetes cluster. It provides visibility into total allocated IPs, used IPs, and free IPs throughout the cluster by fetching details from EC2 instances and analyzing pod IPs on each node.
10+
11+
For each node, the plugin:
12+
- Retrieves total IP addresses from network interfaces attached to EC2 instances
13+
- Counts used IPs from pods that are not using host networking
14+
- Calculates free/unused IP addresses allocated to nodes
15+
16+
**Currently supports:** AWS EKS clusters with VPC CNI
17+
18+
## Installation
19+
20+
### Via Krew (plugin manager)
21+
22+
```bash
23+
# TODO: Will be available via krew once published
24+
kubectl krew install ip-check
625
```
7-
~ $ ./kubectl-ip-check-linux
8-
Allocated IPs: 682 | Used IPs: 170 | Free IPs: 512
9-
10-
NAME INSTANCE-ID INSTANCE-TYPE AVAILABILITY-ZONE INTERNAL-IP TOTAL-IPS USED-IPS FREE-IPS
11-
ip-192-168-10-106.ec2.internal i-064adaf03c2efb4f2 t3.small us-east-1a 192.168.10.106 8 3 5
12-
ip-192-168-101-147.ec2.internal i-04f5d79942c711aa6 m5.2xlarge us-east-1d 192.168.101.147 15 1 14
13-
ip-192-168-103-152.ec2.internal i-01ef79740a15eea5d m5.2xlarge us-east-1d 192.168.103.152 30 5 25
14-
ip-192-168-11-45.ec2.internal i-018fe96ee7b764915 t3.small us-east-1a 192.168.11.45 8 3 5
15-
ip-192-168-11-69.ec2.internal i-00aef0ee2330568cb t3.small us-east-1a 192.168.11.69 8 3 5
16-
ip-192-168-11-73.ec2.internal i-06bdaf3673c7159b9 t3.small us-east-1a 192.168.11.73 8 3 5
17-
ip-192-168-111-254.ec2.internal i-02781e32ca8d3539a m5.2xlarge us-east-1d 192.168.111.254 30 5 25
18-
ip-192-168-116-45.ec2.internal i-03fd3290d4503e43e m5.2xlarge us-east-1d 192.168.116.45 30 5 25
26+
27+
### Manual Installation
28+
29+
1. Download the latest tar zip from the [releases page](https://github.com/4rivappa/kubectl-ip-check/releases)
30+
2. Extract executable and place it in your PATH:
31+
32+
```bash
33+
# Extract executable and move it to your PATH
34+
sudo mv kubectl-ip_check /usr/local/bin/kubectl-ip_check
1935
```
36+
37+
## Motivation
38+
39+
With smaller CIDR ranges in VPC subnets, using default configurations of VPC CNI can quickly exhaust available IP addresses in the network. As shown in the example above, nearly 75-80% of IPs are unused but allocated to nodes in the cluster due to default configuration settings (`WARM_ENI_TARGET`, `WARM_IP_TARGET`).
40+
41+
This plugin helps users:
42+
- **Gain visibility** into IP address usage across the cluster
43+
- **Detect overallocation** in IP allocation
44+
- **Optimize VPC CNI configuration** to mitigate IP exhaustion
45+
- **Plan capacity** for cluster scaling
46+
- **Troubleshoot** IP-related issues
47+
48+
## How It Works
49+
50+
The plugin operates by:
51+
52+
1. **Discovering Nodes**: Uses the Kubernetes API to list all nodes in the cluster
53+
2. **Analyzing ENIs**: Calls AWS EC2 `DescribeNetworkInterfaces` API for each node instance to get total allocated IP addresses
54+
3. **Counting Pod IPs**: Queries Kubernetes API to count pod IPs on each node (excluding host-networked pods)
55+
4. **Calculating Usage**: Computes used vs. free IP addresses per node and aggregates cluster-wide statistics
56+
57+
## Required Permissions
58+
59+
The plugin requires the following permissions to function:
60+
61+
**AWS:**
62+
- `ec2:DescribeNetworkInterfaces` permission for the instances in your cluster
63+
64+
**Kubernetes:**
65+
- Read access to `nodes` and `pods` resources in the cluster
66+
67+
## Configuration
68+
69+
The plugin automatically detects your Kubernetes configuration from:
70+
1. In-cluster service account (when running inside a pod)
71+
2. `~/.kube/config` file
72+
3. `KUBECONFIG` environment variable
73+
74+
AWS credentials are resolved using the standard AWS credential chain:
75+
1. Environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`)
76+
2. AWS credentials file (`~/.aws/credentials`)
77+
78+
## License
79+
80+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

‎cmd/kubectl-ip-check/main.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ import (
1717
func main() {
1818
var rootCmd = &cobra.Command{
1919
Use: "kubectl aws-ip",
20-
Short: "A kubectl plugin to calculate IP addresses usage in AWS EKS nodes",
20+
Short: "plugin to improve visibility on IP address utilization",
2121
Run: run,
2222
}
2323

‎img/ip-check.png‎

477 KB
Loading

0 commit comments

Comments
 (0)