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.
To install and configure
k2d
, the following pre-requisites must be met:docker
server and client version23.0+
podman
version4.4.0+
kubectl
version1.26+
- This is not required on the k2d host, just on your management PC
- (optional)
helm
version3.10+
- Hardware Requirements
- ARM v7 CPU of 700MHhz or higher
- 512 MB RAM or higher
- 16GB SD-Card or greater
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 thebridge
network is supported:K2D_ADVERTISE_ADDR
must be specified when using thebridge
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 thek2d
API:- If the
K2D_SECRET
environment variable is not set, it will be automatically generated, and you can retrieve it in thek2d
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
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.
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
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
.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
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
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