Documentation
¶
Overview ¶
Package config handles the configuration of a program. The configuration contains the set of initial parameter settings that are read at runtime by the program.
This package allows plugging a fully-fledged configuration system into an application, taking care of the boilerplate code, common settings, configuration loading, and validation.
Different configuration sources can be used during development, debugging, testing, or deployment. The configuration can be loaded from a local file, environment variables, or a remote configuration provider (e.g., Consul, etcd, etcd3, Firestore, NATS).
This is a Viper-based implementation of the configuration model described in the following article:
- Nicola Asuni, 2014-09-13, "Software Configuration", https://technick.net/guides/software/software_configuration/
Configuration Loading Strategy: ¶
To achieve maximum flexibility, the different configuration entry points are coordinated in the following sequence (1 has the lowest priority and 5 has the highest):
In the "myprog" program, the configuration parameters are defined as a data structure that can be easily mapped to and from a JSON object (or any other format supported by Viper like TOML, YAML, and HCL). Each structure parameter is annotated with the "mapstructure" and "validate" tags to define the name mapping and the validation rules. The parameters are initialized with constant default values.
The program attempts to load the local "config.json" configuration file, and as soon as one is found, it overwrites the default values previously set.
The configuration file is searched in the following ordered directories based on the Linux Filesystem Hierarchy Standard (FHS):
- ./
- ~/.myprog/
- /etc/myprog/
The program attempts to load the environmental variables that define the remote configuration system. If found, it overwrites the corresponding configuration parameters:
- [ENVIRONMENT VARIABLE NAME] → [CONFIGURATION PARAMETER NAME]
- MYPROG_REMOTECONFIGPROVIDER → remoteConfigProvider
- MYPROG_REMOTECONFIGENDPOINT → remoteConfigEndpoint
- MYPROG_REMOTECONFIGPATH → remoteConfigPath
- MYPROG_REMOTECONFIGSECRETKEYRING → remoteConfigSecretKeyring
- MYPROG_REMOTECONFIGDATA → remoteConfigData
If the "remoteConfigProvider" parameter is not empty, the program attempts to load the configuration data from the specified source. This can be any remote source supported by the Viper library (e.g., Consul, etcd, etcd3, Firestore, NATS). The configuration source can also be the "MYPROG_REMOTECONFIGDATA" environment variable as base64-encoded JSON when "MYPROG_REMOTECONFIGPROVIDER" is set to "envvar".
Any specified command-line argument overwrites the corresponding configuration parameter.
The configuration parameters are validated via the Validate() function.
Example: ¶
An implementation example of this configuration package can be found in examples/service/internal/cli/config.go Note that the "log", "shutdown_timeout", and "remoteConfig" parameters are defined in this package as they are common to all programs.
The configuration file format of the example service is defined by examples/service/resources/etc/gosrvlibexample/config.schema.json
The default configuration file of the example service is defined by examples/service/resources/etc/gosrvlibexample/config.json
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Load ¶
func Load(cmdName, configDir, envPrefix string, cfg Configuration) error
Load populates the configuration parameters.
Types ¶
type BaseConfig ¶
type BaseConfig struct {
// Log configuration.
Log LogConfig `mapstructure:"log" validate:"required"`
// ShutdownTimeout is the time in seconds to wait for graceful shutdown.
ShutdownTimeout int64 `mapstructure:"shutdown_timeout" validate:"omitempty,min=1,max=3600"`
}
BaseConfig contains the default configuration options to be used in the application config struct.
type Configuration ¶
Configuration is the interface we need the application config struct to implement.
type LogConfig ¶
type LogConfig struct {
// Level is the standard syslog level: EMERGENCY, ALERT, CRITICAL, ERROR, WARNING, NOTICE, INFO, DEBUG.
Level string `mapstructure:"level" validate:"required,oneof=EMERGENCY ALERT CRITICAL ERROR WARNING NOTICE INFO DEBUG"`
// Format is the log output format: CONSOLE, JSON.
Format string `mapstructure:"format" validate:"required,oneof=CONSOLE JSON"`
// Network is the optional network protocol used to send logs via syslog: udp, tcp.
Network string `mapstructure:"network" validate:"omitempty,oneof=udp tcp"`
// Address is the optional remote syslog network address: (ip:port) or just (:port).
Address string `mapstructure:"address" validate:"omitempty,hostname_port"`
}
LogConfig contains the configuration for the application logger.
type Viper ¶
type Viper interface {
AddConfigPath(in string)
AddRemoteProvider(provider, endpoint, path string) error
AddSecureRemoteProvider(provider, endpoint, path, secretkeyring string) error
AllKeys() []string
AutomaticEnv()
BindEnv(input ...string) error
BindPFlag(key string, flag *pflag.Flag) error
Get(key string) any
ReadConfig(in io.Reader) error
ReadInConfig() error
ReadRemoteConfig() error
SetConfigName(in string)
SetConfigType(in string)
SetDefault(key string, value any)
SetEnvPrefix(in string)
Unmarshal(rawVal any, opts ...viper.DecoderConfigOption) error
}
Viper is the local interface to the actual viper to allow for mocking.
Source Files