Quickstart

Installation

The typical installation for the k8s-tools suite involves a few components, and is based on the assumption that you probably want to embed and potentially modify the pieces inside some existing project you've already started. In other words: fork and forget.

So basic installation is just copying files and making them executable:

$ cd myproject 

# Download compose.mk, k8s.mk, and k8s-tools.yml
$ curl -sLo compose.mk \
    https://raw.githubusercontent.com/Robot-Wranglers/k8s-tools/main/compose.mk
$ curl -sLo k8s.mk \
    https://raw.githubusercontent.com/Robot-Wranglers/k8s-tools/main/k8s.mk
$ curl -sLo k8s-tools.yml \
    https://raw.githubusercontent.com/Robot-Wranglers/k8s-tools/main/k8s-tools.yml

# Make scripts executable
$ chmod +x compose.mk k8s.mk k8s-tools.yml

# Now equivalent to `make -f ...`
$ ./compose.mk ...
$ ./k8s.mk ...

# Now equivalent to `docker compose -f k8s-tools.yml ...`
$ ./k8s-tools.yml ...

That's it, and at this point you can already do lots of stuff by using k8s.mk in tool mode. With the fork-and-forget approach, you can also strip containers you know that you'll never use from the toolbox, and add new ones.

Read on for info about tighter project integration, library usage, and scripting.

Single File

Experimental

Bundling for the single-file installation works fine for simple things, but isn't exercised yet by automated tests, and some advanced features of compose.mk might unavailable.

If you want fewer files, already know that you're not interested in extending k8s.mk or adjusting details for the tool-containers, you can opt instead for the monolithic install that bundles all 3 files together.

$ cd myproject 

# Download compose.mk, k8s.mk, and k8s-tools.yml
$ curl -sLo compose.mk \
    https://raw.githubusercontent.com/Robot-Wranglers/k8s-tools/main/k8s
$ chmod +x ./k8s

# Alternatively, generate `k8s` omnibus from existing files:
$ bin=./k8s ./compose.mk mk.fork/k8s.mk,k8s-tools.yml

For more background and details building bundles from scratch, see the upstream docs.

Project Integration

For library usage from your project automation and for orchestrating stuff in the toolbox, you'll want something like this inside your project Makefile:

# Include the `k8s.mk` library
include k8s.mk

# Generate target scaffolding for the tool containers
$(call compose.import, file=k8s-tools.yml)

For the monolithic install, the compose.import is implied, so just use include k8s.

Local Clusters

Tip

Local clusters with lots of containers might require increasing the OS limits for open-files. See the kind docs for hints about increasing this value.

Using local clusters isn't required, but it is a typical use-case and one thing that k8s.mk specializes in. Besides the caveat for open-files, this requires no additional setup and has no extra dependencies. For an overview, see the intro to local clusters, and for an example you can pick a random demo since most will involve some kind of cluster-lifecycle management.

For Developers

To run demos yourself, clone the repository.

# For ssh
$ git clone git@github.com:Robot-Wranglers/k8s-tools.git

# Or for http
$ git clone https://github.com/Robot-Wranglers/k8s-tools.git

# Pre-cache for main containers
$ make build 

# Run all the demos
$ make demos

# Run only CMK-lang demos
$ make demos/cmk