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/
- sub-module used to auto-generate the documentation for the CLI commands, which ends up in
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
- configuration to build the
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 likek3d image import
- sub-module used to build the
vendor/
- result of
go mod vendor
, which contains all dependencies of k3d
- result of
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
- that’s the output you see when issuing
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
- hook actions describing actions (commands, etc.) that run at specific stages of the node/cluster lifecycle
client/
- all the top level functionality to work with k3d primitives
- create/retrieve/update/delete/start/stop clusters, nodes, registries, etc. managed by k3d
- all the top level functionality to work with k3d primitives
config/
- everything related to the k3d configuration (files), like
SimpleConfig
andClusterConfig
- everything related to the k3d configuration (files), like
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/
types/
- definition of all k3d primitives and many other details and defaults
- e.g. contains the definition of a
Node
or aCluster
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):
-
(optional, but default and strongly recommended) loadbalancer
- image:
ghcr.io/k3d-io/k3d-proxy
, built fromproxy/
- 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
- by default, it e.g. proxies all the traffic for the Kubernetes API to port
- image:
-
(required, always present) primary server node
- image:
rancher/k3s
, built fromgithub.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)
- runs the K3s executable (which runs containerd, the Kubernetes API Server, etcd/sqlite, etc.):
- image:
-
(optional) secondary server node(s)
- image:
rancher/k3s
, built fromgithub.com/k3s-io/k3s
- image:
-
(optional) agent node(s)
- image:
rancher/k3s
, built fromgithub.com/k3s-io/k3s
- purpose: running the K3s agent process (kubelet, etc.):
k3s agent
- image:
Automation (CI)¶
The k3d repository mainly leverages the following two CI systems:
- GitHub Actions
- 2 workflows in https://github.com/k3d-io/k3d/tree/main/.github/workflows to push the artifact to AUR (Arch Linux User Repository)
- logs/history can be seen in the Actions tab: https://github.com/k3d-io/k3d/actions
- static code analysis
- build
- tests
- docker builds + pushes
- render + push docs
- (pre-) release to GitHub
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/
.