helmfile-operator

helmfile-operator is a Kubernetes operator that reconciles everything deployed to your cluster to the desired state described in your helmfile.

The benefit of Helmfile custom resource and helmfile-operator is that you can declaratively deploy K8s manifests generated with any tool from any source:

Supported tools:

Vanilla Kubernetes manifests(Regular Kuberntees YAMLs)
Helm
Kustomize
Helm + Kustomize(JIT kustomize patches before installinh Helm charts)

Supported sources:

Git
AWS S3
Potentially any sources supported by go-getter and helm downloader plugins

The "Helmfile" custom resource

Seeing is believing - here's the custom resource definition of Helmfile for you to get what it makes possible.

It will be a lot easier if you read it along with the official documentation for CustomResourceDefinition:

apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
  name: helmfile.apps.mumoshu.github.io
spec:
  group: apps.mumoshu.github.io
  versions:
  - name: v1alpha1
    served: true
    storage: true
  names:
    kind: Helmfile
    plural: helmfiles
    singular: helmfile
  scope: Namespaced
  validation:
    openAPIV3Schema:
      properties:
        spec:
          properties:
            source:
              type: string
            version:
              type: string
            image:
              type: object
              properties:
                repository:
                  type: string
                tag:
                  type: string
            values:
              type: object
            envvars:
              type: object

And an example custom resource:

apiVersion: apps.mumoshu.github.io/v1alpha1
kind: Helmfile
metadata:
  name: myapp
spec:
  source: git::https://github.com/mumoshu/helmfile-operator//pkg/examplecontroller@assets?ref=master
  #
  # # Syntax sugar: The trailing "?ref=master" can be specified alternatively with `version`:
  # version: master
  #
  # # Alternatively specify the container `image` for your own helmfile-applier.
  # # See the README section for `example-applier` to see how you can build your own helmfile-applier.
  # image:
  #   repository: quay.io/examplecom/example
  #   tag: v1.2.3
  #
  values:
    foo: FOO
  envvars:
    bar: BAR

Comparison to similar systems

Is helmfile-operator the only solution to the problem stated in the top of this page?

No - but I believe only helmfile-operator does it almost nearly perfect :)

Let's compare it with existing and similar systems, so that you can get why and in which circumstance helmfile-operator(or other system) is good fit:

addons-operators strives to be the collection of operators for cluster addons while providing the solid framework for building those operators.

helmfile-operator, on the other hand, is for managing helmfile. An helmfile is not necessarily a cluster addon so it was natural for the author of this project(me) to build it outside the cluster-operators project.

An cluster-addon operator is free to use helmfile-operator and delegate the management of a complex of bundle of K8s maniefsts(=an helmfile) to helmfile-operator.

The interface between the addon operator and the helmfile-operator will be Appliance custom resources. The addon operator should CRUD Helmfile resources via K8s API accordingly to the Addon and Channel resources. So that each addon-operator can be maintained easily without dealing with various K8s deployment tools.

Terminology

appliance is a virtual appliance a.k.a a self-managed service that is installed onto your k8s cluster. An appliance is composed of one or more K8s resources.

consumer is the user of the appliance. A helmfile surface a single U/X to manage the appliance as a whole, so that consumer is able to operate on the helmfile, rather than on underlying K8s resources.

applier periodically reconcile the k8s cluster so that the appliance keeps running. This project aims to provide (1) generic applier and (2) the framework for building your own applier and helmfile-operator.

helmfile-applier is the only applier that is maintained in this project. example-applier is an example applier that shows how to build your own applier based on helmfile-applier.

helmfile-operator watches for Helmfile custom resources so that it can reconcile the k8s cluster to have corresponding helmfile-controller up and running.

Projects

There are 1 main project and 2 related projects maintained within this project.

See respective directory under the pkg directory for more details.

`helmfile-operator`

This is the implementation of helmfile-operator.

It is based on the helmfile-operator's controller-runtime, and has the additional ability to automatically register the Helmfile CRD on startup.

It's configuration can be customized via the changing the bundled assets/config.yaml, or mouting an alternative config file and pointing the operator to load that by providing the --file CONFIG_FILE flag.

For settings available in config.yaml, see the documentation of whitebox-controller which is the foundation of the operator.

`controller-runtime`

This is a generic implementation of the helmfile-operator which is deployed onto a runtime environment that has connectivity to K8s API.

By contacting K8s API, it watches Helmfile custom resources for changes and updates and removes the Deployment that runs the helmfile-applier.

See [The "Helmfile" custom resource](#The "Helmfile" custom resource) for details of the Appliance resource.

helmfile-applier

helmfile-applier is a generic applier that is deployed as a container within your cluster to periodically runs helmfile to reconcile the cluster state.

example-applier

Use-cases: Air-gapped deployments (By containerizing all the helmfile assets)

This is an example applier that is implemented by extending helmfile-applier.

It bundles the helmfile and all the files referenced from it into the executable binary with packr2.

On runtime, it calls summon to extract the state file and its belongings, periodically run helmfile commands to reconcile the cluster state so that your apps in the desired state is kept up and running.

Advanced: Building your own helmfile-operator based on controller-runtime

TL;DR; Use helmfile-operator's controller-runtime as a framework and helmfile-operator as the reference implementation for building your own operator.

For advanced-usecases

Consider this as a framework for building your own helmfile-operator-like operator from scrach.

Related projects

Under the hood, helmfile-operator uses:

helmfile for declaratively manage and deploy apps onto your cluster.
helm-x for transparent support for any K8s manifests renderer/builder.
kustomize for JIT patching your K8s manifests or helm charts contained in the helmfile.
helm for installing, upgrading your app
helm-diff for reviewing changes before actually updating the cluster state.
whitebox-controller as the framework for building the rock-solid helmfile-operator that is customizable via config files and shell scripts.