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 - use config client to pull remote config server data into local

1: Memory source - after process start, 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

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

after adding file

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

you can get value

ttl := archaius.GetString("ttl", "60s")
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

import a config client implementation

import _ "github.com/go-chassis/go-chassis-config/servicecomb"

set config client to init config center source

	ci := archaius.RemoteInfo{
	//input your remote source config
	}
	//create config client 
	cc,_:=ccclient.NewClient("servicecomb-kie",ccclient.Options{
    		ServerURI:"the address of config server endpoint",
    	})
	//manage local and remote key value at same time
	err = archaius.Init(
		archaius.WithRequiredFiles([]string{filename1}),
		archaius.WithOptionalFiles([]string{filename2}),
		archaius.WithRemoteSource(ci, cc),
	)

To check config server that archaius supports, access https://github.com/go-chassis/go-chassis-config

Example: Manage local configurations

Complete example

Example: Manage key value change events

Complete example

Documentation

Overview

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

Index

• 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(ci *RemoteInfo, cc config.Client) error
• func Exist(key string) bool
• func Get(key string) interface{}
• func GetBool(key string, defaultValue bool) bool
• func GetConfigs() map[string]interface{}
• func GetFloat64(key string, defaultValue float64) float64
• func GetInt(key string, defaultValue int) int
• func GetString(key string, defaultValue string) string
• func GetValue(key string) cast.Value
• func Init(opts ...Option) error
• func RegisterListener(listenerObj event.Listener, key ...string) error
• func Set(key string, value interface{}) error
• func UnRegisterListener(listenerObj event.Listener, key ...string) error
• func UnmarshalConfig(obj interface{}) error
• type FileOption
  • func WithFileHandler(h util.FileHandler) FileOption
• type FileOptions
• type Option
  • func WithCommandLineSource() Option
  • func WithDefaultFileHandler(handler util.FileHandler) Option
  • func WithENVSource() Option
  • func WithMemorySource() Option
  • func WithOptionalFiles(f []string) Option
  • func WithRemoteSource(ri *RemoteInfo, c config.Client) Option
  • func WithRequiredFiles(f []string) Option
• type Options
• type RemoteInfo

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(ci *RemoteInfo, cc config.Client) 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 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 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 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 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 UnmarshalConfig

func UnmarshalConfig(obj interface{}) error

UnmarshalConfig unmarshal the config of receiving object

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 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(ri *RemoteInfo, c config.Client) Option

WithRemoteSource accept the information for initiating a config center source, RemoteInfo is required if you want to use config center source client is optional,if client is nil, archaius will create one based on RemoteInfo config client will be injected into config source as a client to interact with a config server

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
	ConfigClient  config.Client
	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
	ClientType    string
	APIVersion    string
	RefreshPort   string
}

RemoteInfo has attribute for config center source initialization