Project Overview

About This Page

On this page we’ll try to give an overview of all the moving bits and pieces in k3d to ease contributions to the project.

Directory Overview

  • .github/
    • templates for issues and pull requests
    • GitHub Action workflow definitions
  • cmd/
    • everything related to the actual k3d CLI, like the whole command tree, config initialization, argument parsing, etc.
  • docgen/
    • sub-module used to auto-generate the documentation for the CLI commands, which ends up in docs/usage/commands/
  • docs/
    • all the resources used to build k3d.io using mkdocs
  • pkg/
    • the place where the magic happens.. here you find all the main logic of k3d
    • all function calls within cmd/ that do non-trivial things are imported from here
    • this (or rather sub-packages) is what other projects would import as a module to work with k3d without using the CLI
  • proxy/
    • configuration to build the k3d-io/k3d-proxy container image which is used as a loadbalancer/proxy in front of (almost) every k3d cluster
    • this is basically just a combination of NGINX with confd and some k3d-specific configuration details
  • tests/
    • a set of bash scripts used for end-to-end (E2E) tests of k3d
    • mostly used for all the functionality of the k3d CLI which cannot be tested using Go unit tests
  • tools/
    • sub-module used to build the k3d-io/k3d-tools container image which supports some k3d functionality like k3d image import
  • vendor/
    • result of go mod vendor, which contains all dependencies of k3d
  • version/
    • package used to code k3d/k3s versions into releases
    • this is where go build injects the version tags when building k3d
      • that’s the output you see when issuing k3d version

Packages Overview

  • pkg/
    • actions/
      • hook actions describing actions (commands, etc.) that run at specific stages of the node/cluster lifecycle
        • e.g. writing configuration files to the container filesystem just before the node (container) starts
    • client/
      • all the top level functionality to work with k3d primitives
        • create/retrieve/update/delete/start/stop clusters, nodes, registries, etc. managed by k3d
    • config/
      • everything related to the k3d configuration (files), like SimpleConfig and ClusterConfig
    • runtimes/
      • interface and implementations of runtimes that power k3d (currently, that’s only Docker)
      • functions in client/ eventually call runtime functions to “materialize” nodes and clusters
    • tools/
      • functions eventually calling the k3d-tools container (see tools/ in the repo root)
    • types/
      • definition of all k3d primitives and many other details and defaults
      • e.g. contains the definition of a Node or a Cluster in k3d
    • util/
      • some helper functions e.g. for string manipulation/generation, regexp or other re-usable usages

Anatomy of a Cluster

By default, every k3d cluster consists of at least 2 containers (nodes):

  1. (optional, but default and strongly recommended) loadbalancer

    • image: ghcr.io/k3d-io/k3d-proxy, built from proxy/
    • purpose: proxy and load balance requests from the outside (i.e. most of the times your local host) to the cluster
      • by default, it e.g. proxies all the traffic for the Kubernetes API to port 6443 (default listening port of K3s) to all the server nodes in the cluster
      • can be used for multiple port-mappings to one or more nodes in your cluster
        • that way, port-mappings can also easily be added/removed after the cluster creation, as we can simply re-create the proxy without affecting cluster state

  2. (required, always present) primary server node

    • image: rancher/k3s, built from github.com/k3s-io/k3s
    • purpose: (initializing) server (formerly: master) node of the cluster
      • runs the K3s executable (which runs containerd, the Kubernetes API Server, etcd/sqlite, etc.): k3s server
      • in a multi-server setup, it initializes the cluster with an embedded etcd database (using the K3s --cluster-init flag)

  3. (optional) secondary server node(s)

  4. (optional) agent node(s)

Automation (CI)

The k3d repository mainly leverages the following two CI systems:

Documentation

The website k3d.io containing all the documentation for k3d is built using mkdocs, configured via the mkdocs.yml config file with all the content residing in the docs/ directory (Markdown).
Use mkdocs serve in the repository root to build and serve the webpage locally.
Some parts of the documentation are being auto-generated, like docs/usage/commands/ is auto-generated using Cobra’s command docs generation functionality in docgen/.

Last update: March 24, 2022