ipam-go

IPAM Go client SDK

Go client for JakeNeyer/ipam. OpenAPI is dumped from the IPAM server reflector, normalized, and compiled with oapi-codegen. The public API is the stable ipam package (domain types); generated bindings stay under internal/api.

Install

go get github.com/JakeNeyer/ipam-go@latest

Usage

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/JakeNeyer/ipam-go/ipam"
)

func main() {
	client, err := ipam.NewFromEnv() // IPAM_ENDPOINT + IPAM_TOKEN
	if err != nil {
		log.Fatal(err)
	}

	envs, err := client.ListEnvironments(context.Background(), nil)
	if err != nil {
		log.Fatal(err)
	}
	for _, e := range envs {
		fmt.Println(e.ID, e.Name)
	}
}

Or bring your own http.Client (timeout, transport, retries):

httpClient := &http.Client{
	Timeout:   60 * time.Second,
	Transport: myRetryTransport, // any http.RoundTripper
}
client, err := ipam.New(os.Getenv("IPAM_ENDPOINT"),
	ipam.WithToken(os.Getenv("IPAM_TOKEN")),
	ipam.WithHTTPClient(httpClient),
)

Create an API token in the IPAM UI (Admin → API tokens) or set IPAM_TOKEN.

Regenerate the client

# Prefer an upstream tag
IPAM_REF=v0.1.1 make generate

# Or track a branch
IPAM_REF=main make generate

make generate dumps OpenAPI from that ref, regenerates internal/api, records openapi/IPAM_REF + openapi/IPAM_SHA, then runs unit tests and e2e against that same SHA.

A weekly GitHub Action polls new tags on JakeNeyer/ipam and opens a PR when the latest tag differs from the pin — see docs/upstream-lifecycle.md and VERSIONING.md.

Examples

See examples/README.md.

export IPAM_ENDPOINT=http://localhost:8011
export IPAM_TOKEN=...
go run ./examples/me
go run ./examples/create-environment
go run ./examples/allocate

Coverage

Wrapped in ipam: environments, pools, blocks, allocations, reserved blocks, block/pool CIDR suggest, usage, me, API tokens, integrations.

Not wrapped (use the IPAM HTTP API directly, or open an issue): setup/login/session cookies, OAuth, admin org/user/invite routes (not in OpenAPI), CSV export.

End-to-end tests

make test-e2e

Builds IPAM at openapi/IPAM_SHA (in-memory store + bootstrap token) unless IPAM_ENDPOINT + IPAM_TOKEN are set.

License

MIT