config

README

Config

This package handles configuration for Thelma.

It supports configuration through:

• a configuration file, located at ~/.thelma/config.yaml
• environment variables (eg. THELMA_HOME)

It uses Koanf under the hood to provide these features.

Usage

Declare a config struct. Then, unmarshal configuration into it at runtime using config.Unmarshal.

You can optionally:

• Set default values for fields using the default struct tag (via defaults library)
• Add validation to config values using the validate struct tag (via validator library)

Example

// Declare a config struct with optional default and validation tags
type LogConfig struct {
	Logging struct {
		Console struct {
			Level string `default:"info" validate:"oneof=trace debug info warn error"`
		}
		File struct {
			Enabled   bool   `default:"true"`
			Level     string `default:"debug" validate:"oneof=trace debug info warn error"`
			KeepFiles int    `description:"Number of rotated log files to keep" default:"5" validate:"gte=0"`
			MaxSizeMb int    `description:"Max size of rotated log files in megabytes" default:"8" validate:"gte=0"`
		}
	}
}

// Then use UnmarshalKey to unmarshal all config values under a given
// prefix into the struct.
func setupLogging(cfg config.Config) {
    var logConfig LogConfig
    if err := cfg.UnmarshalKey("logging", &logConfig) {
       // handle error
    }
    // initialize logging based on LogConfig settings
    logging.Level = logConfig.Level
    // ...
}

Root Configuration Values

Most clients of config will bundle all configuration under a unique key (eg. logging); this config should be deserialized into a struct using UnmarshalKey(). However, a few core, system-wide configuration values exist at the root level.

These include:

• home: refers to the path where terra-helmfile is checked out

These config values are retrieved using methods on the Config object itself. (eg. cfg.Home())

Only truly global, cross-cutting values that have implications for many parts of Thelma should be added at the root level.

FAQ

Why Koanf and not Viper?

Viper has a really unfortunate long-running bug where environment variables are ignored when unmarshalling config into a struct.

Although there are some hacky workarounds for the bug, they only work for Unmarshal(), and not UnmarshalKey(), because the two functions, for some reason, have very different implementations.

Koanf is not exposed as part of this package's API, so it should be relatively simple to migrate back to Viper if/when this issue is fixed.

Documentation

Index

• Constants
• type Config
  • func Load(opts ...Option) (Config, error)
  • func NewTestConfig(settings map[string]interface{}) (Config, error)
• type Option
• type Options
  • func DefaultOptions() Options

Constants

const HomeKey = "home"

HomeKey configuration key used for thelma home (path to terra-helmfile clone)

Types

type Config

type Config interface {
	// Unmarshal will unmarshal all configuration data under the given prefix into the target struct.
	//
	// Unmarshal supports use of annotations from the Validator (https://github.com/go-playground/validator)
	// and Defaults (https://github.com/mcuadros/go-defaults) libraries in structs.
	Unmarshal(prefix string, into interface{}) error
	// Dump returns all config values as a map for debugging purposes
	Dump() map[string]interface{}
	// Home returns the fully-qualified path to the local terra-helmfile clone
	Home() string
}

Config is the configuration utility for Thelma. See README.md for usage examples.

func Load

func Load(opts ...Option) (Config, error)

Load Thelma configuration from file, environment, etc into a new Config

func NewTestConfig

func NewTestConfig(settings map[string]interface{}) (Config, error)

NewTestConfig is for use in unit tests. It creates a new config object, applying the given settings. By default it sets "home" to the OS temp dir, but this be overridden in the settings map. It DOES NOT include any configuration from the environment or config files (~/.thelma/config.yaml)

type Option

type Option func(Options) Options

Option can be used to customize default Options struct

type Options

type Options struct {
	// Overrides overrides to apply to the configuration (useful for testing)
	Overrides map[string]interface{}
	// ConfigFile which file to load configuration file from (default ~/.thelma/config.yaml)
	// Set to "" to skip loading configuration from a file.
	ConfigFile string
	// EnvPrefix which prefix to use when loading configuration from environment variables (default "THELMA")
	// Set to "" to skip loading configuration from environment variables.
	EnvPrefix string
}

Options configure the behavior of config.Load(). This interface is provided to support testing only and shouldn't be used during regular program execution.

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns default options for Config.Load()