Metadata-Version: 2.4
Name: kubeyard
Version: 1.4.0
Summary: A utility to develop, test and deploy Kubernetes microservices.
Home-page: https://github.com/socialwifi/kubeyard
Author: Social WiFi
Author-email: it@socialwifi.com
License: BSD
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click
Requires-Dist: colorlog
Requires-Dist: jinja2
Requires-Dist: kubepy>=1.21.0
Requires-Dist: pyYAML
Requires-Dist: cached-property
Requires-Dist: sh<2
Requires-Dist: pyfiglet
Requires-Dist: termcolor
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# kubeyard
[![Latest Version](https://img.shields.io/pypi/v/kubeyard.svg)](https://pypi.python.org/pypi/kubeyard/)
[![Supported Python versions](https://img.shields.io/pypi/pyversions/kubeyard.svg)](https://pypi.python.org/pypi/kubeyard/)
[![Wheel Status](https://img.shields.io/pypi/wheel/kubeyard.svg)](https://pypi.python.org/pypi/kubeyard/)
[![License](https://img.shields.io/pypi/l/kubeyard.svg)](https://github.com/socialwifi/kubeyard/blob/master/LICENSE)
[![Build](https://img.shields.io/circleci/project/github/socialwifi/kubeyard/master.svg)](https://circleci.com/gh/socialwifi/kubeyard)


A utility to develop, test and deploy Kubernetes microservices.

## What it does

kubeyard gives a microservice repository one set of commands that behave the
same for everyone who runs them:

    kubeyard build      # build the image
    kubeyard test       # run the suite inside it
    kubeyard deploy     # apply the project's Kubernetes definitions
    kubeyard shell      # exec into the running pod

In development it drives a local minikube cluster: it provisions the
dependencies the project declares (PostgreSQL, RabbitMQ, Redis and so on),
creates the databases they need, and mounts your working copy into the pod, so
edits take effect without rebuilding the image. In production the same
definitions are applied to the real cluster through
[kubepy](https://github.com/socialwifi/kubepy).

A project describes itself in `config/kubeyard.yml` and keeps its Kubernetes
definitions in `config/kubernetes/`, where `development_overrides/` is merged on
top of `deploy/` in development only. Any command can be replaced by an
executable of the same name in the project's `scripts/` directory, which is how
a project adds a step without forking the tool.

## Requirements

- bash
- minikube
- kubectl
- docker
- conntrack

**Important:** Kubeyard is tested on:

- minikube == v1.29.0 (should work with v1.29.0 and above)
- docker == 20.10.23 (should work with any version)
- kubectl == v1.21.14 (should work with v1.21.14 and above)

## Installation

```bash
rm -rf $HOME/kubeyard-venv
virtualenv -p python3 $HOME/kubeyard-venv
. $HOME/kubeyard-venv/bin/activate
pip install kubeyard
echo '. $HOME/kubeyard-venv/bin/activate' >> $HOME/.bashrc
```

## Configuration

Settings come from three layers, each overriding the one before:

1. defaults built into kubeyard
2. the project's `config/kubeyard.yml`
3. your `~/.kubeyard/context.yml`

Your own file wins over everything, so keep it to machine-wide settings such as
`KUBEYARD_MODE` or `KUBEYARD_VM_DRIVER`. A project-level key placed there applies
to every project on the machine, and no project can override it: if one of them
needs a different value, it has no way to ask for one.

Every context key is exported as an environment variable to custom scripts and
to Docker builds.

Keys kubeyard defines belong to exactly one of those layers, and putting one in
the wrong file is an error rather than a surprise:

- `base_domain` is machine-wide, so it can only be set in `~/.kubeyard/context.yml`.
  One `global` ConfigMap serves every service in a namespace, so no single project
  can own its value.
- everything else describes a project, so only `config/kubeyard.yml` may set it.
  The user file would apply it to every project on the machine, with no way for
  any of them to ask for a different value.

Keys kubeyard does not define are yours, and can be set in either file.

### base_domain

`base_domain` is the domain this environment serves. It goes into the `global`
ConfigMap and reaches every container as `BASE_DOMAIN`, so services can build
their own URLs without hardcoding an environment into their code. Inside a
workspace it is qualified with the workspace name.

It has no default. `kubeyard setup` asks for it and writes it to your user
context, or pass `--base-domain`:

    kubeyard setup --development --base-domain example.test

In production `kubeyard setup` will not replace a `global` ConfigMap that
already exists; it reports what is there and what it would have written. Pass
`--replace-global-configmap` if you really want it overwritten.

## Workspaces

A workspace is an isolated development environment: one Kubernetes namespace
(`ws-<name>`) holding the services you are changing, with every other service
aliased back to `default`. This lets several coding agents, or several features
in flight, run concurrently in separate git worktrees without colliding.

    kubeyard workspace create example
    cd .worktrees/example
    kubeyard build && kubeyard deploy

`create` makes the git worktree too, on a branch `ws-<name>`, and prints the
path to `cd` into, along with how to tear it down again.

The workspace is recorded in a `.kubeyard-workspace` file in the worktree, so
every later command picks it up automatically. Add both that filename and
`.worktrees/` to the repository's `.gitignore`.

    kubeyard workspace show       # what is deployed here versus aliased
    kubeyard undeploy             # put this service back on the shared instance
    kubeyard workspace destroy    # remove the whole workspace

### Seeding development data

A project can declare how to load its development data:

```yaml
dev_seed_command: python -m tests.demo
dev_seed_pod: api            # optional; defaults to the shortest running pod name
```

`kubeyard seed` then runs that command inside the deployed pod, in the namespace
kubeyard already knows - so from a workspace it seeds that workspace's database.

`deploy` runs it for you when it has just created the database - so a new workspace,
or a new checkout of the shared environment, comes up with data already in it. A
redeploy finds the database present and leaves it alone.

Without a `.kubeyard-workspace` file, kubeyard behaves exactly as it always has
and targets the shared environment.

See [docs/workspaces.md](docs/workspaces.md) for why workspaces exist, how the
alias overlay works, and the limits worth knowing before relying on them.

## Claude Code

This repository is also a Claude Code plugin marketplace. The plugin teaches
Claude to reach for a workspace rather than a bare `git worktree add`, and
documents the command surface in one place instead of in every project's
`CLAUDE.md`, where nothing updates it when kubeyard changes.

    /plugin marketplace add socialwifi/kubeyard
    /plugin install kubeyard@kubeyard

It adds two skills, `kubeyard:workspaces` and `kubeyard:usage`, and a hook that
warns when `git worktree add` is run in a kubeyard project. `jq` is required.

See [plugins/kubeyard/README.md](plugins/kubeyard/README.md) for what each part
does and how to make the hook block rather than warn.
