• Stars
    star
    113
  • Rank 310,115 (Top 7 %)
  • Language
    Go
  • License
    MIT License
  • Created over 5 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

golang library for ip address management

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

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


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

    ctx, cancel := context.WithTimeout(ctx, 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/metal-stack/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/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, connect.NewRequest(&v1.CreatePrefixRequest{Cidr: "192.168.0.0/16",}))
    if err != nil {
        panic(err)
    }
    fmt.Println("Prefix:%q created", result.Msg.GetPrefix().GetCidr())
}

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

The benchmarks above were performed using:

  • cpu: Intel(R) Xeon(R) Platinum 8370C CPU @ 2.80GHz
  • postgres:16-alpine
  • cockroach:v23.1.0
  • redis:7.2-alpine
  • keydb:alpine_x86_64_v6.3.1
  • etcd:v3.5.9
  • mongodb:7

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

More Repositories

1

metal-api

API to manage and control plane resources like machines, switches, operating system images, machine sizes, networks, IP addresses and more
Go
119
star
2

csi-driver-lvm

Go
80
star
3

csi-lvm

kubernetes csi for bare metal deployments, uses local storage
Go
66
star
4

mini-lab

a small, virtual setup to locally run the metal-stack
Python
52
star
5

firewall-controller

A kubernetes controller running on bare-metal firewalls, creating nftables rules, configures suricata, collects network metrics
Go
42
star
6

metal-hammer

metal-hammer is used to boot bare metal servers with ipxe and the metal-stack kernel
Go
39
star
7

gardener-extension-provider-metal

Implementation of the gardener-extension-controller for metal-stack
Go
24
star
8

metalctl

The metal-stack CLI for accessing the metal-api.
Go
16
star
9

go-lldpd

go-lldpd is a lldpd server written in go
Go
13
star
10

go-hal

server hardware abstraction, tries to lower the burden of supporting different server vendors
Go
13
star
11

metal-go

Go API client for metal-api
Go
11
star
12

metal-core

Middleware for pixiecore and switch access
Go
10
star
13

backup-restore-sidecar

K8s sidecar for database auto-backup and -recovery
Go
10
star
14

metal-images

CI-Builds for the metal-stack OS images
Go
9
star
15

kernel

kernel build for pxe booting bare metal machines
Dockerfile
9
star
16

releases

Contains release notes and release image vectors for metal-stack
Python
8
star
17

metal-robot

A bot helping to automate some tasks on Github and Gitlab. 🤖
Go
7
star
18

metal-python

Python API client for metal-api
Python
7
star
19

droptailer

droptailer visualize iptables/nftables drops in a kubernetes environment
Go
6
star
20

metal-bmc

Catches ip addresses and uuids of ipmi devices
Go
5
star
21

nftables-exporter

prometheus exporter for nftables metrics
Go
4
star
22

metal-ccm

K8s Cloud Controller Manager for metal-stack
Go
4
star
23

ansible-common

Shared roles, modules and plugins for metal-stack
Python
4
star
24

frr

builds frr from source for different operating systems as docker images
Dockerfile
4
star
25

metal-networker

configures networking of metal machines during installation.
Go
4
star
26

gardener-extension-backup-s3

This project is a permanent fork of: https://github.com/gardener/gardener-extension-provider-aws
Go
4
star
27

docs

Contains the documentation for metal-stack
Shell
3
star
28

metal-deployment-base

Just some very general docker base image builds
Dockerfile
3
star
29

firewall-policy-controller

A small controller to generate nftables rules based on network policies and services
Go
3
star
30

os-metal-extension

gardener extension to handle userdata creation in the ignition format
Go
3
star
31

masterdata-api

Microservice to manage tenant and project entities
Go
3
star
32

updater

Updater is a small utility to update your go executables from a http server
Go
3
star
33

builder

Builder image to create go applications.
Makefile
3
star
34

metal-console

Metal Console is responsible to create a secure access to the serial console of a metal machine
Go
3
star
35

metal-roles

Ansible roles for deploying metal-stack
Jinja
2
star
36

duros-go

go client to talk to a lightbits duros api server
Go
2
star
37

metal-lib

Common go packages used across the metal-stack microservices
Go
2
star
38

machine-controller-manager-provider-metal

gardener machine controller manager for metal-stack
Go
2
star
39

gardener-extension-dns-powerdns

This project is a permanent fork of: https://github.com/gardener/gardener-extension-provider-aws
Go
2
star
40

metal-ansible-modules

Ansible modules for metal-stack
Python
1
star
41

metal-ansible-collections

This repository contains Ansible collections for deploying metal-stack.
Python
1
star
42

v

v is a small helper to add version information to your go project.
Go
1
star
43

metal-stack

we believe kubernetes runs best on bare metal, this is all about providing metal as a service
1
star
44

cluster-api-provider-metalstack

Go
1
star
45

pixie

Pixiecore is a permanent fork of https://github.com/danderson/netboot
Go
1
star
46

csilvmctl

csi-driver-lvm command line utility
Go
1
star
47

helm-charts

Contains metal-stack Helm charts
Smarty
1
star
48

metal-image-cache-sync

Syncs partition image caches
Go
1
star
49

sonic-go-swsssdk

Golang SONiC switch state service sdk
Go
1
star
50

security

JWT and HMAC based security primitives for authentication of services and users
Go
1
star