Kubash: The Unix-Philosophic Shell Pipeline for Rapid Kubernetes Clusters

Deploying Kubernetes clusters across heterogeneous environments often turns into an exercise in frustration. Sprawling enterprise playbooks, opaque installer binaries, and heavyweight configuration management engines frequently obscure what is actually happening at the operating system layer. When an orchestration run fails midway through a 500-step task graph, debugging the root cause often requires sifting through megabytes of unhelpful YAML abstractions.

Kubash was created out of a desire to return to the core tenets of the Unix philosophy: simplicity, modularity, and transparency. Hosted on GitHub, Kubash (K8$) is a lightweight, forkable shell pipeline engineered to build, provision, initialize, equip, and tear down production-ready Kubernetes clusters PDQ (Pretty Darn Quick).

The Philosophy: Why Shell & Native Hypervisors?

Kubash began its journey when complex multi-thousand-line automation frameworks repeatedly failed during routine upstream version migrations. The goal became clear: strip away unnecessary layers of indirection and build a transparent pipeline where every stage is composed of clear, composable CLI tools.

Instead of hiding virtualization behind proprietary hypervisor APIs, Kubash relies on KVM/QEMU first and foremost. Because KVM is built directly into the Linux kernel, spinning up node instances requires zero third-party agent daemons or external hypervisor licenses.

The lifecycle is divided into four cleanly decoupled phases:

+------------------+     +--------------------+     +-------------------+     +---------------------+
|  1. BUILD IMAGE  | --> |   2. PROVISION     | --> |   3. INITIALIZE   | --> |     4. ADDONS       |
|  Packer + QEMU   |     | KVM / QEMU Domains |     |  Kubeadm / HA     |     | Helm Charts & CNI   |
+------------------+     +--------------------+     +-------------------+     +---------------------+

Build: Compiles a pristine base OS image using HashiCorp Packer and rebases it with necessary kernel modules, container runtimes, and CNI prerequisites.
Provision: Deploys the cluster topology definitions to KVM/QEMU domains (with support for additional provisioners).
Initialize: Orchestrates node bootstrapping directly with kubeadm (or alternative engines such as Kubespray or OpenShift).
Addons: Installs baseline infrastructure components, network overlays, and Helm charts.

Installation & Rapid Bootstrap

Getting started with Kubash can be done via a single bootstrap command:

curl -L git.io/kubash | bash

Alternatively, clone the repository directly from GitHub:

git clone https://github.com/kubash/kubash.git
cd kubash
make install

Verify your environment and local KVM virtualization support:

kubash --version
kvm-ok

Defining and Spinning Up a Cluster

Kubash drives cluster specifications via declarative YAML manifests that map out control plane nodes, worker nodes, CPU allocations, memory boundaries, and network interfaces.

1. Cluster Manifest (`example-cluster.yaml`)

cluster:
  name: "tekro-dev01"
  network:
    subnet: "192.168.122.0/24"
    gateway: "192.168.122.1"
    domain: "k8s.local"
  nodes:
    - name: "master-01"
      role: "control-plane"
      cpu: 4
      memory: 8192
      ip: "192.168.122.10"
    - name: "worker-01"
      role: "worker"
      cpu: 4
      memory: 16384
      ip: "192.168.122.20"
    - name: "worker-02"
      role: "worker"
      cpu: 4
      memory: 16384
      ip: "192.168.122.21"

2. Generate Cluster Topology

Convert the declarative manifest into a cluster definition:

kubash -n tekro-dev01 yaml2cluster examples/example-cluster.yaml
ls -la clusters/tekro-dev01

3. Build the Base Target Image

Kubash uses Packer to produce clean, reproducible images tailored to your specific OS distribution and Kubernetes release:

# Build Ubuntu Jammy with target Kubernetes 1.30
kubash build --target-os jammy1.30.1

For immutable operating systems like CoreOS, Kubash features an alternative streamlined builder that directly fetches, verifies, and patches official vendor images with ignition configs.

4. Provision Node Virtual Machines

Once the base image is built, provision the defined KVM/QEMU domains:

kubash provision -n tekro-dev01

This allocates disk overlays (backing onto the golden base image for copy-on-write speed), configures virsh XML profiles, attaches tap network bridges, and boots the guest VMs in parallel.

5. Initialize the Cluster

With instances online, initialize the control plane and join worker nodes:

kubash -n tekro-dev01 init

By default, this invokes a clean kubeadm init sequence on master-01, captures the cluster join token and CA certificate hash, securely propagates credentials to worker nodes, and executes kubeadm join.

Dynamic Verbosity & Operational Debugging

Kubash adheres to quiet-by-default execution so automated CI/CD runners aren’t overwhelmed with useless stdout logs. However, when troubleshooting low-level networking or kernel issues, Kubash provides full visibility across all underlying toolchains:

# Crank up verbosity via CLI flags
kubash -n tekro-dev01 -vvvv init

# Or export via environment variable for automated pipelines
export VERBOSITY=100
kubash -n tekro-dev01 init

Kubash stdout logs are clearly indexed by hierarchical # markers:

############# Kubash, by Josh Cox
############# Stage: Node Provisioning [tekro-dev01]
### Validating QEMU/KVM virsh bridge connectivity...
### Attaching disk overlay: tekro-dev01-master-01.qcow2 -> base-jammy1.30.1.qcow2
### Generating cloud-init user-data and network-config...
### Domain master-01 created and started.
### Waiting for SSH availability on 192.168.122.10:22... [OK]

Alternative Pipelines & Extensibility

One of the greatest strengths of Kubash is its modularity. Because each stage is decoupled, you are never locked into a single initialization strategy:

Alternative Builders: Swap between Packer image builders, cloud image pullers, or bare metal PXE boot configurations.
Alternative Initializers: In addition to standard kubeadm, operators can plug in Ansible playbooks using Kubespray, OpenShift installers, or kubeadm2ha for highly available multi-master etcd topologies.
Automated Teardowns: Decommission clusters as quickly as you build them, purging libvirt domains, storage volumes, and network bridges in seconds:
```
kubash -n tekro-dev01 decommission
```

Resources & Community

Whether you are spinning up rapid local test clusters for eBPF kernel research, validating CI pipelines on bare metal, or orchestrating self-hosted lab environments, Kubash gives you direct control over your infrastructure without unnecessary complexity.

Official Website: https://kubash.org
Source Code & Issue Tracker: https://github.com/kubash/kubash
Author & Maintainer: Joshua Edward McLaughlin Cox