ipam

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 30, 2023 License: MIT Imports: 23 Imported by: 1

README

go-ipam

Actions GoDoc Go Report Card codecov License

go-ipam is a module to handle IP address management. It can operate on networks, prefixes and IPs.

It also comes as a ready to go microservice which offers a grpc api.

IP

Most obvious this library is all about IP management. The main purpose is to acquire and release an IP, or a bunch of IP's from prefixes.

Prefix

A 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.

Library Example usage:


package main

import (
    "fmt"
    "time"
    goipam "github.com/cicdteam/go-ipam"
)

func main() {
    // create a ipamer with in memory storage
    ipam := goipam.New()

    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    prefix, err := ipam.NewPrefix(ctx, "192.168.0.0/24")
    if err != nil {
        panic(err)
    }

    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)

    // Now a IPv6 Super Prefix with Child Prefixes
    prefix, err = ipam.NewPrefix(ctx, "2001:aabb::/48")
    if err != nil {
        panic(err)
    }
    cp1, err := ipam.AcquireChildPrefix(ctx, prefix.Cidr, 64)
    if err != nil {
        panic(err)
    }
    fmt.Printf("got Prefix: %s\n", cp1)
    cp2, err := ipam.AcquireChildPrefix(ctx, prefix.Cidr, 72)
    if err != nil {
        panic(err)
    }
    fmt.Printf("got Prefix: %s\n", cp2)
    ip21, err := ipam.AcquireIP(ctx, cp2.Cidr)
    if err != nil {
        panic(err)
    }
    fmt.Printf("got IP: %s\n", ip21.IP)
}

GRPC Service

First 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:

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

From a client perspective you can now talk to this service via grpc.

GRPC Example usage:

package main

import (
    "http"

    "github.com/bufbuild/connect-go"
    v1 "github.com/cicdteam/go-ipam/api/v1"
    "github.com/cicdteam/go-ipam/api/v1/apiv1connect"
)
func main() {

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

    result, err := c.CreatePrefix(context.Background(), connect.NewRequest(&v1.CreatePrefixRequest{Cidr: "192.168.0.0/16",}))
    if err != nil {
        panic(err)
    }
    fmt.Println("Prefix:%q created", result.Msg.Prefix.Cidr)
}

GRPC client

There is also a cli provided in the container which can be used to make calls to the grpc endpoint manually:

docker run -it --rm --entrypoint /cli ghcr.io/cicdteam/go-ipam

Supported Databases & Performance

Database Acquire Child Prefix Acquire IP New Prefix Prefix Overlap Production-Ready Geo-Redundant
In-Memory 106,861/sec 196,687/sec 330,578/sec 248/sec N N
KeyDB 777/sec 975/sec 2,271/sec Y Y
Redis 773/sec 958/sec 2,349/sec Y N
MongoDB 415/sec 682/sec 772/sec Y Y
Etcd 258/sec 368/sec 533/sec Y N
Postgres 203/sec 331/sec 472/sec Y N
CockroachDB 170/sec 300/sec 470/sec Y Y
k8s ConfigMap N/A N/A N/A Y Y

The benchmarks above were performed using:

  • cpu: Intel(R) Xeon(R) Platinum 8370C CPU @ 2.80GHz
  • postgres:15-alpine
  • cockroach:v22.2.0
  • redis:7.0-alpine
  • keydb:alpine_x86_64_v6.3.1
  • etcd:v3.5.5
  • mongodb:5.0.13-focal
Database Version Compatability
Database Details
KeyDB
Redis
MongoDB mongodb-go compatibility
Etcd
Postgres
CockroachDB

Testing individual Backends

It is possible to test a individual backend only to speed up development roundtrip.

backend can be one of Memory, Postgres, Cockroach, Etcd, Redis, and MongoDB.

BACKEND=backend make test

Documentation

Overview

Package ipam is a ip address management library for ip's and prefixes (networks).

It uses either memory or postgresql database to store the ip's and prefixes. You can also bring you own Storage implementation as you need.

Example usage: 

import (
	"fmt"
	goipam "github.com/cicdteam/go-ipam"
)

