Kubepile

Have you ever tried to maintain a Kubernetes config for multiple clusters, and multiple Kubernetes providers? It's gross! It's hard to visually track which users, clusters, and contexts relate to each other, and as you add and remove clusters your config inevitably bloats into a mess and becomes hard to reason about.

Kubepile lets you maintain individual, per-provider kubeconfigs in a ~/.config/kubepile directory, and compile them into a single, merged kubeconfig.

Kubepile exposes a tiny set of commands to manage your configs:

• compile: compile your Kubepile configs into a merged kubeconfig
• source: set a specific context as your default for the current shell
• split: decompile an existing, messy kubeconfig into nice, clean Kubepile configs

Install

npm install -g kubepile

Kubepile also includes a small shell helper that you need to install once:

kubepile install

Once you've installed the shell helper, either start a new shell or re-source your .zshrc/.bashrc/.profile/etc. Kubepile supports Zsh, Bash, and Fish.

Kubepile configs

Each *.yaml file is a normal kubeconfig. You can paste in kubeconfigs from providers without converting them to a kubepile-specific schema. During compile, kubepile reads every file and merges its clusters, users, and contexts directly into the generated kubeconfig.

Kubepile automatically ensures the following:

• No kubepile files set a current-context.
• No cluster, user, or context names clash.

If a new file is added that clashes or sets a current-context, kubepile will intentionally fail compilation with a helpful message explaining which file broke the kubepile rules.

Kubepile will never set a current-context, out of the design belief that setting a global, cross-shell-session current-context is a dangerous footgun in multi-cluster setups. Instead, use kubepile source <context> to temporarily set a default context for your current shell session.

Compile

kubepile compile

This reads ~/.config/kubepile/*.yaml, then writes ~/.kube/config. If ~/.kube/config already exists, kubepile compile prompts before copying it to ~/.kube/config.bak.

Kubepile skips that backup prompt for safe rebuilds. A rebuild is safe when the existing generated kubeconfig can be reproduced from a subset of the current *.yaml files. In practice, this means no-op rebuilds and adding a new provider file do not ask for a backup. If the existing generated kubeconfig was manually edited, was not generated by kubepile, or can no longer be reproduced from the current inputs, kubepile asks before replacing it.

Explicit command and options:

kubepile compile --config-dir ~/.config/kubepile --output ~/.kube/config
kubepile compile --backup
kubepile compile --no-backup

Running kubepile with no command prints help.

Source

kubepile source <context> switches your current shell to use a specific Kubernetes context by default by creating a temporary kubeconfig with that context set as the current-context, and exporting KUBECONFIG to point at it. It also prefixes your shell prompt with the context name.

kubepile source prod
# Your shell prompt is now:
# (prod) WHATEVER_YOUR_OLD_PROMPT_WAS
# All kubectl commands will use the prod context

To list available contexts:

kubepile source --list

To switch to a different context, just run the source command with a new context:

kubepile source dev

Note that this requires installing the shell helpers listed in the installation instructions. If you haven't installed them yet, install them with:

kubepile install

And re-source your main shell config (such as e.g. a .zshrc) or start a new shell.

Split

Do you already have a giant unmaintainable mess of a kubeconfig? No worries! Kubepile ships a split command that auto-splits your existing kubeconfig into separate per-context kubepile config files, and tells you on the command line if you have unsplittable configs due to impossible settings from config drift — and which keys exactly are the problem, so you can clean up your config before splitting it.

To split your config, run:

kubepile split

This reads ~/.kube/config and writes one kubeconfig per context into ~/.config/kubepile.

If there are errors in your kubeconfig that prevent splitting, it'll tell you what they are.

You can optionally override the source kubeconfig and the output kubepile directory. These are the defaults:

kubepile split --source ~/.kube/config --output-dir ~/.config/kubepile

Context names that are not safe as filenames are percent-encoded when split.