![Bonny](./banner.png "Bonny")

[![Build Status](](
[![Coverage Status](](
[![Documentation]( hexdocs-green.svg)](

# Bonny

Kubernetes Operator SDK written in Elixir. 

Extend the Kubernetes API and implement CustomResourceDefinitions lifecycles in Elixir.

If Kubernetes CRDs and controllers are new to you, read up on the [terminology](#terminology).

## Installation

If [available in Hex](, the package can be installed
by adding `bonny` to your list of dependencies in `mix.exs`:

def deps do
    {:bonny, "~> 0.1"}

Add to `config.exs`:

config :bonny, 
  # Add each CRD Controller module for this operator to load here
  controllers: [
  # Set the Kubernetes API group for this operator.
  # This can be overwritten using the @group attribute of a controller
  group: "your-operator.your-domain.tld", 

  # Name must only consist of only lowercase letters and hyphens.
  # Defaults to "bonny"
  operator_name: "your-operator"

  # Name must only consist of only lowercase letters and hyphens.
  # Defaults to operator name
  service_account_name: "your-operator"

  # Kubernetes YAML config, defaults to the service account of the pod
  kubeconf_file: "",
  # Defaults to "current-context" if a config file is provided, override user, cluster. or context here
  kubeconf_opts: []

## Bonny Generators

There are a number of generators to help create kubernetes manifests.

`mix help | grep bonny`

### Generating an operator controller

An operator can have multiple controllers. Each controller handles the lifecycle of a custom resource.

By default controllers are generated in the `V1` version scope.

mix bonny.gen.controller Widget widget

You can specify the version flag to create a new version of a controller. Bonny will dispatch the controller for the given version. So old versions of resources can live alongside new versions.

mix bonny.gen.controller Widget widget --version v2alpha1

*Note:* The one restriction with versions is that they will be camelized into a module name.

Open up your controller and add functionality for your resoures lifecycle:

* Add
* Modify
* Delete

Each controller can create multiple resources. 

For example, a *todo app* controller could deploy a `Deployment` and a `Service`.

Your operator can also have multiple controllers if you want to split up your lifecycle logic!

Check out the two test controllers:

* [Cog](./test/support/cog.ex)
* [Widget](./test/support/widget.ex)

### Generating a dockerfile

The following command will generate a dockerfile *for your operator*. This will need to be pushed to a docker repository that your kubernetes cluster can access.

Again, this Dockerfile is for your operator, not for the pods your operator may deploy.

mix bonny.gen.dockerfile

docker build -t ${BONNY_IMAGE} .
docker push ${BONNY_IMAGE}:latest

### Generating Kubernetes manifest for operator

This will generate the entire manifest for this operator including:

* CRD manifests
* Service Account
* Operator Deployment

mix bonny.gen.manifest --out manifest.yaml

**Note:** YAML output is JSON formatted YAML. Sorry, elixirland isn't fond of YAML :D

By default the manifest will generate the service account and deployment in the "default" namespace.

*To set the namespace explicitly:*

mix bonny.gen.manifest --out - -n test

*Alternatively you can apply it directly to kubectl*:

mix bonny.gen.manifest --out - -n test | kubectl apply -f - -n test

### Generating a resource

TODO: Need to support validation / OpenAPI.

## Terminology

*[Custom Resource](*: 

> A custom resource is an extension of the Kubernetes API that is not necessarily available on every Kubernetes cluster. In other words, it represents a customization of a particular Kubernetes installation.

*[CRD Custom Resource Definition](*: 

> The CustomResourceDefinition API resource allows you to define custom resources. Defining a CRD object creates a new custom resource with a name and schema that you specify. The Kubernetes API serves and handles the storage of your custom resource.


> A custom controller is a controller that users can deploy and update on a running cluster, independently of the cluster’s own lifecycle. Custom controllers can work with any kind of resource, but they are especially effective when combined with custom resources. The Operator pattern is one example of such a combination. It allows developers to encode domain knowledge for specific applications into an extension of the Kubernetes API.


A set of application specific controllers deployed on Kubernetes and managed via kubectl and the Kubernetes API.

## Docs

Documentation can be generated with [ExDoc](
and published on [HexDocs]( Once published, the docs can
be found at [](

## Testing

mix test

### Starting an interactive test session

This will load two modules in the operator, `Widget` and `Cog`.

**Create the CRDs:**

kubectl apply -f ./test/support/crd.yaml

vStart the session:**

BONNY_CONFIG_FILE=~/.kube/config MIX_ENV=test iex -S mix

The GenServers wait about 5 seconds to start watching.

**Trigger some events:**

kubectl apply -f ./test/support/widget.yaml

If log level is set to `debug` you will see the events being

## Reading

* [Why Kubernetes Operators are a game changer](