{"id":19838505,"url":"https://github.com/metal-stack/go-ipam","last_synced_at":"2025-05-16T06:04:46.380Z","repository":{"id":37919287,"uuid":"183595314","full_name":"metal-stack/go-ipam","owner":"metal-stack","description":"golang grpc service and library for ip address management","archived":false,"fork":false,"pushed_at":"2025-04-08T11:28:22.000Z","size":735,"stargazers_count":135,"open_issues_count":15,"forks_count":42,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-12T04:44:29.878Z","etag":null,"topics":["golang","grpc","ipaddress","ipam","networking","protobuf"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/metal-stack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-04-26T09:02:29.000Z","updated_at":"2025-04-11T01:55:23.000Z","dependencies_parsed_at":"2023-02-14T16:15:24.906Z","dependency_job_id":"cf38c563-5188-48c0-a3c9-0507a57cc70f","html_url":"https://github.com/metal-stack/go-ipam","commit_stats":null,"previous_names":["metal-pod/go-ipam"],"tags_count":61,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metal-stack%2Fgo-ipam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metal-stack%2Fgo-ipam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metal-stack%2Fgo-ipam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metal-stack%2Fgo-ipam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/metal-stack","download_url":"https://codeload.github.com/metal-stack/go-ipam/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254478186,"owners_count":22077675,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["golang","grpc","ipaddress","ipam","networking","protobuf"],"created_at":"2024-11-12T12:17:59.102Z","updated_at":"2025-05-16T06:04:46.361Z","avatar_url":"https://github.com/metal-stack.png","language":"Go","readme":"# go-ipam\n\n[![Actions](https://github.com/metal-stack/go-ipam/actions/workflows/docker.yml/badge.svg?branch=master)](https://github.com/metal-stack/go-ipam/actions)\n[![GoDoc](https://godoc.org/github.com/metal-stack/go-ipam?status.svg)](https://godoc.org/github.com/metal-stack/go-ipam)\n[![Go Report Card](https://goreportcard.com/badge/github.com/metal-stack/go-ipam)](https://goreportcard.com/report/github.com/metal-stack/go-ipam)\n[![codecov](https://codecov.io/gh/metal-stack/go-ipam/branch/master/graph/badge.svg)](https://codecov.io/gh/metal-stack/go-ipam)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/metal-stack/go-ipam/blob/master/LICENSE)\n\ngo-ipam is a module to handle IP address management. It can operate on networks, prefixes and IPs.\n\nIt also comes as a ready to go microservice which offers a grpc api.\n\n## IP\n\nMost obvious this library is all about IP management. The main purpose is to acquire and release an IP, or a bunch of\nIP's from prefixes.\n\n## Prefix\n\nA prefix is a network with IP and mask, typically in the form of *192.168.0.0/24*. To be able to manage IPs you have to create a prefix first.\n\nLibrary Example usage:\n\n```go\n\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n    \"time\"\n\n    goipam \"github.com/metal-stack/go-ipam\"\n)\n\nfunc main() {\n    // The background context\n    bgCtx := context.Background()\n\n    // Create a ipamer with in memory storage\n    ipam := goipam.New(bgCtx)\n\n    // Optionally, we can pass around a context for a given namespace\n    namespace := \"tenant-a\"\n    err := ipam.CreateNamespace(bgCtx, namespace)\n    if err != nil {\n        panic(err)\n    }\n    ctx := goipam.NewContextWithNamespace(bgCtx, namespace)\n    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)\n    defer cancel()\n\n    // Create a prefix to manage some IPs\n    prefix, err := ipam.NewPrefix(ctx, \"192.168.0.0/24\")\n    if err != nil {\n        panic(err)\n    }\n\n    // Acquire and release an IP with this prefix\n    ip, err := ipam.AcquireIP(ctx, prefix.Cidr)\n    if err != nil {\n        panic(err)\n    }\n    fmt.Printf(\"got IP: %s\\n\", ip.IP)\n\n    prefix, err = ipam.ReleaseIP(ctx, ip)\n    if err != nil {\n        panic(err)\n    }\n    fmt.Printf(\"IP: %s released.\\n\", ip.IP)\n\n    // Now a IPv6 Super Prefix with Child Prefixes\n    prefix, err = ipam.NewPrefix(ctx, \"2001:aabb::/48\")\n    if err != nil {\n        panic(err)\n    }\n\n    cp1, err := ipam.AcquireChildPrefix(ctx, prefix.Cidr, 64)\n    if err != nil {\n        panic(err)\n    }\n    fmt.Printf(\"got Prefix: %s\\n\", cp1)\n\n    cp2, err := ipam.AcquireChildPrefix(ctx, prefix.Cidr, 72)\n    if err != nil {\n        panic(err)\n    }\n    fmt.Printf(\"got Prefix: %s\\n\", cp2)\n    ip21, err := ipam.AcquireIP(ctx, cp2.Cidr)\n    if err != nil {\n        panic(err)\n    }\n    fmt.Printf(\"got IP: %s\\n\", ip21.IP)\n}\n```\n\n## GRPC Service\n\nFirst start the go-ipam container with the database backend of your choice already up and running. For example if you have a postgres database for storing the ipam data, you could run the grpc service like so:\n\n```bash\ndocker run -it --rm ghcr.io/metal-stack/go-ipam postgres\n```\n\nFrom a client perspective you can now talk to this service via grpc.\n\nGRPC Example usage:\n\n```go\npackage main\n\nimport (\n    \"http\"\n\n    \"github.com/bufbuild/connect-go\"\n    v1 \"github.com/metal-stack/go-ipam/api/v1\"\n    \"github.com/metal-stack/go-ipam/api/v1/apiv1connect\"\n)\nfunc main() {\n\n    c := apiv1connect.NewIpamServiceClient(\n            http.DefaultClient,\n            \"http://localhost:9090\",\n            connect.WithGRPC(),\n    )\n\n    bgCtx := context.Background()\n\n    // Optional with Namespace\n    ctx := goipam.NewContextWithNamespace(bgCtx, \"tenant-a\")\n\n    result, err := c.CreatePrefix(ctx, connect.NewRequest(\u0026v1.CreatePrefixRequest{Cidr: \"192.168.0.0/16\",}))\n    if err != nil {\n        panic(err)\n    }\n    fmt.Println(\"Prefix:%q created\", result.Msg.GetPrefix().GetCidr())\n}\n```\n\n## GRPC client\n\nThere is also a `cli` provided in the container which can be used to make calls to the grpc endpoint manually:\n\n```bash\ndocker run -it --rm --entrypoint /cli ghcr.io/metal-stack/go-ipam\n```\n\n## Metrics\n\n```bash\nhttp://localhost:2112/metrics\n```\n\n## pprof\n\n```bash\ngo tool pprof -http :8080 localhost:2113/debug/pprof/heap\ngo tool pprof -http :8080 localhost:2113/debug/pprof/goroutine\n```\n\n## Docker Compose example\n\nEnsure you have docker with compose support installed. Then execute the following command:\n\n```bash\ndocker compose up -d\n\n# check if up and running\ndocker compose ps\n\nNAME                 IMAGE             COMMAND                  SERVICE    CREATED          STATUS                    PORTS\ngo-ipam-ipam-1       go-ipam           \"/server postgres\"       ipam       14 seconds ago   Up 13 seconds (healthy)   0.0.0.0:9090-\u003e9090/tcp, :::9090-\u003e9090/tcp\ngo-ipam-postgres-1   postgres:alpine   \"docker-entrypoint.s…\"   postgres   8 minutes ago    Up 13 seconds             5432/tcp\n\n\n# Then execute the cli to create prefixes and acquire ips\n\ndocker compose exec ipam /cli prefix create --cidr 192.168.0.0/16\nprefix:\"192.168.0.0/16\" created\n\ndocker compose exec ipam /cli ip acquire --prefix  192.168.0.0/16\nip:\"192.168.0.1\" acquired\n\n# Queries can also made against the Rest api like so:\n\ncurl -v -X POST -d '{}' -H 'Content-Type: application/json' localhost:9090/api.v1.IpamService/ListPrefixes\n```\n\n## Supported Databases \u0026 Performance\n\n| Database    | Acquire Child Prefix |  Acquire IP |  New Prefix | Prefix Overlap | Production-Ready | Geo-Redundant |\n|:------------|---------------------:|------------:|------------:|---------------:|:-----------------|:--------------|\n| In-Memory   |          106,861/sec | 196,687/sec | 330,578/sec |        248/sec | N                | N             |\n| File        |                      |             |             |                | N                | N             |\n| KeyDB       |              777/sec |     975/sec |   2,271/sec |                | Y                | Y             |\n| Redis       |              773/sec |     958/sec |   2,349/sec |                | Y                | N             |\n| MongoDB     |              415/sec |     682/sec |     772/sec |                | Y                | Y             |\n| Etcd        |              258/sec |     368/sec |     533/sec |                | Y                | N             |\n| Postgres    |              203/sec |     331/sec |     472/sec |                | Y                | N             |\n| CockroachDB |              170/sec |     300/sec |     470/sec |                | Y                | Y             |\n\nThe benchmarks above were performed using:\n\n* cpu: Intel(R) Xeon(R) Platinum 8370C CPU @ 2.80GHz\n* postgres:17-alpine\n* cockroach:v24.1.0\n* redis:7.4-alpine\n* keydb:alpine_x86_64_v6.3.1\n* etcd:v3.5.15\n* mongodb:7\n\n### Database Version Compatibility\n\n| Database    | Details                                                                                                                   |\n|-------------|---------------------------------------------------------------------------------------------------------------------------|\n| KeyDB       |                                                                                                                           |\n| Redis       |                                                                                                                           |\n| MongoDB     | [mongodb-go compatibility](https://www.mongodb.com/docs/drivers/go/current/compatibility/#std-label-golang-compatibility) |\n| Etcd        |                                                                                                                           |\n| Postgres    |                                                                                                                           |\n| CockroachDB |                                                                                                                           |\n\n## Testing individual Backends\n\nIt is possible to test a individual backend only to speed up development roundtrip.\n\n`backend` can be one of `Memory`, `Postgres`, `Cockroach`, `Etcd`, `Redis`, and `MongoDB`.\n\n```bash\nBACKEND=backend make test\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetal-stack%2Fgo-ipam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetal-stack%2Fgo-ipam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetal-stack%2Fgo-ipam/lists"}