Getting Started

lok8s is a Kubernetes deployment framework distributed as a b environment. It provides a single CLI (lo), a single folder convention (.lok8s/), and the same workflow from local development to production.

Prerequisites

Docker — that's it. It is the only tool you install yourself.

Everything else the framework needs — kind, kubectl, kustomize, yq, Tilt, mkcert, Helm, and the rest of your profile's toolchain — ships pinned inside the lok8s environment and lands in your project's .bin/ with a single command (b install; see Installation below). Nothing touches your system, versions are locked per project, and teammates get the identical toolchain from the committed b.yaml/b.lock.

Installation

lok8s is distributed as a b environment with five profiles. Pick the one that matches your use case:

Profile	Includes	Use case
core	—	Remote deploy only (framework + lok8s.dev default domain, no kind/Tilt)
kustomize	—	Kustomize plugins only (standalone build artifacts)
local	core + kustomize	Local dev — kind + Tilt + mkcert on top of core
capi	local	Cluster API provisioning (adds clusterctl, hcloud)
kubeone	local	KubeOne provisioning (adds kubeone, hcloud)

# Install b if you haven't already
curl -fsSL https://raw.githubusercontent.com/fentas/b/master/install.sh | bash

# Most users want local dev
b env add github.com/kernpilot/lok8s#local

# Sync into your project
b sync

This copies the CLI, libraries, driver contracts, kustomize plugins, templates, and (for local+) the Tilt extension into your project. Each profile ships only the binaries it actually needs.

Joining a project that already uses lok8s? Then the toolchain is already declared — clone and run a single command:

b install   # exact pinned toolchain from the committed b.yaml / b.lock

The default lok8s.dev domain

Every profile includes clusters/lok8s.dev/ — a preconfigured cluster domain that works out of the box on a local Docker bridge with TLS. You don't need to bring your own domain to get started; just lo use lok8s.dev && lo up.

You can also bring your own FQDN (example.com, infra.example.net, etc.) as an additional domain, or run multiple projects on *.[1-100].lok8s.dev subdomains. See Concepts for the FQDN convention.

Project Structure After Sync

Everything lok8s ships lives under .lok8s/ — a flat, framework-owned tree synced from upstream. Your cluster definitions live under clusters/, one folder per FQDN. Your project's own files live at the repo root alongside Tiltfile and services.yaml.

your-project/
  .lok8s/                      # framework (synced via b — don't edit)
    lo                         # CLI entrypoint (argsh script)
    libs/                      # shared bash libraries
    utils/                     # shared helpers
    addons/                    # bootstrap addons (cilium, metallb, ...)
    drivers/                   # cluster drivers (lo, capi, kubeone, kkp)
    providers/                 # infra providers (hetzner, ...)
    tilt/                      # Tilt extension
      Tiltfile                 # the lok8s() extension function
  clusters/                    # your cluster definitions
    lok8s.dev/                 # local dev domain (template)
      cluster.lok8s.yaml       # cluster spec
      targets/                 # kustomize targets
      artifacts/               # built output (gitignored)
  .kustomize/                  # kustomize plugin discovery (built binaries)
  Tiltfile                     # bootstrap: load('./.lok8s/tilt/Tiltfile', 'lok8s')
  services.yaml                # service definitions (your stuff)
  .envrc                       # direnv: PATH_BASE, PATH_LOK8S, PATH_CLUSTERS, ...

The .lok8s/ and .lok8s/tilt/ directories are framework code synced from upstream by b env-sync. To override or extend behavior, prefer services.local.yaml (gitignored) or wrapping the CLI in your own script — modifying the synced files directly will be overwritten on the next sync.

Your First Cluster

1. Set the active domain

lo use lok8s.dev

2. Start the local cluster

lo up

This provisions a kind cluster — registry mirrors, CoreDNS, TLS certificates, and the spec.bootstrap addons (Cilium by default) — then starts Tilt for live service development. Workload targets are built and deployed with lo build and lo deploy.

3. Check status

lo status

4. Tear it down

lo down

What's Next

• Concepts — domains, targets, bootstrap addons, the driver contract
• Addons — write and reference framework-local addons
• Local Dev with Tilt — configure services for live reload
• CLI Reference — all lo subcommands