archaius

README

go-archaius

This is a light weight configuration management framework which helps to manage configurations in distributed system

The main objective of go archaius is to pull and sync the configuration from multiple sources

Why use go-archaius

it is hard to manage configurations in a distributed system. archaius is able to put all configuration in distributed system together and manage them. To make it simple to get the exact config you want in distributed system. It also keeps watching configuration changes, and fire change event if value changes. so that you can easily implement a service which has hot-reconfiguration features. when you need to change configurations, your service has zero-down time.

Conceptions

Sources

Go-archaius can manage multiple sources at the same time. Each source can holds same or different key value pairs. go-archaius keeps all the sources marked with their precedence, and merge key value based on precedence. in case if two sources have same key then key with higher precedence will be selected, and you can use archaius API to get its value

Here is the precedence list:

0: remote source - pull remote config server data into local

1: Memory source - after init, you can set key value in runtime.

2: Command Line source - read the command lines arguments, while starting the process.

3: Environment Variable source - read configuration in Environment variable.

4: Files source - read files content and convert it into key values based on the FileHandler you define

Dimension

It only works if you enable remote source, as remote server, it could has a lot of same key but value is different. so we use dimension to identify kv. you can also get kv in other dimension by add new dimension

Event management

You can register event listener by key(exactly match or pattern match) to watch value change.

File Handler

It works in File source, it decide how to convert your file to key value pairs. check FileHandler, currently we have 2 file handler implementation

archaius API

developer usually only use API to interact with archaius, check API.

To init archaius

archaius.Init()

when you init archaius you can decide what kind of source should be enable, required file slice was given, archaius checks file existing and add them into file source, if not exist, init fails, below example also enables env and mem sources.

	err := archaius.Init(
		archaius.WithRequiredFiles([]string{filename1}),
		archaius.WithOptionalFiles([]string{filename2}),
		archaius.WithENVSource(),
		archaius.WithMemorySource())

Put value into archaius

Notice, key value will be only put into memory source, it could be overwritten by remote config as the precedence list

archaius.Set("interval", 30)
archaius.Set("ttl", "30s")
archaius.Set("enable", false)

Read config files

if you have a yaml config

some:
  config: 1
ttl: 30s
service:
  name: ${NAME||go-archaius}
  addr: ${IP||127.0.0.1}:${PORT||80} 

after adding file

archaius.AddFile("/etc/component/xxx.yaml")

you can get value

ttl := archaius.GetString("ttl", "60s")
i := archaius.GetInt("some.config", "")
serviceName := archaius.GetString("service.name", "")
serviceAddr := archaius.GetString("service.addr", "")

note:

1. For service.name config with value of ${NAME||go-archaius} is support env syntax. If environment variable ${NAME} isn't setting, return default value go-archaius. It's setted, will get real environment variable value. Besides, if ${Name^^} is used instead of ${Name}, the value of environment variable Name will be shown in upper case, and ${Name,,} will bring the value in lower case.
2. For service.addr config is support "expand syntax". If environment variable ${IP} or ${PORT} is setted, will get env config. eg: export IP=0.0.0.0 PORT=443 , archaius.GetString("service.addr", "") will return 0.0.0.0:443 .

if you want to read some.config from env you can run

export some_config=xxxx

then you can read it by below code

i := archaius.GetInt("some.config", "")

by default archaius only support yaml files, but you can extend file handler to handle file in other format, for example we only consider file name as a key, content is the value.