func main() {
	// create a ipamer with in memory storage
	ipam := goipam.New()

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

	ip, err := ipam.AcquireIP(prefix)
	if err != nil {
		panic(err)
	}
	fmt.Printf("got IP: %s", ip.IP)

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

Index

Constants

View Source 
const (
	// SSLModeAllow I don't care about security
	// but I will pay the overhead of encryption if the server insists on it
	SSLModeAllow = SSLMode("allow")
	// SSLModeDisable I don't care about security
	// and I don't want to pay the overhead of encryption.
	SSLModeDisable = SSLMode("disable")
	// SSLModePrefer I don't care about encryption
	// but I wish to pay the overhead of encryption if the server supports it.
	SSLModePrefer = SSLMode("prefer")
	// SSLModeRequire I want my data to be encrypted and I accept the overhead.
	// I trust that the network will make sure I always connect to the server I want.
	SSLModeRequire = SSLMode("require")
	// SSLModeVerifyCA I want my data encrypted and I accept the overhead.
	// I want to be sure that I connect to a server that I trust.
	SSLModeVerifyCA = SSLMode("verify-ca")
	// SSLModeVerifyFull I want my data encrypted and I accept the overhead.
	// I want to be sure that I connect to a server I trust, and that it's the one I specify.
	SSLModeVerifyFull = SSLMode("verify-full")
)

Variables

View Source 
var (
	// ErrNotFound is returned if prefix or cidr was not found
	ErrNotFound NotFoundError
	// ErrNoIPAvailable is returned if no IP is available anymore
	ErrNoIPAvailable NoIPAvailableError
	// ErrAlreadyAllocated is returned if the requested address is not available
	ErrAlreadyAllocated AlreadyAllocatedError
	// ErrOptimisticLockError is returned if insert or update conflicts with the existing data
	ErrOptimisticLockError OptimisticLockError
)

Functions

func PrefixesOverlapping 

func PrefixesOverlapping(existingPrefixes []string, newPrefixes []string) error

PrefixesOverlapping will check if one ore more prefix of newPrefixes is overlapping with one of existingPrefixes

Types

type AlreadyAllocatedError 

type AlreadyAllocatedError struct {
}

AlreadyAllocatedError is raised if the given address is already in use

func (AlreadyAllocatedError) Error 

func (o AlreadyAllocatedError) Error() string

type IP 

type IP struct {
	IP           netip.Addr
	ParentPrefix string
}

IP is a single ipaddress.

type Ipamer 

type Ipamer interface {
	// NewPrefix create a new Prefix from a string notation.
	NewPrefix(ctx context.Context, cidr string) (*Prefix, error)
	// DeletePrefix delete a Prefix from a string notation.
	// If the Prefix is not found an NotFoundError is returned.
	DeletePrefix(ctx context.Context, cidr string) (*Prefix, error)
	// AcquireChildPrefix will return a Prefix with a smaller length from the given Prefix.
	AcquireChildPrefix(ctx context.Context, parentCidr string, length uint8) (*Prefix, error)
	// AcquireSpecificChildPrefix will return a Prefix with a smaller length from the given Prefix.
	AcquireSpecificChildPrefix(ctx context.Context, parentCidr, childCidr string) (*Prefix, error)
	// ReleaseChildPrefix will mark this child Prefix as available again.
	ReleaseChildPrefix(ctx context.Context, child *Prefix) error
	// PrefixFrom will return a known Prefix.
	PrefixFrom(ctx context.Context, 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(ctx context.Context, prefixCidr, specificIP string) (*IP, error)
	// AcquireIP will return the next unused IP from this Prefix.
	AcquireIP(ctx context.Context, 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(ctx context.Context, ip *IP) (*Prefix, error)
	// ReleaseIPFromPrefix will release the given IP for later usage.
	// If the Prefix or the IP is not found an NotFoundError is returned.
	ReleaseIPFromPrefix(ctx context.Context, prefixCidr, ip string) error
	// Dump all stored prefixes as json formatted string
	Dump(ctx context.Context) (string, error)
	// Load a previously created json formatted dump, deletes all prefixes before loading
	Load(ctx context.Context, dump string) error
	// ReadAllPrefixCidrs retrieves all existing Prefix CIDRs from the underlying storage
	ReadAllPrefixCidrs(ctx context.Context) ([]string, error)
}

Ipamer can be used to do IPAM stuff.

func New 

func New() Ipamer

New returns a Ipamer with in memory storage for networks, prefixes and ips.

func NewWithStorage 

func NewWithStorage(storage Storage) Ipamer

NewWithStorage allows you to create a Ipamer instance with your Storage implementation. The Storage interface must be implemented.

type MongoConfig 

type MongoConfig struct {
	DatabaseName       string
	CollectionName     string
	MongoClientOptions *options.ClientOptions
}

type NoIPAvailableError 

type NoIPAvailableError struct {
}

NoIPAvailableError indicates that the acquire-operation could not be executed because the specified prefix has no free IP anymore.

func (NoIPAvailableError) Error 

func (o NoIPAvailableError) Error() string

type NotFoundError 

type NotFoundError struct {
}

NotFoundError is raised if the given Prefix or Cidr was not found

func (NotFoundError) Error 

func (o NotFoundError) Error() string

type OptimisticLockError 

type OptimisticLockError struct {
}

OptimisticLockError indicates that the operation could not be executed because the dataset to update has changed in the meantime. clients can decide to read the current dataset and retry the operation.

func (OptimisticLockError) Error 

func (o OptimisticLockError) Error() string

type Prefix 

type Prefix struct {
	Cidr       string // The Cidr of this prefix
	ParentCidr string // if this prefix is a child this is a pointer back
	// contains filtered or unexported fields
}

Prefix is a expression of a ip with length and forms a classless network.

func (*Prefix) GobDecode 

func (p *Prefix) GobDecode(buf []byte) error

GobDecode implements GobDecode for Prefix

func (*Prefix) GobEncode 

func (p *Prefix) GobEncode() ([]byte, error)

GobEncode implements GobEncode for Prefix

func (*Prefix) Network 

func (p *Prefix) Network() (netip.Addr, error)

Network return the net.IP part of the Prefix

func (*Prefix) String 

func (p *Prefix) String() string

func (*Prefix) Usage 

func (p *Prefix) Usage() Usage

Usage report Prefix usage.

type Prefixes 

type Prefixes []Prefix

type SSLMode 

type SSLMode string

SSLMode specifies how to configure ssl encryption to the database

func (SSLMode) String 

func (s SSLMode) String() string

type Storage 

type Storage interface {
	Name() string
	CreatePrefix(ctx context.Context, prefix Prefix) (Prefix, error)
	ReadPrefix(ctx context.Context, prefix string) (Prefix, error)
	DeleteAllPrefixes(ctx context.Context) error
	ReadAllPrefixes(ctx context.Context) (Prefixes, error)
	ReadAllPrefixCidrs(ctx context.Context) ([]string, error)
	UpdatePrefix(ctx context.Context, prefix Prefix) (Prefix, error)
	DeletePrefix(ctx context.Context, prefix Prefix) (Prefix, error)
}

Storage is a interface to store ipam objects.

func NewConfigmap 

func NewConfigmap(cmName string, cacheInternally bool) Storage

NewConfigmap create a redis storage for ipam

func NewEtcd 

func NewEtcd(ip, port string, cert, key []byte, insecureskip bool) Storage

NewEtcd create a etcd storage for ipam

func NewMemory 

func NewMemory() Storage

NewMemory create a memory storage for ipam

func NewMongo 

func NewMongo(ctx context.Context, config MongoConfig) (Storage, error)

func NewPostgresStorage 

func NewPostgresStorage(host, port, user, password, dbname string, sslmode SSLMode) (Storage, error)

NewPostgresStorage creates a new Storage which uses postgres.

func NewRedis 

func NewRedis(ip, port string) Storage

NewRedis create a redis storage for ipam

type Usage 

type Usage struct {
	// AvailableIPs the number of available IPs if this is not a parent prefix
	// No more than 2^31 available IPs are reported
	AvailableIPs uint64
	// AcquiredIPs the number of acquired IPs if this is not a parent prefix
	AcquiredIPs uint64
	// AvailableSmallestPrefixes is the count of available Prefixes with 2 countable Bits
	// No more than 2^31 available Prefixes are reported
	AvailableSmallestPrefixes uint64
	// AvailablePrefixes is a list of prefixes which are available
	AvailablePrefixes []string
	// AcquiredPrefixes the number of acquired prefixes if this is a parent prefix
	AcquiredPrefixes uint64
}

Usage of ips and child Prefixes of a Prefix

func (*Usage) String 

func (u *Usage) String() string

Source Files

View all Source files

Directories

Path Synopsis
api
v1
v1/apiv1connect
cmd
client
server
pkg
service

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.