Introduction:

k3d is a lightweight wrapper to run k3s (Rancher Lab’s minimal Kubernetes distribution) in docker.

k3d makes it very easy to create single- and multi-node k3s clusters in docker, e.g. for local development on Kubernetes.

In the reference configuration supplied, the CircleCI Kubernetes Orb is used to automate the installation of the kubectl CLI. k3d is then installed and a cluster is created.

This cluster can then be used for tests or other operations that requiring a cluster to be present in your execution environment.

Reference configuration:

version: 2.1

orbs:
  kubernetes: circleci/kubernetes@2.0.1

executors:
  k3d-executor:
    machine:
      image: ubuntu-2404:2025.09.1

jobs:
  install-k3d:
    executor: k3d-executor
    steps:
      - checkout
      - kubernetes/install_kubectl
      - run:
          name: Install k3d
          command: |
            wget -q https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh
            cat install.sh | bash
            k3d --version

      - run:
          name: Create k3d cluster
          command: |
            k3d cluster create the-cluster

      - run:
          name: kubectl cluster-info
          command: |
            kubectl cluster-info

workflows:
  k3d-workflow:
    jobs:
      - install-k3d

Additional Resources

• k3d
• CircleCI Orbs: Kubernetes