archaius.AddFile("xxx.txt", archaius.WithFileHandler(util.FileHandler(util.UseFileNameAsKeyContentAsValue))

you can get value

v := archaius.GetString("/etc/component/xxx.txt", "")

Enable remote source

If you want to use one remote source, you must import the corresponding package of the source in your code.

import _ "github.com/go-chassis/go-archaius/source/remote/kie"

set remote info to init remote source

	ri := &archaius.RemoteInfo{
	//input your remote source config
	}
	//manage local and remote key value at same time
	err := archaius.Init(
		archaius.WithRequiredFiles([]string{filename1}),
		archaius.WithOptionalFiles([]string{filename2}),
		archaius.WithRemoteSource(archaius.KieSource, ri),
	)

Supported distributed configuration management service:

name	import	description
kie	github.com/go-chassis/go-archaius/source/remote/kie	ServiceComb-Kie is a config server which manage configurations in a distributed system. It is also a micro service in ServiceComb ecosystem and developed by go-chassis we call it ServiceComb Native application. https://kie.readthedocs.io
config-center	github.com/go-chassis/go-archaius/source/remote/configcenter	huawei cloud CSE config center https://www.huaweicloud.com/product/cse.html
apollo	github.com/go-chassis/go-archaius/source/apollo	A reliable configuration management system https://github.com/ctripcorp/apollo

Example: Manage local configurations

Complete example

Example: Manage key value change events

Complete example

Example: Manage remote source configurations

Complete example

Example: Manage module change events

Sometimes, we may want to handle multiple key value changes as a module, which means that the different key in the module has some relation with each other. Once such keys have changed, we expect to handle the changes as a whole instead of one by one. Module events help us to handle this case.

Complete example

Documentation

Overview

Package archaius provides you APIs which helps to manage files, remote config center configurations

Index

• Constants
• func AddDimensionInfo(labels map[string]string) (map[string]string, error)
• func AddFile(file string, opts ...FileOption) error
• func AddSource(source source.ConfigSource) error
• func Clean() error
• func CustomInit(sources ...source.ConfigSource) error
• func Delete(key string) error
• func EnableRemoteSource(remoteSource string, ci *RemoteInfo) error
• func Exist(key string) bool
• func Get(key string) interface{}
• func GetBool(key string, defaultValue bool) bool
• func GetConfigs() map[string]interface{}
• func GetConfigsWithSourceNames() map[string]interface{}
• func GetFloat64(key string, defaultValue float64) float64
• func GetInt(key string, defaultValue int) int
• func GetInt64(key string, defaultValue int64) int64
• func GetString(key string, defaultValue string) string
• func GetValue(key string) cast.Value
• func Init(opts ...Option) error
• func InstallRemoteSource(source string, remoteSource NewRemoteSource)
• func RegisterListener(listenerObj event.Listener, key ...string) error
• func RegisterModuleListener(listenerObj event.ModuleListener, prefix ...string) error
• func Set(key string, value interface{}) error
• func UnRegisterListener(listenerObj event.Listener, key ...string) error
• func UnRegisterModuleListener(listenerObj event.ModuleListener, prefix ...string) error
• func UnmarshalConfig(obj interface{}) error
• func WriteTo(w io.Writer) error
• type FileOption
  • func WithFileHandler(h util.FileHandler) FileOption
• type FileOptions
• type NewRemoteSource
• type Option
  • func WithCommandLineSource() Option
  • func WithDefaultFileHandler(handler util.FileHandler) Option
  • func WithENVSource() Option
  • func WithMemorySource() Option
  • func WithOptionalFiles(f []string) Option
  • func WithRemoteSource(provider string, ri *RemoteInfo) Option
  • func WithRequiredFiles(f []string) Option
• type Options
• type RemoteInfo

Constants

const (
	// ApolloSource is for apollo source
	ApolloSource = "apollo"
	// ConfigCenterSource is for config center source
	ConfigCenterSource = "config-center"
	// KieSource is for ServiceComb-Kie source
	KieSource = "kie"
)

Functions

func AddDimensionInfo

func AddDimensionInfo(labels map[string]string) (map[string]string, error)

AddDimensionInfo adds a NewDimensionInfo of which configurations needs to be taken

func AddFile

func AddFile(file string, opts ...FileOption) error

AddFile is for to add the configuration files at runtime

func AddSource

func AddSource(source source.ConfigSource) error

AddSource add source implementation

func Clean

func Clean() error

Clean will call config manager CleanUp Method, it deletes all sources which means all of key value is deleted. after you call Clean, you can init archaius again

func CustomInit

func CustomInit(sources ...source.ConfigSource) error

CustomInit accept a list of config source, add it into archaius runtime. it almost like Init(), but you can fully control config sources you inject to archaius

func Delete

func Delete(key string) error

Delete delete the configuration key, value pairs in memory source

func EnableRemoteSource

func EnableRemoteSource(remoteSource string, ci *RemoteInfo) error

EnableRemoteSource create a remote source singleton A config center source pull remote config server key values into local memory so that you can use GetXXX to get value easily

func Exist

func Exist(key string) bool

Exist check the configuration key existence

func Get

func Get(key string) interface{}

Get is for to get the value of configuration key

func GetBool

func GetBool(key string, defaultValue bool) bool

GetBool is gives the key value in the form of bool

func GetConfigs

func GetConfigs() map[string]interface{}

GetConfigs gives the information about all configurations

func GetConfigsWithSourceNames

func GetConfigsWithSourceNames() map[string]interface{}

GetConfigsWithSourceNames gives the information about all configurations each config key, along with its source will be returned the returned map will be like:

map[string]interface{}{
		key string: map[string]interface{"value": value, "sourceName": sourceName}
}

func GetFloat64

func GetFloat64(key string, defaultValue float64) float64

GetFloat64 gives the key value in the form of float64

func GetInt

func GetInt(key string, defaultValue int) int

GetInt gives the key value in the form of GetInt

func GetInt64

func GetInt64(key string, defaultValue int64) int64

GetInt64 gives the key value in the form of int64

func GetString

func GetString(key string, defaultValue string) string

GetString gives the key value in the form of GetString

func GetValue

func GetValue(key string) cast.Value

GetValue return interface

func Init

func Init(opts ...Option) error

Init create a Archaius config singleton

func InstallRemoteSource

func InstallRemoteSource(source string, remoteSource NewRemoteSource)

InstallRemoteSource allow user customize remote source

func RegisterListener

func RegisterListener(listenerObj event.Listener, key ...string) error

RegisterListener to Register all listener for different key changes, each key could be a regular expression

func RegisterModuleListener

func RegisterModuleListener(listenerObj event.ModuleListener, prefix ...string) error

RegisterModuleListener to Register all moduleListener for different key(prefix) changes

func Set

func Set(key string, value interface{}) error

Set add the configuration key, value pairs into memory source at runtime it is just affect the local configs

func UnRegisterListener

func UnRegisterListener(listenerObj event.Listener, key ...string) error

UnRegisterListener is to remove the listener

func UnRegisterModuleListener

func UnRegisterModuleListener(listenerObj event.ModuleListener, prefix ...string) error

UnRegisterModuleListener is to remove the moduleListener

func UnmarshalConfig

func UnmarshalConfig(obj interface{}) error

UnmarshalConfig unmarshal the config of receiving object

func WriteTo

func WriteTo(w io.Writer) error

WriteTo write the config to writer by yaml

Types

type FileOption

type FileOption func(options *FileOptions)

FileOption is a func

func WithFileHandler

func WithFileHandler(h util.FileHandler) FileOption

WithFileHandler use custom handler

type FileOptions

type FileOptions struct {
	Handler util.FileHandler
}

FileOptions for AddFile func

type NewRemoteSource

type NewRemoteSource func(info *RemoteInfo) (source.ConfigSource, error)

NewRemoteSource create a new remote source

type Option

type Option func(options *Options)

Option is a func

func WithCommandLineSource

func WithCommandLineSource() Option

WithCommandLineSource enable cmd line source archaius will read command line params as key value

func WithDefaultFileHandler

func WithDefaultFileHandler(handler util.FileHandler) Option

WithDefaultFileHandler let user custom handler you can decide how to convert file into kv pairs

func WithENVSource

func WithENVSource() Option

WithENVSource enable env source archaius will read ENV as key value

func WithMemorySource

func WithMemorySource() Option

WithMemorySource accept the information for initiating a Memory source

func WithOptionalFiles

func WithOptionalFiles(f []string) Option

WithOptionalFiles tell archaius to manage files, if not exist will NOT return error

func WithRemoteSource

func WithRemoteSource(provider string, ri *RemoteInfo) Option

WithRemoteSource accept the information for initiating a remote source

func WithRequiredFiles

func WithRequiredFiles(f []string) Option

WithRequiredFiles tell archaius to manage files, if not exist will return error

type Options

type Options struct {
	RequiredFiles []string
	OptionalFiles []string
	FileHandler   util.FileHandler
	RemoteInfo    *RemoteInfo
	RemoteSource  string
	UseCLISource  bool
	UseENVSource  bool
	UseMemSource  bool
}

Options hold options

type RemoteInfo

type RemoteInfo struct {
	//required.
	//Key value can be in different namespace, we call it dimension.
	//although key is same but in different dimension, the value is different.
	//you must specify the service,app and version, so that the remote source will pull key value
	DefaultDimension map[string]string
	//archaius config center source support 2 types of refresh mechanism:
	//0: Web-Socket Based -  client makes an web socket connection with
	//the config server and keeps getting an events whenever any data changes.
	//1: Pull Configuration interval- In this type client keeps polling the configuration from
	//the config server at regular intervals.
	RefreshMode int

	//Pull Configuration interval, unit is second
	RefreshInterval int

	//currentConfig for config client implementation
	//if you already create a client, don't need to set those config
	URL           string
	TenantName    string
	EnableSSL     bool
	TLSConfig     *tls.Config
	AutoDiscovery bool
	APIVersion    string
	RefreshPort   string
	ProjectID     string
}

RemoteInfo has attribute for config center source initialization