config

README

go-config

Configuration file loading and reloading for orhecstrated Go applications.

Package go-config provide the necessary machinery to load, watch and reload configuration files for a Go application.

Unlike other packages with similar purpose, go-config does not attempt to mix configuration files with command line and environment variables handling. In the context of a Kubernetes cluster, confirugation files are handled by configMap object that are updated asynchronously from the application deployment, leading to the following guidelines:

• Command-line arguments and environment variables are attached to the application deployment definition and cannot be changed without restarting the application process. They should be used for configuration requiring the application to restart when changed. For stateless apllications that are cheap to restart, that should be almost all the configuration.

• Configuration files may be updated asynchronously from the application deployment and therefore MUST be watched and reloaded when they change.

go-config provides the necessary machinery to load and watch configuration files, and trigger updates notification. It supports YAML and JSON configuration file format, and loads their content into an application defined config struct. Reloading is asynchrnous and atomic.

Installation

go get github.com/marcus999/go-config

Usage

package main

import (
	"log"
	"time"

	config "github.com/marcus999/go-config"
)

// Config ...
type Config struct {
	Endpoint string `json:"endpoint"`
	Port     int    `json:"port"`
}

var defaultConfig = &Config{
	Endpoint: "default-endpoint",
	Port:     1234,
}

var loader *config.Loader

func main() {
	log.SetFlags(log.Lmicroseconds | log.Lshortfile | log.LUTC)

	loader, err := config.NewLoader("cmd/watcher/config.yaml", defaultConfig,
		config.OptStrictParsing(),
		config.ErrorHandler(func(err error) {
			log.Printf("config loader error, %v", err)
		}),
		config.ReloadHandler(func(cfg interface{}) {
			log.Printf("config reloaded, %#+v", cfg)
		}),
	)

	if err != nil {
		log.Fatalf("failed to initialize configuration loader, %v", err)
	}

	cfg := loader.Get().(*Config)

	// Use cfg as *Config
	_ = cfg

	for {
		time.Sleep(time.Second)
	}
}

Troubleshooting

Max number of file descriptors

Unit tests for the filesystem watching logic use the actual filesystem operations to verify that everything is working as expected. Since the go test command can run multiple tests in parallel, it is possible to run out of file descriptors very quickly, especially if the actual limit is low (the default is only 256 on macOS).

To check the current limit or change it, use

ulimit -n
ulimit -Sn 10240

Documentation

Index

• Constants
• type Loader
  • func NewLoader(filename string, defaultConfig interface{}, opts ...Option) (*Loader, error)
  • func (c *Loader) Get() interface{}
  • func (c *Loader) GetDefaults() interface{}
• type Option
  • func ErrorHandler(f func(err error)) Option
  • func OptDebounceInterval(v time.Duration) Option
  • func OptDebounceMaxDelay(v time.Duration) Option
  • func OptKeepLatestOnFailure() Option
  • func OptStrictParsing() Option
  • func ReloadHandler(f func(interface{})) Option
  • func ValidationHandler(f func(interface{}) (interface{}, error)) Option

Constants

const (
	// DefaultDebounceInterval defines the default debounce interval of 100ms
	DefaultDebounceInterval = 1000 * time.Millisecond

	// DefaultDebounceMaxDelay defines the default debounce max delay of 3s
	DefaultDebounceMaxDelay = 3 * time.Second
)

Types

type Loader

type Loader struct {
	// contains filtered or unexported fields
}

Loader loads and watches config

func NewLoader

func NewLoader(filename string, defaultConfig interface{}, opts ...Option) (*Loader, error)

NewLoader creates a new configuration loader from a filename and a set of defaults

func (*Loader) Get

func (c *Loader) Get() interface{}

Get returns the current version of the configuraiton stored in the loader

func (*Loader) GetDefaults

func (c *Loader) GetDefaults() interface{}

GetDefaults returns a copy of the default config

type Option

type Option func(*Loader)

Option is the base tupe for configuration options

func ErrorHandler

func ErrorHandler(f func(err error)) Option

ErrorHandler attaches a function to be called when an error occurs during a background opration, e.g. while reloading the configuration file

func OptDebounceInterval

func OptDebounceInterval(v time.Duration) Option

OptDebounceInterval set the debounce interval for rapid changes to the configuration file. Default interval is 100ms

func OptDebounceMaxDelay

func OptDebounceMaxDelay(v time.Duration) Option

OptDebounceMaxDelay set the maximum delay that can be caused by the debouncing process, in case the target configuration file is constantly cahning. The default value is 3s.

func OptKeepLatestOnFailure

func OptKeepLatestOnFailure() Option

OptKeepLatestOnFailure activate an option that will keep the latest valid configuration if the new configuration fails to load. The default behavior is to revert to the default settings. This option is not recommended for application running in a cluster orchestration environment.

func OptStrictParsing

func OptStrictParsing() Option

OptStrictParsing activate the strict option for the underlying parsing of the configuration file, i.e. fields that are unknown generate an error rather than being silently ignored

func ReloadHandler

func ReloadHandler(f func(interface{})) Option

ReloadHandler attaches a function to be called when the configuration is reloaded

func ValidationHandler

func ValidationHandler(f func(interface{}) (interface{}, error)) Option

ValidationHandler attaches a function to be called when a new configuration is loaded, but before it propagates through the system. The handler can modify or enhance the config object, and can abort the update by returning an error.