ipam

package module
v1.7.1 Latest Latest
Warning

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

 Go to latest Published: Jul 15, 2020 License: MIT Imports: 16 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 Cleanable 

type Cleanable interface {
	// contains filtered or unexported methods
}

Cleanable interface for impls that support cleaning before each testrun

type ExtendedSQL 

type ExtendedSQL struct {
	// contains filtered or unexported fields
}

ExtendedSQL extended sql interface

func (ExtendedSQL) CreatePrefix 

func (s ExtendedSQL) CreatePrefix(prefix Prefix) (Prefix, error)

func (ExtendedSQL) DeletePrefix 

func (s ExtendedSQL) DeletePrefix(prefix Prefix) (Prefix, error)

func (ExtendedSQL) ReadAllPrefixes 

func (s ExtendedSQL) ReadAllPrefixes() ([]Prefix, error)

func (ExtendedSQL) ReadPrefix 

func (s ExtendedSQL) ReadPrefix(prefix string) (Prefix, error)

func (ExtendedSQL) UpdatePrefix 

func (s ExtendedSQL) UpdatePrefix(prefix Prefix) (Prefix, error)

UpdatePrefix tries to update the prefix. Returns OptimisticLockError if it does not succeed due to a concurrent update.

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
	AvailableChildPrefixes map[string]bool // available child prefixes of this prefix
	ChildPrefixLength      int             // the length of the child prefixes
	IPs                    map[string]bool // The IPs contained in this prefix
	// 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 StorageProvider 

type StorageProvider struct {
	// contains filtered or unexported fields
}

StorageProvider provides different storages

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

Source Files

View all Source files

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.