📚 onion - Awesome Go Library for Configuration
Layer based configuration for Go, Supports JSON, TOML, YAML, properties, etcd, env, and encryption using PGP.
Detailed Description of onion
onion
import "github.com/goraz/onion"
Package onion is a layer based, pluggable config manager for golang.
The current version in develop
branch is work in progress (see the milestone), for older versions check the v2
and v3
branches and use the gopkg.in/goraz/onion.v1
and gopkg.in/goraz/onion.v2
For the next release we use the go module and tagging using semantic version.
Shrek: For your information, there's a lot more to ogres than people think.
Donkey: Example?
Shrek: Example... uh... ogres are like onions!
[holds up an onion, which Donkey sniffs]
Donkey: They stink?
Shrek: Yes... No!
Donkey: Oh, they make you cry?
Shrek: No!
Donkey: Oh, you leave 'em out in the sun, they get all brown, start sproutin' little white hairs...
Shrek: [peels an onion] NO! Layers. Onions have layers. Ogres have layers... You get it? We both have layers.
[walks off]
Donkey: Oh, you both have LAYERS. Oh. You know, not everybody like onions. CAKE! Everybody loves cake! Cakes have layers!
Shrek: I don't care what everyone likes! Ogres are not like cakes.
Donkey: You know what ELSE everybody likes? Parfaits! Have you ever met a person, you say, "Let's get some parfait," they say, "Hell no, I don't like no parfait."? Parfaits are delicious!
Shrek: NO! You dense, irritating, miniature beast of burden! Ogres are like onions! End of story! Bye-bye! See ya later.
Donkey: Parfait's gotta be the most delicious thing on the whole damn planet!
Goals
The main goal is to have minimal dependency based on usage. if you need normal config files in the file system,
there should be no dependency to etcd
or consul
, if you have only yaml
files, including toml
or any other format
is just not right.
Usage
Choose the layer first. normal file layer and json are built-in but for any other type you need to import the package for that layer.
Example json file layer
package main
import (
"fmt"
"github.com/goraz/onion"
)
func main() {
// Create a file layer to load data from json file. onion loads the file based on the extension.
// so the json file should have `.json` ext.
l1, err := onion.NewFileLayer("/etc/shared.json", nil)
if err != nil {
panic(err)
}
// Create a layer based on the environment. it loads every environment with APP_ prefix
// for example APP_TEST_STRING is available as o.Get("test.string")
l2 := onion.NewEnvLayerPrefix("_", "APP")
// Create the onion, the final result is union of l1 and l2 but l2 overwrite l1.
o := onion.New(l1, l2)
str := o.GetStringDefault("test.string", "empty")
fmt.Println(str)
// Now str is the string in this order
// 1- if the APP_TEST_STRING is available in the env
// 2- if the shared.json had key like this { "test" : { "string" : "value" }} then the str is "value"
// 3- the provided default, "empty"
}
Loading other file format
Currently onion
support json
format out-of-the-box, while you need to blank import the loader package of others formats to use them:
toml
(for 0.4.0 version)toml-0.5.0
(for 0.5.0 version)yaml
properties
For example:
import (
_ "github.com/goraz/onion/loaders/toml" // Needed to load TOML format
)
Watch file and etcd
Also there is other layers, (like etcd
and filewatchlayer
) that watches for change.
package main
import (
"fmt"
"github.com/goraz/onion"
"github.com/goraz/onion/layers/etcdlayer"
"github.com/goraz/onion/layers/filewatchlayer"
)
func main() {
// Create a file layer to load data from json file. also it watches for change in the file
l1, err := filewatchlayer.NewFileWatchLayer("/etc/shared.json", nil)
if err != nil {
panic(err)
}
l2, err := etcdlayer.NewEtcdLayer("/app/config", "json", []string{"http://127.0.0.1:2379"}, nil)
if err != nil {
panic(err)
}
// Create the onion, the final result is union of l1 and l2 but l2 overwrite l1.
o := onion.New(l1, l2)
// Get the latest version of the key
str := o.GetStringDefault("test.string", "empty")
fmt.Println(str)
}
Encrypted config
Also if you want to store data in encrypted content. currently only secconf
(based on the crypt project) is supported.
also the onioncli helps you to manage this keys.
package main
import (
"bytes"
"fmt"
"github.com/goraz/onion"
"github.com/goraz/onion/ciphers/secconf"
"github.com/goraz/onion/layers/etcdlayer"
"github.com/goraz/onion/layers/filewatchlayer"
)
// Normally this should be in a safe place, not here
const privateKey = `PRIVATE KEY`
func main() {
// The private key should be in the safe place. this is just a demo, also there is a cli tool
// to create this `go get -u github.com/goraz/onion/cli/onioncli`
cipher, err := secconf.NewCipher(bytes.NewReader([]byte(privateKey)))
if err != nil {
panic(err)
}
// Create a file layer to load data from json file. also it watches for change in the file
// passing the cipher to this make means the file in base64 and pgp encrypted
l1, err := filewatchlayer.NewFileWatchLayer("/etc/shared.json", cipher)
if err != nil {
panic(err)
}
// Create a etcd layer. it watches the /app/config key and it should be json file encoded with
// base64 and pgp
l2, err := etcdlayer.NewEtcdLayer("/app/config", "json", []string{"http://127.0.0.1:2379"}, cipher)
if err != nil {
panic(err)
}
// Create the onion, the final result is union of l1 and l2 but l2 overwrites l1.
o := onion.New(l1, l2)
// Get the latest version of the key
str := o.GetStringDefault("test.string", "empty")
fmt.Println(str)
}