Myks

Manage (my) yaml for Kubernetes simply. Or something like that.

Myks is a tool and a framework for managing the configuration of applications for multiple Kubernetes clusters. It helps to reuse, mutate, and share the configuration between applications and clusters.

Basically, myks downloads sources and renders them into ready-to-use Kubernetes manifests.

Features

create and reuse application "prototypes" combining helm charts, ytt templates and overlays, and plain YAML files;
download and cache third-party configurations from various sources (anything that is supported by vendir: helm charts, git repositories, GitHub releases, etc.);
maintain a single source of truth for all clusters' manifests;
render manifests, validate and automatically inspect them before applying;
smart detection of what to render based on what was changed;
integrate with ArgoCD;
apply changes to all applications in all clusters at once or to a specific subset;
plugins support for extending myks with custom tools.

How does it work?

Myks consumes a set of templates and values and renders them into a set of Kubernetes manifests. It is built on top of vendir for retrieving sources and on top of ytt for configuration.

Hands on

Here's a quick example:

# Switch to an empty directory
cd "$(mktemp -d)"

# Initialize a repository
git init

# Make an initial commit
git commit --allow-empty -m "Initial commit"

# Initialize a new project with example configuration
myks init

# Optionally, check the generated files
find

# Sync and render everything
myks all

# Check the rendered manifests
find rendered

Installation

Depending on the installation method and on the desired features, you may need to install some of the tools manually:

helm is only needed for rendering Helm charts
ytt and vendir are now built into myks, no need to install separately.

At the moment, we do not track compatibility between versions of these tools and myks. Fairly recent versions should work fine.

AUR

On Arch-based distros, you can install myks-bin from AUR:

yay -S myks-bin

APK, DEB, RPM

See the latest release page for the full list of packages.

Docker

See the container registry page for the list of available images. The image includes the latest versions of helm.

docker pull ghcr.io/mykso/myks:latest

Homebrew

brew tap mykso/tap
brew install myks

Download manually

Download an archive for your OS from the releases page and unpack it.

Build from source

Get the source code and build the binary:

git clone https://github.com/mykso/myks.git
# OR
curl -sL https://github.com/mykso/myks/archive/refs/heads/main.tar.gz | tar xz

cd myks-main
go build -o myks main.go

Usage

To become useful, myks needs to be run in a project with a particular directory structure and some basic configuration in place. A new project can be initialized with myks init (see an example).

Myks has two main stages of operation and the corresponding commands: sync and render. During the sync stage, myks downloads and caches external sources. Final kubernetes manifests are rendered from the retrieved and local sources during the render stage.

The all command runs the both stages sequentially for convenience.

These commands (sync, render, all) accept two optional arguments: environments and applications to process. When no arguments are provided, myks will use the Smart Mode to detect what to process.

Tip

Check the optimizations page to get most of myks.

Examples

A few example setups are available in the examples directory.

And here are some real-world examples:

zebradil/myks-homelab: single cluster setup with ArgoCD for deployment and sops for secrets management;
kbudde/lab: single cluster setup with [kapp] for deployment and sops for secrets management;

Running `sync` against protected repositories and registries

Vendir uses secret resources to authenticate against protected repositories. These are references by the vendir.yaml with the secretRef key.

Myks dynamically creates these secrets based on environment variables prefixed with VENDIR_SECRET_. For example, if you reference a secret named "mycreds" in your vendir.yaml, you need to define the environment variables VENDIR_SECRET_MYCREDS_USERNAME and VENDIR_SECRET_MYCREDS_PASSWORD. The secrets are cleaned up automatically after the sync is complete.

Development

Prerequisites

For building and contributing:

Go 1.22+
goreleaser 1.18+
optional:
- task 3.27+
- lefthook 1.4+
- gofumpt 0.5+
- golangci-lint 1.53+
- commitlint 17.6+

For running:

helm 3.12+

Build

$ task go:build
$ # or, if task or goreleaser aren't installed, just
$ go build -o myks ./cmd/myks

Test

$ # Switch to an empty directory
$ cd $(mktemp -d)
$ # Initialize a repository
$ git init
$ # Make an initial commit
$ git commit --allow-empty -m "Initial commit"
$ # Initialize a new myks project
$ myks init
$ # Optionally, check the generated files
$ find
$ # Sync and render everything
$ myks all envs --log-level debug

Motivation

The original idea grew out of the need to maintain applications in a constantly growing zoo of Kubernetes clusters in a controlled and consistent way.

Here are some of the requirements we had:

to be able to create and maintain configurations of multiple applications for multiple clusters;
to provide compatibility tools for different Kubernetes flavors (e.g. k3s, Redshift, AKS) and versions;
to be able to consume upstream application configurations in various formats (e.g. Helm, kustomize, plain YAML);
to have automatic updates and version management;
to provide a single source of truth for the configuration.

mykso/myks