Kubernetes native dhcp server.

The server can be configured by creating and editing kubernetes objects dhcpserver, dhcpsubnet and optionally dhcphost.

Server instances

To start listening, at least one dhcpserver object must be created:

apiVersion: dhcp.kaas.mirantis.com/v1alpha1
kind: DHCPServer
  name: dhcpserver-sample-1
  listenInterface: enp0s3
  • listenInterface Server will listen on all interfaces if this field is empty.
  • listenAddress Server will listen at if empty.


Each subnet is represented by dhcpsubnet object:

apiVersion: dhcp.kaas.mirantis.com/v1alpha1
kind: DHCPSubnet
  name: dhcpsubnet-sample-broadcast
  leaseTime: 3600
  - id: 66
    type: string
  • subnet subnet address. Required.
  • rangeFrom Required.
  • rangeTo Required.
  • gateway Required.
  • bootFileName Optional.
  • leaseTime Required.
  • dns Optional.
  • options list of dhcp options to be included in response. Optional.

Each server instance may serve multiple subnets. Server will automatically detect proper subnet for each request, and will construct dhcp response according to dhcpsubnet and possibly dhcplease settings.

Requests on unknown subnets will be ignored.

Static Hosts

Per host configuration may be applied if needed by creating dhcphost objects:

apiVersion: dhcp.kaas.mirantis.com/v1alpha1
kind: DHCPHost
  name: host-sample-1
  mac: "00:01:02:03:04:05"
  hostname: sample-pxe-node
  - id: 66
    type: string
  serverHostName: example.net
  leaseTime: 3600
  • subnet is a reference to subnet. Required.
  • mac client hardware address. Required.
  • ip client fixed ip address. may be outside of range but must be inside of subnet. Will be taken from pool if empty.
  • gateway Optional.
  • hostname Optional.
  • dns Optional.
  • options Optional.
  • serverHostName Optional.
  • bootFileName Optional.
  • leaseTime Optional.

Server start listening and logging dhcp requests when at least one dhcpserver is created, and start responding when at least one dhcpsubnet is created.

$ kubectl get dhcpservers
NAME                   INTERFACE   LISTEN
dhcpserver-sample-br1  br1
dhcpserver-veth 1      veth1

$ kubectl get dhcpsubnets
NAME                          SUBNET         FROM          TO              GATEWAY


  • keep as few dhcpleases objects as possible;
  • detect start of another server;
  • load all subnets, leases and hosts before starting the server;
  • configure namespace;
  • log server version;
  • add ping check option;
  • handle subnet update;
  • handle hostnames;
  • support dhcp NAK;
  • support dhcp INFORM;
  • add validation webhooks;
  • add mutating webhooks to add OwnerRef;
  • conditional options;
  • respect requested options;
  • make test client;
  • add ReuseAddr property to server/listen;
  • exit if failed to bind;
  • dhcp option 43 (vendor-option-space);


Getting Started

You’ll need a Kubernetes cluster to run against. You can use Minikube to get a local cluster for testing, or run against a remote cluster. Note: Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster kubectl cluster-info shows).

Running on the cluster

  1. Install Instances of Custom Resources:
kubectl apply -f config/samples/
  1. Build and push your image to the location specified by IMG:
make docker-build docker-push IMG=<some-registry>/k8s-dhcp:tag
  1. Deploy the controller to the cluster with the image specified by IMG:
make deploy IMG=<some-registry>/k8s-dhcp:tag

Uninstall CRDs

To delete the CRDs from the cluster:

make uninstall

Undeploy controller

UnDeploy the controller to the cluster:

make undeploy


// TODO(user): Add detailed information on how you would like others to contribute to this project

How it works

This project aims to follow the Kubernetes Operator pattern

It uses Controllers which provides a reconcile function responsible for synchronizing resources untile the desired state is reached on the cluster

Test It Out

  1. Install the CRDs into the cluster:
make install
  1. Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running):
make run

NOTE: You can also run this in one step by running: make install run

Modifying the API definitions

If you are editing the API definitions, generate the manifests such as CRs or CRDs using:

make manifests

NOTE: Run make --help for more information on all potential make targets

More information can be found via the Kubebuilder Documentation


Copyright 2022.

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at


Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


View Github