Subnet Garden

Description

Subnet Garden is a source-control based approach to managing network infrastructure similar to IPAM without the need to set up a dedicated IPAM server. The database is a human-readable text file that can be edited with any text editor and is stored in a git repository.

Features

• Human-readable text file
• Git-based version control
• Automatic subnet assignment

How to use it

Installation

Using cargo:

cargo install subg

This will install the subg binary in ~/.cargo/bin. Make sure that this directory is in your PATH environment variable.

Initialization

Subnet garden stores its data in a pool file. This file is a source-control friendly text file that can be edited with any text editor and easily placed under version control. Each pool file is responsible for managing subnets under a single parent subnet.

For example, To create a new pool file that will managing the 10.10.0.0/16 subnet, run:

subg init 10.10.0.0/16

This will createa new pool file in the current directory called subnet-garden-pool.yaml.

You may also manage IPv6 subnets. For example, to manage the fc00::/112 subnet, run:

subg init fc00::/112

You can specify alternate names for the pool file using the --pool-path option:

subg init --pool-path institute-network.yaml 10.10.0.0/16

You can also set the SUBG_POOL_PATH environment variable to specify the pool file. This is useful to avoid having to specify the --pool-path option every time you run a command:

# Using an environment variable
export SUBG_POOL_PATH=institute-network.yaml
subg init 10.10.0.0/16

It is also possible to store the pool file as JSON instead of YAML:

export SUBG_POOL_PATH=subnet-garden-pool.json
subg init 10.10.0.0/16

Managing subnets

Once you have initialized a pool file, you can start allocate, deallocate, and see information about managed subnets.

Subnet allocation

When you need to allocate a new subnet, you can do so by requesting a subnet that covers the number of hosts-bits you need.

Allocate an anonymous subnet

For example, to allocate a subnet that can hold 8-bits worth of hosts (256 hosts), run:

subg allocate 8

This will allocate an 8-bit subnet from the pool. The location of the subnet is determined by available space in the pool.

Allocate a named subnet

A subnets may be assigned names. Once assigned, the name may be referenced in other commands. For example, to allocate a subnet with a name, run:

subg allocate 8 tardigrade-lab

This will create an 8-bit subnet with the name tardigrade-lab.

Allocate a set of subnets

In many cases one needs to allocate a set of subnets, such as when building a system across multiple datacenters and availability zones. For example, to allocate 2 8-bit subnets in each of two availability zones and two regions, run:

subg allocate 8 tardigrade-project-{}-{}-{} us-east-1,eu-central-1 a,b %0..2

This will allocate 8 subnets in total:

tardigrade-project-us-east-1-a-0
tardigrade-project-us-east-1-a-1
tardigrade-project-us-east-1-b-0
tardigrade-project-us-east-1-b-1
tardigrade-project-eu-central-1-a-0
tardigrade-project-eu-central-1-a-1
tardigrade-project-eu-central-1-b-0
tardigrade-project-eu-central-1-b-1

Claim a specific CIDR

In some cases you may want to allocate a subnet with a specific address. For example, when applying a subnet pool to an existing network. To claim a specific subnet, run:

subg claim 10.10.110.0/24

Seeing allocated subnets

To see the subnets that have been allocated, run:

subg cidrs

To see a list of named subnets use:

subg names

Subnet naming

It is possible to add, change or remove the name of a subnet. Examples:

Add a name to an unnamed subnet:

subg rename 10.10.0.0/24 rotifer-lab

Change the name of a subnet:

subg rename rotifer-lab other-microbe-lab

To remove the name of a subnet, omit the name:

subg rename other-microbe-lab

Freeing subnets

Subnets are freed by name or CIDR. For example, to free the previously claimed subnet, run:

subg free 10.10.110.0/24

Subnet name template

When describing a set of subnets, the name parameter becomes a template used for describing the name of each new subnet. The arguments after the template are generated in every combination. The values are substituted into each {} placeholder in the template.

List parameters

List parameters are specified as a comma-separated list of values. For example, to generate a list of subnets for each of the availability zones a and b, run:

subg allocate 8 tardigrade-experiment-az-{} a,b

This will create two networks, tardigrade-experiment-az-a and tardigrade-experiment-az-b.

Range parameters

Range parameters are used to specify a range of numbers. For example, to generate a list of 6 subnets, run:

subg allocate 8 rotifer-experiment-{} %0..6

Note that the range is exclusive of the last number. This will create 6 subnets

rotifer-experiment-0
rotifer-experiment-1
rotifer-experiment-2
rotifer-experiment-3
rotifer-experiment-4
rotifer-experiment-5

Subnet garden pool format

The subnet garden pool file is stored either as a YAML or JSON file. Here is an example of a YAML pool file:

cidr: 10.10.0.0/16
subnets:
- cidr: 10.10.0.0/24
- cidr: 10.10.1.0/24
  name: tardigrade-lab
- cidr: 10.10.110.0/24