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
rancher/k3d-proxycontainer 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
rancher/k3d-toolscontainer 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 buildinjects 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
SimpleConfigandClusterConfig
+
+- 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
Nodeor aClusterin 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:
rancher/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-initflag)
+
+ - 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/rancher/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/rancher/k3d/actions +
+ - DroneCI
-
+
- a set of pipelines in a single file: https://github.com/rancher/k3d/blob/main/.drone.yml +
- static code analysis +
- build +
- tests +
- docker builds + pushes +
- render + push docs +
- (pre-) release to GitHub +
pushevents end up here (also does the releases, when a tag is pushed): https://drone-publish.rancher.io/rancher/k3d
+prs end up here: https://drone-pr.rancher.io/rancher/k3d
+
+
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: July 20, 2021
+
+
+
+
+
+
+
+
+
+
+
+
+