Overview

Under Construction

Docs are a work in progress, but you'll still find lots of working examples and hands-on tutorials. This is a sibling project for compose.mk, which is a more general automation framework; The k8s-tools suite serves as a reference implementation for extending it.

Meet the k8s-tools suite, which aggregates 30+ individual utilities for working with kubernetes into a single dockerized toolchain, and provides an automation framework for extending and interacting it. Project-local clusters, cluster lifecycle automation, customizable TUIs, and more, with no dependencies at all beyond what's already in your dev environment.

The k8s-tools suite operates at a project-automation layer that is designed to embrace and extend other tools, so it doesn't really conflict or compete with anything. It's especially useful for CI/CD pipelines or prototyping systems, and is designed to be embedded alongside existing projects.

Tool-container definitions use docker-compose, and the automation framework is Makefile-based.

What does it do?

Individual utilities in the toolbox work as usual on any sort of kubernetes platform, regardless of where or how it's hosted. But there's also a major emphasis on the kind of project-local clusters that you might be interested in for local-first development, platform-agnostic end-to-end tests, etc. To that end, the toolbox incorporates dockerized versions of k3d, kind, and minikube, and scripting that makes use of those containers is easy.

Use Cases:

  1. Cluster lifecycle / development / debugging workflows in general.
  2. Project-local kubernetes clusters & corresponding lifecycle automation.
  3. Decoupling project automation from the choice of CI/CD backend.
  4. Separation of automation tasks from runtime / container context specs.
  5. Per-project tool-versioning, providing defaults but allowing overrides
  6. Less automation code in general, with what's left being more modular and composable
  7. Decoupling and sharing automation, without locking it away inside Jenkinsfiles, Tiltfiles, Github Actions

Another use-case is actually executable tutorials / prototypes / PoCs, somewhat in the spirit of literate programming. Although some infrastructure-as-code ships with a tidy example repository.. lots of documentation refers to a long list of instructions you're supposed to copy/paste into a terminal, and expects you to bring your own cluster.

This reference aims to collect simple, self-contained demos for complex systems, basically striving for bootstrapping won't pester you to install things first or expect you to bring your own cluster, yet can be extended easily to use remote clusters.

How does it do it?

At a high level, the k8s-tools suite has 2 main components that can be used individually or together. Those components are a collection of tool-container definitions, and an automation framework for extending and interacting with the containers.

k8s-tools.yml

Aggregates 30+ individual utilities for working with kubernetes in one place, hosted inside a single docker-compose file. Official sources are used where possible and containers defined here aren't built from scratch. Low-level tools (like kubectl, helm, etc) mostly come from alpine/k8s but many other tools (like argo, helm, knative, cdk, k9s, k3d, ansible, etc) are also included. Tools containers are versioned independently, using defaults but allowing overrides, and are pulled only if/when they are used.

k8s.mk

A library/utility that builds on k8s-tools.yml, providing powerful ways to run automation inside the tool-containers and script orchestration across them. As a stand-alone utility, k8s.mk can enable interactive workflows like inspection and debugging. As a library, it's especially useful for prototyping, and you can very quickly build on it to express custom project automation that's surprisingly portable, powerful, and flexible.

Getting Started

If you're waiting to learn more about what the k8s-tools suite can do, start at the main demo for cluster lifecycle management. Jump directly to the quickstart if you want to start experimenting, or the introduction to automation if you want to read a bit first.