1.0.0
Search
⌃K
Comment on page

Quick-Start Guide

This is the quick-start guide that will assist you in spinning up a k2d instance and start consuming it.

Pre-requisites

To install and configure k2d, the following pre-requisites must be met:
  • docker server and client version 23.0+
  • podman version 4.4.0+
  • kubectl version 1.26+
  • (optional) helm version 3.10+
  • Hardware Requirements
    • ARM v7 CPU of 700MHhz or higher
    • 512 MB RAM or higher
    • 16GB SD-Card or greater

Installation

The k2d image can run on the following platforms/archs: linux/amd64, linux/arm64, linux/386, linux/armv6 and linux/armv7.
The deployment of k2d is based on a simple Docker run:
docker run -d \
--name k2d-k2d \
--network host \
--restart always \
--env K2D_ADVERTISE_ADDR=YOUR_HOST_IP \
--env K2D_SECRET=YOUR_OWN_SECRET \
--label resource.k2d.io/namespace-name=k2d \
--label workload.k2d.io/name=k2d \
--volume /var/run/docker.sock:/var/run/docker.sock \
--volume /var/lib/k2d:/var/lib/k2d \
portainer/k2d:1.0.0
  • Use the K2D_ADVERTISE_ADDR only if you have multiple net interfaces at the OS level
  • Use of the host network is not mandatory. Using the bridge network is supported:
    • K2D_ADVERTISE_ADDR must be specified when using the bridge network
    • Docker Desktop for Mac and Docker Desktop for Windows do not support the HOST network, so you must use the bridge network if testing on these platforms.
  • The K2D_SECRET is used as an authentication token to secure the k2d API:
    • If the K2D_SECRET environment variable is not set, it will be automatically generated, and you can retrieve it in the k2d container logs
  • Use of the volume mounts is for:
    • The /var/run/docker.sock must be mounted to interact with the underlying Docker Engine server
    • The /var/lib/k2d path must be persisted for:
      • SSL certificates
      • Secrets
      • Configmaps
      • Kubernetes Token

Installation with Podman

For Podman to work with k2d, the Podman Socket first needs to be enabled:
systemctl --user enable --now podman.socket
Then, create the k2d directory under /var/lib and change the owner to your user & group:
sudo mkdir -p /var/lib/k2d && sudo chown -R YOUR_USER:YOUR_GROUP /var/lib/k2d
Finally, you can use the following command to run k2d with Podman in the rootless mode:
podman run -d \
--name k2d-k2d \
--restart always \
--env K2D_ADVERTISE_ADDR=YOUR_HOST_IP \
--env K2D_SECRET=YOUR_OWN_SECRET \
--label resource.k2d.io/namespace-name=k2d \
--label workload.k2d.io/name=k2d \
--security-opt label=disable \
--publish 6443:6443 \
--volume /run/podman/podman.sock:/var/run/docker.sock:ro \
--volume /var/lib/k2d:/var/lib/k2d \
portainer/k2d:1.0.0
The following memory-related issues have arisen for CentOS 9:
  • crun: cannot set memory swappiness with cgroupv2
  • crun: write to /proc/self/oom_score_adj: Permission denied: OCI permission denied
It is recommended that CentOS 8 be run to avoid the problems listed above.

Installation with Docker via Snap

When Docker Engine is installed via Snap, due to its confinement, most of the underlying directories are set to read-only. Hence, amending the default k2d data path is required.
You can use the following command to run k2d with Docker installed via Snap:
docker run -d \
--name k2d-k2d \
--restart always \
--env K2D_ADVERTISE_ADDR=YOUR_HOST_IP \
--env K2D_SECRET=YOUR_OWN_SECRET \
--env K2D_DATA_PATH=${HOME}/k2d \
--label resource.k2d.io/namespace-name=k2d \
--label workload.k2d.io/name=k2d \
--publish 6443:6443 \
--volume /var/run/docker.sock:/var/run/docker.sock:ro \
--volume ${HOME}/k2d:${HOME}/k2d \
portainer/k2d:1.0.0

Usage

The k2d instance exposes an API endpoint to return a kubeconfig format to start interacting with it:
Note: You must use the K2D_SECRET to retrieve the config file successfully.
curl --insecure -H "Authorization: Bearer $(echo -n 'YOUR_OWN_SECRET' | base64)" https://YOUR_HOST_IP:6443/k2d/kubeconfig
The output can be saved directly to your local ~/.kube/config, or set KUBECONFIG environment variable. You can treat it just like Kubernetes!
Now, use kubectl to interact with the k2d translator:
> kubectl get namespaces
NAME STATUS AGE
default Active 53s
k2d Active 52s
helm will also be supported as long as the chart contains the resources supported by k2d.

The List of Supported API Resources

To identify which Kubernetes API resources are supported by k2d, you can run kubectl api-resources to obtain the list:
> kubectl api-resources
NAME SHORTNAMES APIVERSION NAMESPACED KIND
configmaps cm v1 true ConfigMap
events v1 false Event
namespaces ns v1 false Namespace
nodes v1 false Node
persistentvolumeclaims pvc v1 true PersistentVolumeClaim
persistentvolumes pv v1 false PersistentVolume
pods v1 true Pod
secrets v1 true Secret
services svc v1 true Service
deployments apps/v1 true Deployment
selfsubjectaccessreviews authorization.k8s.io/v1 false SelfSubjectAccessReview
events events.k8s.io/v1 false Event
storageclasses sc storage.k8s.io/v1 false StorageClass

Uninstall k2d

In order to uninstall k2d, you can simply remove the k2d container:
docker rm -f k2d-k2d
To reset the system and remove all the resources that have been created by k2d and via k2d, you can use the following command:
This command will remove any workload and data that have been deployed through k2d.
docker run --rm -it \
--volume /var/run/docker.sock:/var/run/docker.sock \
--volume /var/lib/k2d:/var/lib/k2d \
portainer/k2d:1.0.0 -reset

With Podman

If you are using Podman, you can use the following instructions:
podman rm -f k2d-k2d
This command will remove any workload and data that have been deployed through k2d.
podman run --rm -it \
--volume /run/podman/podman.sock:/var/run/docker.sock \
--volume /var/lib/k2d:/var/lib/k2d \
--security-opt label=disable \
portainer/k2d:1.0.0 -reset
​
Previous
Supported Resources and Operations
Next
Common IIoT application manifest examples
Last modified 1mo ago