README.md

Bakraid

Kubernetes distribution for easy cluster deployment and administration.

Table of contents

1. What is this
2. Design goals
3. Installation
4. Configuration charts
5. Available commands

What is this ?

Bakraid is built around kubeadm and provides features for bootstraping, expanding and shrinking a K8s cluster on a set of provisioned nodes with minimal configuration and reasonable defaults.

It bundles the following components together into a single cohesive distribution :

• cri-o as a container runtime.
• kubeadm for cluster bootstrapping and administration.
• CoreDNS for internal service discovery.
• flannel for pod networking.
• kube-vip to provide a highly available control plane.
• ingress-nginx as a default ingress controller.
• kubernetes-dashboard for cluster observability.
• helm for configuration and workloads management.

Design goals

1. Kubernetes complexity requires an opinionated approach : arrange some of its features into a distribution that covers a limited number of use cases.

2. Keeping kubernetes simple also requires specific infrastructure provisioning constraints, which are by themselves a limitation on supported use cases.

3. The main use case that this distribution aims to satisfy is running a fully functional kubernetes cluster on a set of nodes connected to the same private IPV4 subnetwork. This can be achieved whether the nodes are physical machines connected to a router or virtual machines created in a cloud environment.

4. The opinions that guided the design of this distribution are as follows :

   • Specify clear constraints for nodes and network provisioning.
   • Drop support for cloud-provided K8s features.
   • Build on top of kubeadm.
   • Run control plane components as static pods.
   • Stack etcd instances along control plane components.
   • Make the control plane highly available with kube-vip.
   • Limit kube-apiserver authentication strategies.
   • Use bash scripts, YAML files, Go templates and that's all.
   • Leverage helm features to their full extent.
   • Start the cluster with minimal defaults and make the rest optional.
   • No service discovery outside the cluster.
   • No self hosted image registries.

Installation

• Installation requires being logged as cluster admin on a node that satisfies the provisioning constraints :

# clone the repository
git clone https://github.com/mulekick/bakraid.git

# cd into the directory
cd bakraid

# install the required apt sources and packages
./bakraid install

Configuration charts

• Everything that is configurable in Bakraid lives in a set of helm charts.

• Some configuration values are cluster-specific while others are node-specific.

• Configuration values usually have to be reviewed and updated after installation :

  • Cluster-specific values must match the cluster the current node is meant to be a part of.
  • Node-specific values must match the current node's system and network configuration.

• Bakraid configuration charts are :

  chart	description
  kubeadm-config	kubeadm commands configuration
  kubevip-config	kube-vip static pod configuration
  cluster-defaults	Required default cluster configuration
  dashboard-config	kubernetes-dashboard configuration

• Configuration values must be reviewed prior to running any Bakraid command.

Available commands

Nodes management

• Those commands manage interactions between the current node and the cluster control plane.
• They are wrappers around kubeadm commands that will execute according to the current configuration.
• They may run on candidate nodes, control plane nodes or worker nodes depending on the case.

# candidate node : create node authentication assets for a new cluster
./bakraid utils reset

# candidate node : create the initial control plane node of a new cluster
./bakraid cluster up

# candidate node : join an existing cluster as a worker node
./bakraid cluster join

# candidate node : join an existing cluster as a control plane node
./bakraid cluster join --control-plane

# control plane node / worker node : leave an existing cluster
./bakraid cluster leave

# control plane node : teardown the last control plane node of an existing cluster
./bakraid cluster down

Note : since some commands required for cluster operation cannot be automated, Bakraid will warn when kubectl commands need to be executed following a Bakraid command. As a result, it is important to pay close attention to commands output and act as instructed.

Features management

• Those commands manage optional cluster workloads called features.
• They are wrappers around helm commands that will execute according to the current configuration.
• They require the admin kubeconfig file thus have to run on a control plane node.

# add / remove ingress controller
./bakraid feature add --ingress
./bakraid feature remove --ingress

# add / remove dashboard
./bakraid feature add --dashboard
./bakraid feature remove --dashboard

Cluster administration

• Those commands provide additional utilities to monitor and administer the cluster.
• They require the admin kubeconfig file thus have to run on a control plane node.

# print detailed cluster information
./bakraid utils status

# print detailed information about etcd nodes
./bakraid utils etcd

# print service account token for dashboard access
./bakraid utils token

# proxies kube-apiserver API to localhost
./bakraid utils proxy