iknite

README

Iknite

Manages the initialization and start of a Kubernetes mono-machine cluster on Alpine Linux.
Explore the docs »

Report Bug · Request Feature

Table of Contents

1. About The Project
   • How it works
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
• Alternative: Start through OpenRC
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

Iknite manages the initialization and start of a Kubernetes cluster in an Alpine based WSL 2 distribution or VM.

Iknite is part of the kaweezle project. Kaweezle allows running a Kubernetes cluster on Windows using Windows Subsystem for Linux 2 (WSL 2).

It is a small go based executable. It can be run from the command line or as an openrc based service.

It is packaged as an APK that is published in its own repository.

It used by the kaweezle-rootfs project (now deprecated) and is included in the WSL root filesystem available with each release (see below).

(back to top)

How it works

Under the hood, iknite uses kubeadm to install the cluster, and containerd as the container runtime. The APK package contains the relevant Alpine dependencies so everything is already available when iknite is first launched.

With kubeadm, you get a vanilla Kubernetes installation, with its pros and cons. There are more moving parts than in other light distributions but you won't be blocked because some feature has been removed.

Some additional components are also installed:

• flannel as the CNI (Common Network Interface) provider
• metrics-server for providing basic metrics to tools like K9s and for use by Horizontal Pod Autoscaling
• MetalLB allowing to created a LoadBalancer service.
• Local Path Provisioner to provide a default storage class bound to the local host filesystem.

This project uses the following popular go tools:

• cobra
• logrus
• client-go
• goreleaser for building and packaging
• ... (take a look at go.mod)

(back to top)

Getting Started

Please refer to the kaweezle readme for installation instructions.

The following sections gives instructions on how to use the root filesystem without the kaweezle windows command.

Prerequisites

To run kaweezle, you'll need to have WSL installed.

The simplest way to install it is to run the following command:

> wsl --install

After reboot, update the kernel and set the default version to version 2:

> sudo wsl --update
> wsl --set-default-version 2

For the other tools, you can use Scoop.

To use the kubernetes cluster, you will need to have kubectl installed:

> scoop install kubectl

(Optional) Other tools might be of interest, like k9s, kubectx, kubens or stern. All are available through scoop. You can install all of them at once with the following command:

> scoop install k9s kubectx kubens stern

Download and installation

The root filesystem can be downloaded from the Releases page.

You can create a WSL distribution with the following set of commands:

PS> cd $env:LOCALAPPDATA
PS> mkdir kwsl
PS> cd kwsl
# 500Mb download ahead
PS> (New-Object Net.WebClient).DownloadFile("https://github.com/kaweezle/iknite/releases/latest/download/kaweezle.rootfs.tar.gz", "$PWD\rootfs.tar.gz")
PS> wsl --import kwsl . rootfs.tar.gz
...
PS>

You will have a WSL distribution called kwsl which file system will be located in the current directory:

❯ wsl -l -v
  NAME                    STATE           VERSION
* Alpine                  Stopped         2
  kwsl                    Stopped         2

(back to top)

Usage

To start the kubernetes cluster, issue the following command:

❯ wsl -d kwsl /sbin/iknite -v info start -w 120
INFO[0000] Adding IP address                             iface=eth0 ip=192.168.99.2/24
INFO[0000] Check domain name to IP mapping...            domainName=kaweezle.local ip=192.168.99.2
INFO[0001] Mapping not found, creating...                domainName=kaweezle.local ip=192.168.99.2
INFO[0001] Starting openrc...
INFO[0003] Running/usr/bin/kubeadm init --config /tmp/config419805402.yaml...
INFO[0012] Applying base kustomization...                directory=/etc/iknite.d
INFO[0014] Configuration applied                         directory=/etc/iknite.d resources="..."
INFO[0014] Waiting for workloads for 120 seconds...
INFO[0014] Workloads total: 7, ready: 0, unready:7       ready=0 total=7 unready=7
INFO[0016] Workloads total: 7, ready: 0, unready:7       ready=0 total=7 unready=7
...
INFO[0066] Workloads total: 7, ready: 6, unready:1       ready=6 total=7 unready=1
INFO[0068] Workloads total: 7, ready: 7, unready:0       ready=7 total=7 unready=0
INFO[0068] executed

The distribution is now running:

❯ wsl -l -v
  NAME                    STATE           VERSION
* Alpine                  Stopped         2
  kwsl                    Running         2

Now the kubernetes cluster can be accessed:

❯ $env:KUBECONFIG="\\wsl$\kwsl\root\.kube\config"
❯ kubectl get nodes
NAME             STATUS   ROLES    AGE     VERSION
kaweezle.local   Ready    <none>   3m22s   v1.26.0
❯ kubectl get pod -A
NAMESPACE            NAME                                     READY   STATUS    RESTARTS        AGE
kube-flannel         kube-flannel-ds-nf9z2                    1/1     Running   0               3m43s
kube-system          coredns-787d4945fb-vdv7s                 1/1     Running   0               3m43s
kube-system          coredns-787d4945fb-zxdnc                 1/1     Running   0               3m43s
kube-system          etcd-kaweezle.local                      1/1     Running   0               3m58s
kube-system          kube-apiserver-kaweezle.local            1/1     Running   0               3m58s
kube-system          kube-controller-manager-kaweezle.local   1/1     Running   0               3m57s
kube-system          kube-proxy-hgzvk                         1/1     Running   0               3m43s
kube-system          kube-scheduler-kaweezle.local            1/1     Running   0               3m56s
kube-system          metrics-server-699cfc467c-jn28p          1/1     Running   0               3m43s
local-path-storage   local-path-provisioner-8bc8875b-p7tqp    1/1     Running   0               3m43s
metallb-system       controller-577b5bdfcc-8grxd              1/1     Running   1 (3m10s ago)   3m43s
metallb-system       speaker-4p5b2                            1/1     Running   0               3m43s

You can now deploy anything on the cluster. As in contains MetalLB, Any ingress controller (Traefik, for instance) can be installed and be available locally.

(back to top)

Alternative: Start through OpenRC

Instead of running iknite to start the cluster, you can enable the iknite-config service with OpenRC:

PS> wsl -d kwsl rc-update add iknite-config default

And then the cluster is started and restarted with:

PS>  wsl -d kwsl openrc default
 * Caching service dependencies ...                                       [ ok ]
 * Starting containerd ...                                                [ ok ]
 * Running iknite start ...                                               [ ok ]
 * Running iknite config ...                                              [ ok ]

This is useful to integrate iknite in a VM or to add other downstream services to OpenRC.

(back to top)

Roadmap

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the Apache License. See LICENSE for more information.

(back to top)

Contact

Kaweezle - @kaweezle

Project Link: https://github.com/kaweezle/iknite

(back to top)

Acknowledgements

This project started from the amazing work made by yuk7 with wsldl and AlpineWSL.

It also uses the great work made by the Alpine Linux community on the edge repository.

You may be interested by existing alternatives from which we have taken some ideas:

• Rancher Desktop
• Minikube
• Kind

By using kubeadm and Alpine, kaweezle is closer to the clusters you may use on public clouds.

This readme has has been created from the Best-README-Template project.

(back to top)

Documentation

Overview

Copyright © 2021 Antoine Martin <antoine@openance.com>

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.