Advanced Configuration

Custom k2d Port

The port exposed for k2d can be customized through the use of the environment variable --env K2D_PORT=XXXX.

Increasing Docker Client Timeout

The default timeout for activities triggered by the Docker client is 10 minutes.

For certain devices leveraging an SD card, the pull and extract of an image might be a bottleneck. In this case, use the environment variable K2D_DOCKER_CLIENT_TIMEOUT to increase the timeout value.

Portainer Integration

k2d integrates with Portainer natively.

Only the Portainer Business Edition Edge Async type is supported by k2d

To enable it, specify the following environment variables as part of the execution:

  • PORTAINER_EDGE_KEY that can be obtained from the Environments -> Auto onboarding script creation -> Edge Agent Async page:

  • (Optional) PORTAINER_EDGE_ID to define the unique name of the device where k2d is running. The common case will be to grab the unique identifier of the edge device. If not specified, a random UUID will be generated

  • Note that Portainer agent does not run on ARMv6 hardware, so you are unable to use this integration on that platform.

Below is an example:

docker run -d \
  --name k2d \
  --network host \
  --restart always \
  --env PORTAINER_EDGE_ID=$(uuidgen) \
  --volume /var/run/docker.sock:/var/run/docker.sock \
  --volume /var/lib/k2d:/var/lib/k2d \

This will deploy K2D, the Portainer Kubernetes Edge Async Agent, and the device will appear in the "waiting room" on your configured Portainer Business instance.

ArgoCD Integration

The device where k2d runs can be treated as a single-node Kubernetes cluster managed by ArgoCD.

Use of the argocd command line tool to add it as a cluster has yet to be supported (argocd cluster add k2d).

To onboard the device as an ArgoCD managed target, create an ArgoCD cluster secret with the tlsClientConfig specifying the certificate details from k2d. To obtain the CA, cert, and key files, you will need to copy the files directly from the container and convert them to base64 format.

Below is an example run to grab and encode the certificate files:

docker cp k2d:/var/lib/k2d .
cat k2d/ssl/ca.pem | base64
cat k2d/ssl/cert.pem | base64
cat k2d/ssl/key.pem | base64

With the output above, create a secret as per below:

apiVersion: v1
kind: Secret
  name: k2d-cluster-secret
  labels: cluster
  namespace: argocd
type: Opaque
  name: k2d
  config: |
      "tlsClientConfig": {
        "caData": "${CA_ENCODED}",
        "certData": "${CERT_ENCODED}",
        "keyData": "${KEY_ENCODED}"

Now, navigate to Settings -> Clusters; you will see the k2d endpoint within the ArgoCD UI:

Be aware that your manifest has to include Kubernetes resources that are supported by k2d

Last updated