coil

README

Coil

Coil is a CNI plugin that automates IP address management (IPAM) and programs intra-node Pod routing for Kubernetes.

Coil is designed in favor of UNIX philosophy. It is not tightly integrated with routing daemons like BIRD. It does not implement Kubernetes Network Policies either.

Instead, users can choose their favorite routing daemons and/or network policy implementations for use with coil. There is a real-world example of using coil with MetalLB (for LoadBalancer) and Calico (for network policies) at github.com/cybozu-go/neco-apps.

Project Status: General Availability (GA)

Requirements

• Linux with routing software such as BIRD.
• Kubernetes Version
  • 1.15, 1.16, 1.17
  • Other versions are likely to work, but not tested.
• etcd: coil requires etcd v3 API, does not support v2.

Features

• IP address management (IPAM)

  Coil dynamically allocates IP addresses to Pods.

  Coil has a mechanism called address pool so that the administrator can control to assign special/global IP addresses only to some Pods.

• Address pools

  An address pool is a pool of allocatable IP addresses. In addition to the default pool, users can define arbitrary address pools.

  Pods in a specific Kubernetes namespace take their IP addresses from the address pool whose name matches the namespace if such a pool exists.

  This way, only users who can create Pods in the namespace can use special/global IP addresses.

• Address block

  Coil divides a large subnet into small fixed size blocks (e.g. /27), and assign them to nodes. Nodes then allocate IP addresses to Pods from the assigned blocks.

• Intra-node Pod routing

  Coil programs intra-node routing for Pods.

  As to inter-node routing, coil publishes address blocks assigned to the node to an unused kernel routing table as described next.

• Publish address blocks to implement inter-node Pod routing

  Coil registers address blocks assigned to a node with an unused kernel routing table. The default table ID is 119.

  The routing table can be referenced by other routing programs such as BIRD to implement inter-node routing.

  An example BIRD configuration file that advertises address blocks via BGP is available at mtest/bird.conf.

Programs

This repository contains these programs:

• coil: CNI plugin.
• coilctl: CLI tool to configure coil IPAM.
• coild: A background service to manage IP address.
• coil-controller: watches kubernetes resources for coil.
• coil-installer: installs coil and CNI configuration file.
• hypercoil: all-in-one binary just like hyperkube.

coil should be installed in /opt/cni/bin directory.

coilctl directly communicates with etcd. Therefore it can be installed any host that can connect to etcd cluster.

coild and coil-installer should run as DaemonSet.

coil-controller should be deployed as Deployment.

Documentation

docs directory contains documents about designs and specifications.

mtest/bird.conf is an example configuration for BIRD to make it work with coil.

License

MIT

Documentation

Index

• Constants
• Variables
• func NewEtcdConfig() *etcdutil.Config
• func ResolveEtcdEndpoints(cfg *etcdutil.Config) error
• type AddressPool
  • func (p AddressPool) MarshalJSON() ([]byte, error)
  • func (p *AddressPool) UnmarshalJSON(data []byte) error
  • func (p AddressPool) Validate() error
• type BlockAssignment
  • func EmptyAssignment(ipnet *net.IPNet, blockSize int) BlockAssignment
  • func (ba *BlockAssignment) FindBlock(node string, block *net.IPNet) int
  • func (ba BlockAssignment) MarshalJSON() ([]byte, error)
  • func (ba *BlockAssignment) ReleaseBlock(node string, block *net.IPNet) error
  • func (ba *BlockAssignment) UnmarshalJSON(data []byte) error
• type IPAssignment

Constants

const Version = "1.1.9"

Version represents the version of coil

Variables

var ErrBlockNotFound = errors.New("block not found")

ErrBlockNotFound is returned when a target block does not exist.

Functions

func NewEtcdConfig

func NewEtcdConfig() *etcdutil.Config

NewEtcdConfig creates a new etcd config

func ResolveEtcdEndpoints

func ResolveEtcdEndpoints(cfg *etcdutil.Config) error

ResolveEtcdEndpoints checks if an endpoint begins with "@". If such an endpoint exists, it looks for Endpoints resource in "kube-system" namespace.

Suppose an endpoint is "@myetcd". If `kube-system/myetcd` Endpoints exists, then endpoints in cfg is replaced with those defined in the Endpoints resource.

Types

type AddressPool

type AddressPool struct {
	Subnets   []*net.IPNet
	BlockSize int
}

AddressPool is a collection of subnets

func (AddressPool) MarshalJSON

func (p AddressPool) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler

func (*AddressPool) UnmarshalJSON

func (p *AddressPool) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler

func (AddressPool) Validate

func (p AddressPool) Validate() error

Validate validates pool.

type BlockAssignment

type BlockAssignment struct {
	FreeList []*net.IPNet            `json:"free"`
	Nodes    map[string][]*net.IPNet `json:"nodes"`
}

BlockAssignment holds address block assignment information for a subnet

func EmptyAssignment

func EmptyAssignment(ipnet *net.IPNet, blockSize int) BlockAssignment

EmptyAssignment returns an empty block assignment for ipnet and blockSize.

func (*BlockAssignment) FindBlock

func (ba *BlockAssignment) FindBlock(node string, block *net.IPNet) int

FindBlock returns index of target block

func (BlockAssignment) MarshalJSON

func (ba BlockAssignment) MarshalJSON() ([]byte, error)

MarshalJSON implements Marshaler

func (*BlockAssignment) ReleaseBlock

func (ba *BlockAssignment) ReleaseBlock(node string, block *net.IPNet) error

ReleaseBlock move target block to freeList from target node

func (*BlockAssignment) UnmarshalJSON

func (ba *BlockAssignment) UnmarshalJSON(data []byte) error

UnmarshalJSON implements Unmarshaler

type IPAssignment

type IPAssignment struct {
	ContainerID string    `json:"container_id"`
	Namespace   string    `json:"namespace"`
	Pod         string    `json:"pod"`
	CreatedAt   time.Time `json:"created_at"`
}

IPAssignment holds IP address assignment information for a pod/container