https://github.com/planetscale/cloudranger
Go library for mapping IP address ranges to cloud provider regions (currently: AWS and GCP)
https://github.com/planetscale/cloudranger
Last synced: 3 months ago
JSON representation
Go library for mapping IP address ranges to cloud provider regions (currently: AWS and GCP)
- Host: GitHub
- URL: https://github.com/planetscale/cloudranger
- Owner: planetscale
- License: apache-2.0
- Created: 2023-11-26T18:11:32.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2026-03-30T04:27:16.000Z (3 months ago)
- Last Synced: 2026-03-30T06:51:09.272Z (3 months ago)
- Language: Go
- Homepage:
- Size: 4.53 MB
- Stars: 23
- Watchers: 2
- Forks: 2
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# cloudranger
`cloudranger` is a Go library designed to identify cloud provider information from IP addresses, with current support for AWS and GCP.
It functions without any external runtime dependencies, as IP range data is stored internally. Meant for high throughput, low-latency environments, `cloudranger` also focuses on rapid startup, loading in under 4ms. You can verify this on your system by running `make bench` and checking the `BenchmarkNew` results.
New releases are automatically created in response to updates in cloud providers' IP range information. This process, facilitated through GitHub Actions, is executed weekly to ensure the library remains up-to-date.
The inspiration for `cloudranger` came from a similar library found at https://github.com/kubernetes/registry.k8s.io, used by the Kubernetes OCI registry for redirecting requests to the appropriate cloud provider. We developed `cloudranger` to provide a standalone library adaptable for various projects, offering greater control for our specific use cases and minimizing the impact of upstream changes. Unlike the original project, which uses its own trie implementation, `cloudranger` depends on github.com/infobloxopen/go-trees. While both implementations have not been directly benchmarked against each other, their performance is expected to be comparable.
## Usage
```sh
go get github.com/planetscale/cloudranger
```
```go
package main
import (
"fmt"
"github.com/planetscale/cloudranger"
)
func main() {
ranger := cloudranger.New()
ipinfo, found := ranger.GetIP("3.5.140.101")
if found {
fmt.Printf("cloud: %s, region: %s\n", ipinfo.Cloud(), ipinfo.Region())
}
}
```
A small cli is included in [cmd/cloudranger](cmd/cloudranger). It is EXPERIMENTAL and its behavior, flags, and output is likely to change.
```sh
$ go run cmd/cloudranger/main.go 3.5.140.101
{"cloud":"AWS","region":"ap-northeast-2"}
```
## Testing and Benchmarks
```sh
make lint
make test
make bench
```
```
goos: linux
goarch: amd64
pkg: github.com/planetscale/cloudranger
cpu: AMD EPYC 7B12
BenchmarkNew-16 396 3153591 ns/op 1084213 B/op 26089 allocs/op
BenchmarkGetIP-16 6268292 194.8 ns/op 64 B/op 2 allocs/op
```
## IP Range Database Updates
IP range data is sourced from:
- AWS: https://ip-ranges.amazonaws.com/ip-ranges.json
- GCP: https://www.gstatic.com/ipranges/cloud.json
A GitHub Actions workflow is run weekly to update the IP range data if changed by the supported cloud providers. A new version is created and tagged if changes are detected. Use dependabot or renovate to automate updates to the latest version.