README
env 
Environment variable management
Package Goals:
- Up-front check for existance and validity of all required config variables
- Can output all variables used by a process on startup
- Can export and import full env configurations
- Seamlessly transition local testing environments to Kubernetes
Inspired by the simplicity and power of the standard library flag
package, env
works by first defining a set of variables in your program which will take the value of ENV variables.
This is extended with the envsvc
package which is explicitly designed for use in service processes.
Example below:
package main
import (
"fmt"
"net/http"
"github.com/sajari/env"
"github.com/sajari/env/envsvc"
)
func main() {
// Define variables...
listen := env.BindAddr("LISTEN", "bind address for gRPC server")
debug := env.BindAddr("LISTEN_DEBUG", "bind address for http debug server")
apiKey := env.String("API_KEY", "key id for api authorisation")
workers := env.Int("WORKERS", "number of parallel workers to start")
// Parse them from the environment and exit if all env vars are not set
envsvc.Parse()
// Debug server (optional)
http.ListenAndServe(*debug, nil)
// Your code begins here!
}
By default String
, Int
, Bool
, Duration
are defined. We also have flag types BindAddr
and DialAddr
typically included in all of our services for exposing ports on server processes and dialing to other servers.
Extending this pattern
It’s also possible to define new variable types by implementing the Value interface (which is the same as in flag
). You can also define separate sets of variables, rather than using the global functions in the env
package.
Config export, generation and more
Inheriting a project and getting configured is simple. The above code example will exit if the env vars are not set. From an engineer perspective this is great, you immediately see why the service won't start and what you need to fix to get running.
The built-in --help
flag tells you your options:
$ ./my-service --help
Usage of ./my-service:
-env-check
check env variables
-env-dump
dump env variables
-env-dump-json
dump env variables in JSON format
-env-dump-yaml
dump env variables in YAML format
So we can check
which env vars are required:
$ ./my-service -env-check
missing env MY_SERVICE_LISTEN
missing env MY_SERVICE_LISTEN_DEBUG
missing env MY_SERVICE_API_KEY
missing env MY_SERVICE_WORKERS
Note: the env vars are prefixed with the service name to avoid clashes.
Ok that's useful, now we know what we need to get this service up and running. I'm lazy, so i want this done for me:
$ ./my-service -env-dump
# bind address for gRPC server
export MY_SERVICE_LISTEN=""
# bind address for http debug server
export MY_SERVICE_LISTEN_DEBUG=""
# key id for api authorisation
export MY_SERVICE_API_KEY=""
# number of parallel workers to start
export MY_SERVICE_WORKERS=""
Excellent, now I have a workable set of environment parameters ready to be exported, note that they are currently blank. At this point the engineer has some options:
- Create workable values (particularly if the owner)
- Look for example values in the service repo (good practice)
- Ask the service owner
So after making these up and adding them to my environment i can re-run the dump
commmand to get the following:
$ ./my-service -env-dump
export MY_SERVICE_LISTEN=":1234" # bind address for gRPC server
export MY_SERVICE_LISTEN_DEBUG=":5678" # bind address for http debug server
export MY_SERVICE_API_KEY="abc" # key id for api authorisation
export MY_SERVICE_WORKERS="4" # number of parallel workers to start
We now have a fully working environment that will be validated on service start and can be exported and shared with other engineers as needed.
Documentation
Overview ¶
Package env provides a standardised interface to environment variables, including parsing, validation and export checks.
Index ¶
- Variables
- func BindAddr(name, usage string) *string
- func Bool(name string, usage string) *bool
- func DialAddr(name, usage string) *string
- func Duration(name string, usage string) *time.Duration
- func Int(name string, usage string) *int
- func Int64(name string, usage string) *int64
- func Parse() error
- func Path(name, usage string) *string
- func String(name, usage string) *string
- func StringRequired(name, usage string) *string
- func URL(name, usage string) *url.URL
- func Visit(fn func(*Var))
- type Errors
- type Getter
- type Value
- type Var
- type VarSet
- func (v *VarSet) BindAddr(name, usage string) *string
- func (v *VarSet) Bool(name string, usage string) *bool
- func (v *VarSet) DialAddr(name, usage string) *string
- func (v *VarSet) Duration(name string, usage string) *time.Duration
- func (v *VarSet) Int(name string, usage string) *int
- func (v *VarSet) Int64(name string, usage string) *int64
- func (v *VarSet) Name() string
- func (v *VarSet) Parse(g Getter) error
- func (v *VarSet) Path(name, usage string) *string
- func (v *VarSet) Prefix() string
- func (v *VarSet) String(name string, usage string) *string
- func (v *VarSet) StringRequired(name string, usage string) *string
- func (v *VarSet) URL(name, usage string) *url.URL
- func (v *VarSet) Var(value Value, name, usage string)
- func (v *VarSet) Visit(fn func(v *Var))
Constants ¶
Variables ¶
CmdName is used to create the default variable set name.
var CmdVar = NewVarSet(CmdName())
CmdVar is the default variable set used for command-line based applications. The name of the variable set (and hence all variable prefixes) is given by CmdName.
Functions ¶
func BindAddr ¶
BindAddr defines a string variable with specified name, usage string validated as a bind address (host:port). The return value is the address of a string variable that stores the value of the variable.
func Bool ¶
Bool defines a bool variable with specified name and usage string. The return value is the address of a bool variable that stores the value of the variable.
func DialAddr ¶
DialAddr defines a string variable with specified name, usage string validated as a dial address (host:port). The return value is the address of a string variable that stores the value of the variable.
func Duration ¶
Duration defines a time.Duration variable with specified name, usage string and validation checks. The return value is the address of a time.Duration variable that stores the value of the variable.
func Int ¶
Int defines an int variable with specified name and usage string. The return value is the address of an int variable that stores the value of the variable.
func Int64 ¶
Int64 defines an int64 variable with specified name and usage string. The return value is the address of an int variable that stores the value of the variable.
func Path ¶
Path defines a string variable with specified name, usage string validated as a local path. The return value is the address of a string variable that stores the value of the variable.
func String ¶
String defines a string variable with specified name, usage string and validation checks. The return value is the address of a string variable that stores the value of the variable.
func StringRequired ¶
StringRequired defines a required string variable with specified name and usage string.. The return value is the address of a string variable that stores the value of the variable.
Types ¶
type Value ¶
type Value interface { // String is a string representation of the stored value. String() string // Set assigns a new value to a stored value from a string // representation. Set(string) error }
Value is the interface to the dynamic value stored in Var.
type VarSet ¶
type VarSet struct {
// contains filtered or unexported fields
}
VarSet contains a set of variables.
func NewVarSet ¶
NewVarSet creates a new variable set with given name.
If name is non-empty, then all variables will have a strings.ToUpper(name)+"_" prefix.
func (*VarSet) BindAddr ¶
BindAddr defines a string variable with specified name, usage string validated as a bind address (host:port). The return value is the address of a string variable that stores the value of the variable.
func (*VarSet) Bool ¶
Bool defines a bool variable with specified name, usage string and validation checks. The return value is the address of a bool variable that stores the value of the variable.
func (*VarSet) DialAddr ¶
DialAddr defines a string variable with specified name, usage string validated as a dial address (host:port). The return value is the address of a string variable that stores the value of the variable.
func (*VarSet) Duration ¶
Duration defines a time.Duration variable with specified name, usage string and validation checks. The return value is the address of a time.Duration variable that stores the value of the variable.
func (*VarSet) Int ¶
Int defines an int variable with specified name, usage string and validation checks. The return value is the address of an int variable that stores the value of the variable.
func (*VarSet) Int64 ¶
Int64 defines an int64 variable with specified name, usage string and validation checks. The return value is the address of an int variable that stores the value of the variable.
func (*VarSet) Path ¶
Path defines a string variable with specified name, usage string validated as a local path. The return value is the address of a string variable that stores the value of the variable.
func (*VarSet) String ¶
String defines a string variable with specified name, usage string and validation checks. The return value is the address of a string variable that stores the value of the variable.
func (*VarSet) StringRequired ¶
StringRequired defines a required string variable with specified name and usage string. The return value is the address of a string variable that stores the value of the variable.
func (*VarSet) URL ¶
URL defines a string variable with specified name, usage string validated as a URL. The return value is the address of a URL variable that stores the value of the variable.
Directories
Path | Synopsis |
---|---|
Package envsvc provides convenience methods for using env with services.
|
Package envsvc provides convenience methods for using env with services. |