kleat

README

kleat

Kleat is tool for managing Spinnaker configuration files that is intended to replace Halyard. Please see the RFC for an overview of what this tool will do.

It is currently under active development, but is ready for early adopters to try in development clusters! Please share any feedback in the #kleat channel in Spinnaker slack.

Please see spinnaker/kustomization-base for step-by-step instructions on how to install Spinnaker to a Kubernetes cluster using kleat and kustomize.

Migrating from Halyard

Please see the migration README for details on migrating from Halyard.

Installation

Download the appropriate binary from the releases page.

Usage

• kleat generate /path/to/halconfig /path/to/output/directory
• kleat help
• kleat version

Philosophy

The overarching design goal of kleat is that is should be as lightweight as possible, and should know as little as possible about implementation details of Spinnaker's microservices.

Problems should be solved at the right level of abstraction. For example:

• If a microservice does not set reasonable defaults, and requires a lot of config to be usable, this should be fixed by having the microservice set reasonable defaults rather than by having kleat hard-code defaults.
• If configuration errors do not lead to useful error messages, the microservice shoiuld be updated to provide useful error messages instead of relying on kleat to catch erroneous config.

This is in contrast to Halyard, which often had detailed knowledge of how the Spinnaker microservices worked (even to the point of importing a number of the microservices as libraries).

Much of the the effort in writing kleat involved:

• Updating the microservices to set sensible defaults, so that these did not need to be set in kleat
• Strongly typing and documenting the fields in the halconfig and the microservice configs

Defaulting

All configurable fields should have sensible defaults; users should be able to get a working installation of Spinnaker with as little config as possible.

The microservices are responsible for defaulting config properties to sensible values; kleat should not explicitly default any config properties. If a property has not been explicitly configured by the user, kleat should omit it from the generated output and let the relevant microservice handle defaulting.

While it might seem reasonable to have kleat set default values for a service's properties, the need to do this is generally a sign that the service should better default its properties.

Our experience with Halyard is that having a config management tool handle defaulting leads to the following issues:

• The config management tool needs to understand too much about the implementation details of the microservices it is deploying, breaking an important layer of abstraction.
• Users who deploy manually, without a config management tool, don't get the benefit of these defaults and still need to manually write a lot of config.
• The microservice is unable to distinguish values that have been explicitly set by the user from values that were defaulted by the config management tool. This makes it difficult to add or change defaults at the microservice level.
• The config generated by the tool becomes less readable, as it contains a lot of default values that are not of interest to the user, instead of only values that the user has explicitly configured.

One of the reasons that Halyard became difficult to maintain is that it tried to solve a lot of problems that were better solved at a different level of abstraction.

Transformation of values

The core competency of kleat is understanding what parts of the halconfig belong in each microservice's config. This is valuable, as:

• End users do not need to understand what each microservice does, and can just configure their halconfig and defer to kleat to generate microservice configs.
• Some config parameters (such as account credentials) are used by more than one microservice; kleat allows users to specify these parameters once and handles duplicating them in the required config files.

kleat should not transform input fields to the halconfig and should just pass these through unchanged to the appropriate places in the output configs.

If it seems necessary for kleat to transform a config value before passing it along to the microservice, please consider updating the relevant microservice to handle this transformation when loading its config. This will allow users manually writing their microservice configs to benefit from the change, and will keep the code handling this transformation in the relevant microservice rather than in the config management tool.