whereabouts

An IP Address Management (IPAM) CNI plugin that assigns IP addresses cluster-wide.

If you need a way to assign IP addresses dynamically across your cluster -- Whereabouts is the tool for you. If you've found that you like how the host-local works, but, you need something that works across all the nodes in your cluster (host-local only knows how to assign IPs to pods on the same node) -- Whereabouts is just what you're looking for.

The original inspiration for Whereabouts comes from when users have tried to use the samples from Multus CNI (a CNI plugin that attaches multiple network interfaces to your pods), which includes samples that use the host-local plugin, and they find that it's... Almost the right thing. Sometimes people even assume it'll work across nodes -- and then wind up IP address collisions.

Whereabouts is designed with Kubernetes in mind, but, isn't limited to use in just Kubernetes.

To store IP address allocation, Whereabouts uses etcd as a backend. If you'd like to see another backend -- the patches are welcome!

Installation

There's two steps to installing Whereabouts

• Installing etcd, for a
• Installing Whereabouts itself (it's just a binary on disk)

Installing etcd.

Installing Whereabouts.

You can install this plugin with a Daemonset, using:

git clone https://github.com/dougbtv/whereabouts && cd whereabouts
kubectl apply -f ./doc/daemonset-install.yaml

You can compile from this repo (with ./hack/build-go.sh) and copy the resulting binary onto each node in the /opt/cni/bin directory (by default).

Example Config

{
      "cniVersion": "0.3.0",
      "name": "whereaboutsexample",
      "type": "macvlan",
      "master": "eth0",
      "mode": "bridge",
      "ipam": {
        "type": "whereabouts",
        "range": "192.168.2.225/28",
        "etcd_host": "127.0.0.1:2379",
        "log_file" : "/tmp/whereabouts.log",
        "log_level" : "debug",
        "gateway": "192.168.2.1"
      }
}

Building

Run the build command from the ./hack directory:

./hack/build-go.sh

Acknowledgements

Thanks big time to Tomofumi Hayashi, I utilized his static CNI IPAM plugin as a basis for this project to give me a head start!

Known limitations

• This only works for IPv4 addresses.
• It has write locking, but, it's not optimized. It's write locked for all ranges.
• If you specify overlapping ranges -- you're almost certain to have collisions, so if you specify one config with 192.168.0.0/16 and another with 192.168.0.0/24, you'll have collisions.
• There's approximately a cap of 18,500 possible addresses in a given range before you'll have to configure etcd to allow more than 1.5 megs in a value.
• There's probably a lot of comparison of IP addresses that could be optimized, lots of string conversion.
• The etcd method that I use is all ASCII. If this was binary, it could probably store more and have more efficient IP address comparison.