Install, configure and create

Welcome, on these pages you will find guides on how to install, operate and extend the software to suit your own use-cases.

Installation

There are many ways to install easykube, below are some of the paths you can choose.

Please note that pre-built easykube binaries exist for windows, linux, and macos. It will run on windows, but it’s recommended run easykube in WSL2

Nix

You can use nix to speed up the process.

nix develop github:/torloejborg/easykube

This will fetch and build from source, and automatically pull in the required binary dependencies (except docker), you will then be dropped into a shell with all the tooling available, and can start using easykube.

nix (~/.config/nix/nix.conf)

You may have to add the following to your nix.conf in order to quench nix warnings

extra-experimental-features = nix-command
extra-experimental-features = flakes

The Nix flake has two shells; Default will build easykube from source.

nix develop .#light will drop you into a shell with supporting tools without building. Useful if you cloned the repository.

Manual installation

Download the latest easykube binary for your platform here. Extract the archive, rename the binary to easykube, ek or whatever you please. And make sure it’s on your systems PATH.

Use a package manager, or download the following software yourself

On some linux systems, installing the above packages via snap, has proved troublesome for easykube. It may work out for you, it may not.

Post installation check

Typing easykube in your shell you should see a warning and usage description.

⚠ expecting /home/jane/.kube/easykube to exist, create the cluster and this message will disappear

bootstrap a single node kubernetes cluster, install development platforms via addon-repositories

hint: start with 'easykube config'

Usage:
  easykube [command]

Available Commands:
  add         applies one or more addons located in the addon repository
  completion  Generate the autocompletion script for the specified shell
  config      edits your easykube configuration file
  create      creates the easykube cluster
  destroy     kills the current easykube cluster
  help        Help about any command
  list        lists available modules in the addon repository
  remove      removes a previously installed addon
  skaffold    creates a new addon using a basic template
  start       starts the cluster node and registry container
  status      inspects you environment to see if prerequisites are met
  stop        stops the cluster node and registry container
  version     shows the version of easykube CLI

Flags:
  -d, --dry-run   dry-run
  -h, --help      help for easykube
  -v, --verbose   verbose output

Also, try with easykube status, that should yield some more warnings and errors.

⚠ expecting /home/jane/.kube/easykube to exist, create the cluster and this message will disappear
Inspecting binary dependencies
✓ kubectl 1.34.1 (~1.34)
✓ docker 28.4.0 (^28)
✓ helm 3.19.0 (~3.19)
✓ kustomize 5.7.1 (~5.7)

Container configuration
⚠ easykube-registry container not running
⚠ easykube-control-plane container not running
⚠ easykube-registry not connected to kind network

Repository configuration
stat /home/jane/addons: no such file or directory
⚠ addon directory '/home/jane/addons' does not exist, check your config

The checks for the dependent binaries passes, next, proceed to configuration.

Configuration

By itself easykube is not very interesting, it cannot do anything without its companion addons, which you will find here. Clone (or download the repository) to your local machine.

The next sections assume the addon repository is placed in /home/jane/code/easykube-addons - adjust accordingly.

You will need to set an evironment variable named VISUAL which points to your favorite editor.

$ export VISUAL=nvim

You can use any editor, as long as it can be called with editor /some/path/to/file.txt

Invoke easykube config this will launch your editor and present you with the following

easykube:
  # location of addons dir
  addon-root: /home/jane/addons (1)

  # where local configuration is stored
  config-dir: /home/jane/.config/easykube (2)

  # if an absolute path is not given, persistence will be located in config-dir
  # this is used by kind to store peristent data, it will survive cluster deletion
  persistence-dir: /home/jane/.config/easykube/persistence (3)

  # Container Runtime (as of now, only docker is supported. podman support is planned)
  container-runtime: docker
1 - Change this line to match the path to the addon repository you previously cloned
2 - This is the directory where easykube will store its configuration files it will be revisited in the operate section.
3 - Easykube will automatically create subdirectories here based on addon requirements

Save the file, and we’ll be ready for the next step.

Create cluster

With installation and configuration done, it’s time to create a cluster, do that with;

easykube create

If all went well, a cluster creation report is printed, each addon is listed in a section which describes which ports it want to expose, and what storage it needs.

⚠ expecting /home/jane/.kube/easykube to exist, create the cluster and this message will disappear
Bootstrapping easykube single node cluster
Waiting for cluster ready
Configuring containerd
Adding registry host
These addons contribute to cluster configuration (1)

Addon: "gitea.ek.js"
  Mounts:
        - /home/jane/.config/easykube/persistence/gitea -> /storage/gitea

Addon: "ingress.ek.js" (2)
  Ports:
        - 127.0.0.1 80/TCP -> NodePort 80
        - 127.0.0.1 443/TCP -> NodePort 443

Addon: "immich.ek.js"
  Mounts:
        - /home/jane/.config/easykube/persistence/immich-data -> /storage/immich-data
        - /home/jane/.config/easykube/persistence/immich-extra-volume -> /storage/ext-pictures

Addon: "postgres.ek.js"
  Ports:
        - 127.0.0.1 5432/TCP -> NodePort 32000

  Mounts:
        - /home/jane/.config/easykube/persistence/postgres-data -> /storage/pg-data

Addon: "redis.ek.js"
  Ports:
        - 127.0.0.1 6379/TCP -> NodePort 30971

Addon: "temporal.ek.js"
  Ports:
        - 127.0.0.1 7233/TCP -> NodePort 30950

⚠ Warning, cluster created without importing secrets, this might affect your ability to pull images from private registries. (3)
1 A single kind cluster configuration file is created based on the aggregate of all addons
2 An addon want to expose port 80 and 443 from the host to the cluster.
3 Corpo users might find this feature useful, you can create the cluster with an option -s /path/to/mysecret.properties which will then automatically provide credentials when pulling images.

What is the status now ?

easykube status

Inspecting binary dependencies
✓ kubectl 1.34.1 (~1.34)
✓ docker 28.4.0 (^28)
✓ helm 3.19.0 (~3.19)
✓ kustomize 5.7.1 (~5.7)

Container configuration
✓ easykube-registry container
✓ easykube-control-plane container
✓ easykube-registry connected to kind network

Repository configuration
✓ 13 addons discovered at '/home/jane/code/easykube-addons'
✓ dev build, skipping addon catalog compatibility check

All good. Easykube is ready for usage.

You might get a warning where easykube complains about a KUBECONFIG environment variable not being set. The warning provides a link on how to configure that.

Since easykube uses Kind, lets examine the running docker containers.

docker ps

...
a81acb9b11c9   kindest/node:v1.34.0   "/usr/local/bin/entr…"   29 minutes ago   Up 29 minutes   0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp, 127.0.0.1:40581->6443/tcp, 0.0.0.0:7233->30950/tcp, 0.0.0.0:6379->30971/tcp, 0.0.0.0:5432->32000/tcp   easykube-control-plane

132098d8a882   registry:2.8.3         "/entrypoint.sh /etc…"   29 minutes ago   Up 29 minutes   127.0.0.1:5001->5000/tcp   easykube-registry
...

We can see that kindest/node is running with a bunch of port-forwards, they were defined by the addons.

The registry is a local docker-registry. Most easykube addons should pull from that registry to avoid exessive bandwidth consumption.