K2D Internal Architecture

The diagram below highlights the internal architecture of K2D.

Note that from a client side, the most common Kubernetes tools have been validated against K2D's API.

On the Docker host, K2D operates completely within a single container.


On a high level, k2d works with three main components:

  • API server

  • Controller

  • Adapter

API server

The API server is responsible for handling all Kubernetes requests sent by any Kubernetes client. It emulates the Kubernetes API server for a list of supported resources.

Requests to create resources, such as pods, deployments, and persistent volume claims, are processed asynchronously by the controller. The controller assigns a priority to each request before sending it to the adapter for creation.

Other resource requests, such as read, update, patch, and delete, are processed synchronously by the adapter directly.


The Controller component has the responsibility of assigning priorities to each resource creation operation and communicating with the adapter component to translate the resource creation request from the original Kubernetes object to a Docker object.

All resource creation requests, except for namespace creation, are handled asynchronously. Namespace creation is handled synchronously to ensure that a namespace is always available before processing other requests that might depend on it.

Priorities are assigned to each resource type to ensure that resources dependent on each other are created in the correct order. For example, a namespace is created before a pod that depends on that namespace.

The following list shows the priorities and associated resources set by the controller.

High priority resources

  • ConfigMap

  • Secret

  • PersistentVolumeClaim

Medium priority resources

  • Deployment

  • Pod

Low priority resources

  • Service


The Adapter component is responsible for handling Kubernetes operations. It utilizes a Converter component to translate a Kubernetes object into a Docker object. This Docker object is then handled using the Docker SDK.

In addition, the Adapter component relies on a Store component to store resources that need to be accessed from disk by the containers created by k2d. The Store component can interact with the host's filesystem (by default, everything is stored in /var/lib/k2d - refer to the advanced configuration section to modify this location) to store data associated with Secrets and ConfigMaps.

Last updated