go-ipam IP Address Management

The project can be run as a standalone microservice providing a gRPC API.

Running the service

Start the container with your chosen database backend. For example, using Postgres:

docker run -it --rm ghcr.io/metal-stack/go-ipam postgres

Client implementation

Use the generated gRPC client to interact with the service. You can specify a namespace using goipam.NewContextWithNamespace to ensure requests are scoped correctly.

package main

import (
    "context"
    "http"

    v1 "github.com/metal-stack/go-ipam/api/v1"
    "github.com/metal-stack/go-ipam/api/v1/apiv1connect"
)

func main() {
    c := apiv1connect.NewIpamServiceClient(
            http.DefaultClient,
            "http://localhost:9090",
            connect.WithGRPC(),
    )

    bgCtx := context.Background()
    // Optional with Namespace
    ctx := goipam.NewContextWithNamespace(bgCtx, "tenant-a")

    result, err := c.CreatePrefix(ctx, &v1.CreatePrefixRequest{Cidr: "192.168.0.0/16"})
    if err != nil {
        panic(err)
    }
    fmt.Println("Prefix:%q created", result.GetPrefix().GetCidr())
}

You can use go-ipam as a Go module to manage networks, prefixes, and IP addresses. The library supports namespaces to isolate IP management for different tenants.

Key operations include:

• New(ctx): Initializes an ipamer (e.g., with in-memory storage).
• CreateNamespace(ctx, name): Creates a new namespace.
• NewContextWithNamespace(ctx, name): Returns a new context associated with a specific namespace.
• NewPrefix(ctx, cidr): Creates a new prefix (e.g., 192.168.0.0/24).
• AcquireIP(ctx, cidr): Acquires an IP from the specified prefix.
• ReleaseIP(ctx, ip): Releases an acquired IP back to its prefix.
• AcquireChildPrefix(ctx, cidr, mask): Acquires a sub-prefix from an existing prefix (useful for IPv6 management).

package main

import (
    "context"
    "fmt"
    "time"

    goipam "github.com/metal-stack/go-ipam"
)

func main() {
    bgCtx := context.Background()
    ipam := goipam.New(bgCtx)

    namespace := "tenant-a"
    err := ipam.CreateNamespace(bgCtx, namespace)
    if err != nil {
        panic(err)
    }
    ctx := goipam.NewContextWithNamespace(bgCtx, namespace)
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()

    // Create a prefix
    prefix, err := ipam.NewPrefix(ctx, "192.168.0.0/24")
    if err != nil {
        panic(err)
    }

    // Acquire and release an IP
    ip, err := ipam.AcquireIP(ctx, prefix.Cidr)
    if err != nil {
        panic(err)
    }
    fmt.Printf("got IP: %s\n", ip.IP)

    prefix, err = ipam.ReleaseIP(ctx, ip)
    if err != nil {
        panic(err)
    }
    fmt.Printf("IP: %s released.\n", ip.IP)
}

The file implementation satisfies the Storage interface. When using NewLocalFile, you can perform standard IPAM operations which are automatically persisted to the JSON file.

Note on Synchronization: The provider uses a reload() mechanism. Before any read or write operation, it checks if the file's modification time has changed. If it has, it reloads the file content into memory to ensure consistency. Write operations (Create, Update, Delete) are followed by a persist() call to save the updated state back to disk.

// Example operations on the Storage interface
// Create a new prefix in a namespace
newPrefix, err := storage.CreatePrefix(ctx, prefix, "my-namespace")

// Read a prefix
prefix, err := storage.ReadPrefix(ctx, prefix, "my-namespace")

// List all namespaces
namespaces, err := storage.ListNamespaces(ctx)

// Delete a namespace
err := storage.DeleteNamespace(ctx, "my-namespace")

The Ipamer interface provides the core functionality for managing IP addresses and prefixes. It supports creating new prefixes, acquiring/releasing IPs, and managing child prefixes (subnets) with specific bitlengths. The library is IPv6 compatible and uses inet.af/netaddr for high-performance network manipulation.

type Ipamer interface {
    // NewPrefix create a new Prefix from a string notation.
    NewPrefix(cidr string) (*Prefix, error)
    // DeletePrefix delete a Prefix from a string notation.
    // If the Prefix is not found an NotFoundError is returned.
    DeletePrefix(cidr string) (*Prefix, error)
    // AcquireChildPrefix will return a Prefix with a smaller length from the given Prefix.
    AcquireChildPrefix(parentCidr string, length uint8) (*Prefix, error)
    // ReleaseChildPrefix will mark this child Prefix as available again.
    ReleaseChildPrefix(child *Prefix) error
    // PrefixFrom will return a known Prefix.
    PrefixFrom(cidr string) *Prefix
    // AcquireSpecificIP will acquire given IP and mark this IP as used, if already in use, return nil.
    // If specificIP is empty, the next free IP is returned.
    // If there is no free IP an NoIPAvailableError is returned.
    AcquireSpecificIP(prefixCidr, specificIP string) (*IP, error)
    // AcquireIP will return the next unused IP from this Prefix.
    AcquireIP(prefixCidr string) (*IP, error)
    // ReleaseIP will release the given IP for later usage and returns the updated Prefix.
    // If the IP is not found an NotFoundError is returned.
    ReleaseIP(ip *IP) (*Prefix, error)
    // ReleaseIPFromPrefix will release the given IP for later usage.
    ReleaseIPFromPrefix(prefixCidr, ip string) error
}