ipam

README

ipam

ipam provides functionality for IP Address Management.

Documentation

Overview

ipam provides IP address management functionality.

Example

This example demonstrates how the IPAM service can be used to dynamically manage subnets within a larger network.

ctx := context.Background()

// Construct a new IPAM service.
logger := microloggertest.New()
storage, _ := memory.New(memory.Config{})
_, network, _ := net.ParseCIDR("10.4.0.0/16")

config := Config{
	Logger:  logger,
	Storage: storage,
	Network: network,
}

service, _ := New(config)

// Request a subnet. There are no subnets in the network currently,
// so this subnet will be at the start of the IP range.
firstNetwork, _ := service.CreateSubnet(ctx, net.CIDRMask(24, 32), "arbitrary value", nil)
fmt.Println(firstNetwork.String())

// Request a second, smaller subnet.
// There is one subnet currently, so this subnet will begin after
// the previous subnet.
secondNetwork, _ := service.CreateSubnet(ctx, net.CIDRMask(32, 32), "", nil)
fmt.Println(secondNetwork.String())

// Release the first subnet from the service.
// This makes the IP range available for future operations.
_ = service.DeleteSubnet(ctx, firstNetwork)

// Request a third subnet.
// As the range at the start of the network is free,
// and this subnet fits in the space,
// it will be placed there.
thirdNetwork, _ := service.CreateSubnet(ctx, net.CIDRMask(25, 32), "", nil)
fmt.Println(thirdNetwork.String())

// Request a fourth subnet.
// As 2 /25s fit within a /24, both this subnet and the previous
// subnet fit in the space of the older /24.
fourthNetwork, _ := service.CreateSubnet(ctx, net.CIDRMask(25, 32), "", nil)
fmt.Println(fourthNetwork.String())

Output:

10.4.0.0/24
10.4.1.0/32
10.4.0.0/25
10.4.0.128/25

Index

• func CalculateParent(n net.IPNet) net.IPNet
• func CalculateSubnetMask(networkMask net.IPMask, n uint) (net.IPMask, error)
• func CanonicalizeSubnets(networkRange net.IPNet, subnets []net.IPNet) []net.IPNet
• func Contains(network, subnet net.IPNet) bool
• func Filter(networks []net.IPNet, f func(n net.IPNet) bool) []net.IPNet
• func Free(network net.IPNet, mask net.IPMask, subnets []net.IPNet) (net.IPNet, error)
• func Half(network net.IPNet) (first, second net.IPNet, err error)
• func IsIPNotContained(err error) bool
• func IsIncorrectNumberOfBoundaries(err error) bool
• func IsIncorrectNumberOfFreeRanges(err error) bool
• func IsInvalidConfig(err error) bool
• func IsInvalidParameter(err error) bool
• func IsMaskIncorrectSize(err error) bool
• func IsMaskTooBig(err error) bool
• func IsNilIP(err error) bool
• func IsSpaceExhausted(err error) bool
• func Split(network net.IPNet, n uint) ([]net.IPNet, error)
• type Config
• type Service
  • func New(config Config) (*Service, error)
  • func (s *Service) CreateSubnet(ctx context.Context, mask net.IPMask, annotation string, reserved []net.IPNet) (net.IPNet, error)
  • func (s *Service) DeleteSubnet(ctx context.Context, subnet net.IPNet) error

Examples

• Package
• Free
• Half

Functions

func CalculateParent

func CalculateParent(n net.IPNet) net.IPNet

CalculateParent takes network as an input and returns one with 1 bit smaller mask (yielding therefore 1 bit larger network).

func CalculateSubnetMask

func CalculateSubnetMask(networkMask net.IPMask, n uint) (net.IPMask, error)

CalculateSubnetMask calculates new subnet mask to accommodate n subnets.

func CanonicalizeSubnets

func CanonicalizeSubnets(networkRange net.IPNet, subnets []net.IPNet) []net.IPNet

CanonicalizeSubnets iterates over subnets and returns deduplicated list of networks that belong to networkRange. Subnets that overlap each other but aren't exactly the same are not removed. Subnets are returned in the same order as they appear in input.

Example:

networkRange: 192.168.2.0/24
subnets: [172.168.2.0/25, 192.168.2.0/25, 192.168.3.128/25, 192.168.2.0/25, 192.168.2.128/25]
returned: [192.168.2.0/25, 192.168.2.128/25]

