README

env GoDoc

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.

Expand ▾ Collapse ▴

Documentation

Overview

    Package env provides a standardised interface to environment variables, including parsing, validation and export checks.

    Index

    Constants

    This section is empty.

    Variables

    View Source
    var CmdName = func() string {
    	return path.Base(os.Args[0])
    }

      CmdName is used to create the default variable set name.

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

        func BindAddr(name, usage string) *string

          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

          func Bool(name string, usage string) *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

            func DialAddr(name, usage string) *string

              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

              func Duration(name string, usage string) *time.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

                func Int(name string, usage string) *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

                  func Int64(name string, usage string) *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 Parse

                    func Parse() error

                      Parse parses variables from the process environment.

                      func Path

                      func Path(name, usage string) *string

                        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

                        func String(name, usage string) *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

                          func StringRequired(name, usage string) *string

                            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 URL

                            func URL(name, usage string) *url.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.

                              func Visit

                              func Visit(fn func(*Var))

                                Visit visits the variables in the order in which they were defined, calling fn for each.

                                Types

                                type Errors

                                type Errors []error

                                  Errors is returned from Parse.

                                  func (Errors) Error

                                  func (me Errors) Error() string

                                    Error implements error.

                                    type Getter

                                    type Getter interface {
                                    	// Get retrieves an evironment variable.
                                    	Get(string) (string, bool)
                                    }

                                      Getter defines the Get method.

                                      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 Var

                                        type Var struct {
                                        	Name  string // name
                                        	Usage string // help message
                                        	Value Value  // value as set
                                        }

                                          Var represents the state of a variable.

                                          type VarSet

                                          type VarSet struct {
                                          	// contains filtered or unexported fields
                                          }

                                            VarSet contains a set of variables.

                                            func NewVarSet

                                            func NewVarSet(name string) *VarSet

                                              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

                                              func (v *VarSet) BindAddr(name, usage string) *string

                                                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

                                                func (v *VarSet) Bool(name string, usage string) *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

                                                  func (v *VarSet) DialAddr(name, usage string) *string

                                                    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

                                                    func (v *VarSet) Duration(name string, usage string) *time.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

                                                      func (v *VarSet) Int(name string, usage string) *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

                                                        func (v *VarSet) Int64(name string, usage string) *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) Name

                                                          func (v *VarSet) Name() string

                                                            Name is the name of the variable set.

                                                            func (*VarSet) Parse

                                                            func (v *VarSet) Parse(g Getter) error

                                                              Parse parses variables from the environment provided by the Getter.

                                                              func (*VarSet) Path

                                                              func (v *VarSet) Path(name, usage string) *string

                                                                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) Prefix

                                                                func (v *VarSet) Prefix() string

                                                                  Prefix applied to all variables when they are created.

                                                                  func (*VarSet) String

                                                                  func (v *VarSet) String(name string, usage string) *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

                                                                    func (v *VarSet) StringRequired(name string, usage string) *string

                                                                      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

                                                                      func (v *VarSet) URL(name, usage string) *url.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.

                                                                        func (*VarSet) Var

                                                                        func (v *VarSet) Var(value Value, name, usage string)

                                                                          Var defines a variable with the specified name and usage string.

                                                                          func (*VarSet) Visit

                                                                          func (v *VarSet) Visit(fn func(v *Var))

                                                                            Visit visits the variables in the order in which they were defined, calling fn for each.

                                                                            Source Files

                                                                            Directories

                                                                            Path Synopsis
                                                                            Package envsvc provides convenience methods for using env with services.
                                                                            Package envsvc provides convenience methods for using env with services.