archaius

package module
v1.5.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 2, 2022 License: Apache-2.0 Imports: 15 Imported by: 64

README

go-archaius

Build Status Coverage Status HitCount goproxy.cn

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

View Source 
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"
)

Variables

This section is empty.

Functions

func AddDimensionInfo added in v0.21.0 

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 added in v0.15.0 

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 added in v0.13.0 

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 added in v0.21.0 

func Delete(key string) error

Delete delete the configuration key, value pairs in memory source

func EnableRemoteSource added in v0.21.0 

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 added in v1.5.0 

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 added in v1.3.0 

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 added in v0.21.0 

func GetValue(key string) cast.Value

GetValue return interface

func Init 

func Init(opts ...Option) error

Init create a Archaius config singleton

func InstallRemoteSource added in v1.1.0 

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 added in v1.3.0 

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

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

func Set added in v0.21.0 

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 added in v1.3.0 

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 added in v1.5.0 

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 added in v1.1.0 

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 added in v0.21.0 

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 added in v0.21.0 

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

Source Files

View all Source files

Directories

Path Synopsis
Package event provides the different Listeners
 Package event provides the different Listeners
examples
apollo
env
event
file
kie
module_event
pkg
cast
Package cast provides the typeCasting of an object
 Package cast provides the typeCasting of an object
configcenter
serializers
Package serializers created on 2017/6/22.
 Package serializers created on 2017/6/22.
serializers/json
Package json is used for marshalling and unmarshalling
 Package json is used for marshalling and unmarshalling
Package source manage all the config source and merge configs by precedence
 Package source manage all the config source and merge configs by precedence
apollo
cli
Package cli created on 2017/6/22.
 Package cli created on 2017/6/22.
configmap
env
Package env created on 2017/6/22.
 Package env created on 2017/6/22.
file
Package filesource created on 2017/6/22.
 Package filesource created on 2017/6/22.
mem
remote
remote/configcenter
remote/kie
util
util/queue

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.