Example 2:

networkRange: 10.0.0.0/8
subnets: [10.1.0.0/16, 10.1.0.0/24, 10.1.1.0/24]
returned: [10.1.0.0/16, 10.1.0.0/24, 10.1.1.0/24]

func Contains

func Contains(network, subnet net.IPNet) bool

Contains returns true when the subnet is a part of the network, false otherwise.

func Filter

func Filter(networks []net.IPNet, f func(n net.IPNet) bool) []net.IPNet

Filter is basic functional filter function which iterates over given networks and returns ones that yield true with given filter function.

func Free

func Free(network net.IPNet, mask net.IPMask, subnets []net.IPNet) (net.IPNet, error)

Free takes a network, a mask, and a list of subnets. An available network, within the first network, is returned.

Example

_, network, _ := net.ParseCIDR("10.4.0.0/16")

firstSubnet, _ := Free(*network, net.CIDRMask(24, 32), []net.IPNet{})
fmt.Println(firstSubnet.String())

secondSubnet, _ := Free(*network, net.CIDRMask(28, 32), []net.IPNet{firstSubnet})
fmt.Println(secondSubnet.String())

thirdSubnet, _ := Free(*network, net.CIDRMask(24, 32), []net.IPNet{firstSubnet, secondSubnet})
fmt.Println(thirdSubnet.String())

Output:

10.4.0.0/24
10.4.1.0/28
10.4.2.0/24

func Half

func Half(network net.IPNet) (first, second net.IPNet, err error)

Half takes a network and returns two subnets which split the network in half.

Example

_, network, _ := net.ParseCIDR("10.4.0.0/16")

firstNetwork, secondNetwork, _ := Half(*network)

fmt.Println(firstNetwork.String())
fmt.Println(secondNetwork.String())

Output:

10.4.0.0/17
10.4.128.0/17

func IsIPNotContained

func IsIPNotContained(err error) bool

IsIPNotContained asserts ipNotContainedError.

func IsIncorrectNumberOfBoundaries

func IsIncorrectNumberOfBoundaries(err error) bool

IsIncorrectNumberOfBoundaries asserts incorrectNumberOfBoundariesError.

func IsIncorrectNumberOfFreeRanges

func IsIncorrectNumberOfFreeRanges(err error) bool

IsIncorrectNumberOfFreeRangesError asserts incorrectNumberOfFreeRangesError.

func IsInvalidConfig

func IsInvalidConfig(err error) bool

IsInvalidConfig asserts invalidConfigError.

func IsInvalidParameter

func IsInvalidParameter(err error) bool

IsInvalidParameter asserts invalidParameterError.

func IsMaskIncorrectSize

func IsMaskIncorrectSize(err error) bool

IsMaskIncorrectSize asserts maskIncorrectSizeError.

func IsMaskTooBig

func IsMaskTooBig(err error) bool

IsMaskTooBig asserts maskTooBigError.

func IsNilIP

func IsNilIP(err error) bool

IsNilIP asserts nilIPError.

func IsSpaceExhausted

func IsSpaceExhausted(err error) bool

IsSpaceExhausted asserts spaceExhaustedError.

func Split

func Split(network net.IPNet, n uint) ([]net.IPNet, error)

Split returns n subnets from network.

Types

type Config

type Config struct {
	Logger  micrologger.Logger
	Storage microstorage.Storage

	// Network is the network in which all returned subnets should exist.
	Network *net.IPNet
	// AllocatedSubnets is a list of subnets, contained by `Network`,
	// that have already been allocated outside of IPAM control.
	// Any subnets created by the IPAM service will not overlap with these subnets.
	AllocatedSubnets []net.IPNet
}

Config represents the configuration used to create a new ipam service.

type Service

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

func New

func New(config Config) (*Service, error)

New creates a new configured ipam service.

func (*Service) CreateSubnet

func (s *Service) CreateSubnet(ctx context.Context, mask net.IPMask, annotation string, reserved []net.IPNet) (net.IPNet, error)

CreateSubnet returns the next available subnet, of the configured size, from the configured network.

func (*Service) DeleteSubnet

func (s *Service) DeleteSubnet(ctx context.Context, subnet net.IPNet) error

DeleteSubnet deletes the given subnet from IPAM storage, meaning it can be given out again.