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.

Profiles

Thelma is run by humans, on laptops, as well as in CI/CD pipelines. Often it needs to behave slightly differently each situation. (For example, credentials should not be cached on disk on CI servers).

Thelma configuration values should default to the manual, run-by-people case. However, it's possible to set configuration overrides for the CI/CD case in the ci configuration profile, located in ./profiles/ci.yaml.

Thelma will automatically apply the ci profile when it is run in a non-interactive shell.

But it's possible to explicitly select a configuration profile using the THELMA_CONFIG_PROFILE environment variable:

# Run thelma with the default (i.e. "human-mode") config profile
THELMA_CONFIG_PROFILE=default thelma <...>

# Run thelma with the ci profile
THELMA_CONFIG_PROFILE=ci thelma <...>

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(t *testing.T, settings ...map[string]interface{}) (Config, error)
• type Option
  • func WithOverride(key string, value interface{}) Option
  • func WithOverrides(overrides ...map[string]interface{}) Option
  • func WithTestDefaults(t *testing.T) Option
  • func WithThelmaRoot(thelmaRoot root.Root) 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(t *testing.T, settings ...map[string]interface{}) (Config, error)

NewTestConfig creates an empty config with optional settings, suitable for use unit tests. 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)

Option can be used to customize default Options struct

func WithOverride

func WithOverride(key string, value interface{}) Option

WithOverride merges a single override on top of any that have already been set

func WithOverrides

func WithOverrides(overrides ...map[string]interface{}) Option

WithOverrides merges overrides on top of any that have already been set

func WithTestDefaults

func WithTestDefaults(t *testing.T) Option

WithTestDefaults sets useful test defaults, including: * disabling config loading from config file and environment variables * pointing THELMA_HOME at a temporary directory

func WithThelmaRoot

func WithThelmaRoot(thelmaRoot root.Root) Option

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
	// Profile load a specific configuration profile instead of the one specified by THELMA_CONFIG_PROFILE
	Profile 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()