ipam

package module
v1.5.1-0...-45245c1 Latest Latest
Warning

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

Go to latest
Published: Jun 15, 2020 License: MIT Imports: 12 Imported by: 0

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.

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.

Example usage:


package main

import (
    "fmt"
    goipam "github.com/metal-stack/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.Cidr)
    if err != nil {
        panic(err)
    }
    fmt.Printf("got IP: %s", ip.IP)

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

Performance

BenchmarkNewPrefixMemory-4               1000000              1637 ns/op             728 B/op         27 allocs/op
BenchmarkNewPrefixPostgres-4                 200           8611579 ns/op            6170 B/op        155 allocs/op
BenchmarkAcquireIPMemory-4               1000000              1234 ns/op             232 B/op         15 allocs/op
BenchmarkAcquireIPPostgres-4                 200          11583345 ns/op            7252 B/op        184 allocs/op
BenchmarkAcquireChildPrefix1-4            300000              3771 ns/op            1528 B/op         58 allocs/op
BenchmarkAcquireChildPrefix2-4            300000              3773 ns/op            1528 B/op         58 allocs/op
BenchmarkAcquireChildPrefix3-4            300000              3997 ns/op            1541 B/op         58 allocs/op
BenchmarkAcquireChildPrefix4-4            300000              4877 ns/op            1581 B/op         60 allocs/op
BenchmarkAcquireChildPrefix5-4            200000              5541 ns/op            1854 B/op         70 allocs/op
BenchmarkAcquireChildPrefix6-4            300000              4123 ns/op            1528 B/op         58 allocs/op
BenchmarkAcquireChildPrefix7-4            300000              4954 ns/op            1528 B/op         58 allocs/op
BenchmarkAcquireChildPrefix8-4            300000              5017 ns/op            1528 B/op         58 allocs/op
BenchmarkAcquireChildPrefix9-4            300000              5309 ns/op            1528 B/op         58 allocs/op
BenchmarkAcquireChildPrefix10-4           200000              5234 ns/op            1532 B/op         58 allocs/op
BenchmarkPrefixOverlapping-4             1000000              1934 ns/op             432 B/op         24 allocs/op

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/metal-stack/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
)

Functions

func JitterDelay

func JitterDelay(_ uint, config *retry.Config) time.Duration

JitterDelay is a DelayType which varies delay in each iterations

func NewMemory

func NewMemory() *memory

NewMemory create a memory storage for ipam

func NewPostgresStorage

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

NewPostgresStorage creates a new Storage which uses postgres.

Types

type IP

type IP struct {
	IP           net.IP
	ParentPrefix string
}

IP is a single ipaddress.

type Ipamer

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 int) (*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.
	// If the Prefix or the IP is not found an NotFoundError is returned.
	ReleaseIPFromPrefix(prefixCidr, ip string) error
	// PrefixesOverlapping will check if one ore more prefix of newPrefixes is overlapping
	// with one of existingPrefixes
	PrefixesOverlapping(existingPrefixes []string, newPrefixes []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 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 {
	// contains filtered or unexported fields
}

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) DeepCopy

func (p Prefix) DeepCopy() *Prefix

DeepCopy to a new Prefix

func (*Prefix) IPNet

func (p *Prefix) IPNet() (*net.IPNet, error)

IPNet return the net.IPNet part of the Prefix

func (*Prefix) Network

func (p *Prefix) Network() (net.IP, 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 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 {
	CreatePrefix(prefix Prefix) (Prefix, error)
	ReadPrefix(prefix string) (Prefix, error)
	ReadAllPrefixes() ([]Prefix, error)
	UpdatePrefix(prefix Prefix) (Prefix, error)
	DeletePrefix(prefix Prefix) (Prefix, error)
}

Storage is a interface to store ipam objects.

type Usage

type Usage struct {
	AvailableIPs      uint64
	AcquiredIPs       uint64
	AvailablePrefixes uint64
	AcquiredPrefixes  uint64
}

Usage of ips and child Prefixes of a Prefix

func (*Usage) String

func (u *Usage) String() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL