consulstructure

README

consulstructure

consulstructure is a Go library for decoding Consul data into a Go structure and keeping it in sync with Consul.

The primary use case for this library is to be able to build native Consul-based configuration into your Go applications without needing glue such as consul-template.

Installation

Standard go get:

$ go get github.com/mitchellh/consulstructure

Features

Below is a high-level feature list:

• Watch a key prefix in Consul KV to populate a Go structure.

• Notification on a channel when configuration is updated.

• Configuration structures support all Go primitive types, maps, and structs. Slices and arrays aren't supported since they don't mean anything in the data model of Consul KV.

• Nested and embedded structs in configuration structures work.

• Set quiescence periods to avoid a stampede of configuration updates when many keys are updated in a short period of time.

• Supports all connection features of Consul: multi-datacenter, encryption, and ACLs.

Usage & Example

For docs see the Godoc.

An example is shown below:

import (
    "fmt"

    "github.com/mitchellh/consulstructure"
)

// Create a configuration struct that'll be filled by Consul.
type Config struct {
    Addr     string
    DataPath string `consul:"data_path"`
}

// Create our decoder
updateCh := make(chan interface{})
errCh := make(chan error)
decoder := &consulstructure.Decoder{
    Target:   &Config{},
    Prefix:   "services/myservice",
    UpdateCh: updateCh,
    ErrCh:    errCh,
}

// Run the decoder and wait for changes
go decoder.Run()
for {
    select {
    case v := <-updateCh:
        fmt.Printf("Updated config: %#v\n", v.(*Config))
    case err := <-errCh:
        fmt.Printf("Error: %s\n", err)
    }
}

But Why Not a File?

A file is the most portable and technology agnostic way to get configuration into an application. I'm not advocating this instead of using files for the general case.

For organizations that have chosen Consul as their technology for configuration, services, etc. being able to build services that can be started without any further configuration and immediately start running is very attractive. You no longer have a configuration step where you have to setup services and file templates and so on with tools like consul-template.

You just install the Go binary, start it, and it is going. To update it, you just update the settings in Consul, and the application automatically updates. No more SIGHUP necessary, no more manual restarts.

Documentation

Index

• type Decoder
  • func (d *Decoder) Close() error
  • func (d *Decoder) Run()

Types

type Decoder

type Decoder struct {
	// Target is the target structure for configuration to be written to.
	// After supplying this configuration option, you should never write to
	// this value again. When configuration changes are detected, Decoder
	// will deep copy this structure before writing any changes and sending
	// them on UpdateCh.
	Target interface{}

	// Prefix is the key prefix in Consul where data will live. Decoder
	// will perform a blocking list query on this prefix and will also
	// request ALL DATA in this prefix. Be very careful that this prefix
	// contains only the configuration data for this application.
	//
	// A prefix of "" is not allowed, since that will request all data in
	// Consul and should never be used as the configuration root.
	//
	// If Prefix doesn't end in '/', then it will be appended. The Decoder
	// treats '/' as the path separator in Consul. This is used to find
	// nested values as well.
	Prefix string

	// UpdateCh is the channel where updates to the configuration are sent.
	// An initial value will be sent on the first read of data from Consul.
	//
	// The value sent on UpdateCh is initially a deep copy of Target so
	// there are no race issues around reading/writing values that come
	// on this channel.
	//
	// ErrCh is sent errors that the Decoder experiences. The Decoder
	// will otherwise ignore errors and continue running in an attempt to
	// stabilize, but you can choose to log or exit on errors if you'd
	// like. Temporary errors such as network issues aren't ever reported.
	UpdateCh chan<- interface{}
	ErrCh    chan<- error

	// QuiescencePeriod is the period of time to wait for Consul changes
	// to quiesce (achieve a stable, unchanging state) before triggering
	// an update.
	//
	// QuiescenceTimeout is the max time to wait for the QuiescencePeriod
	// to be reached before forcing an update anyways. For example, if
	// Period is set to 500ms and Timeout is set to 5s, then if data is
	// continously being updated for over 5s (causing the Period to never
	// be reached), the decoder will trigger an update anyways.
	//
	// If neither of these is set, they will default to 500ms and 5s,
	// respectively.
	QuiescencePeriod  time.Duration
	QuiescenceTimeout time.Duration

	// Consul is the configuration to use for initializing the Consul client.
	// If this is nil, then a default configuration will be used that
	// accesses Consul locally without any ACL token. For default values,
	// see consul.DefaultConfig.
	Consul *consul.Config
	// contains filtered or unexported fields
}

Decoder is the structure for decoding Consul data into a Go structure.

Please read the documentation carefully for each field. Fields that aren't set properly can result in broken behavior.

See Run for information on how to start the Decoder.

func (*Decoder) Close

func (d *Decoder) Close() error

Close stops any running Run method. If none are running, this does nothing. Otherwise, this will block until it stops. After Close is called, Run can be started again at any time.

This could really be named "Stop" but we have implemented it as Close so that it implements io.Closer.

func (*Decoder) Run

func (d *Decoder) Run()

Run starts the decoder. This should be started in a goroutine. If a runner is already running then this will return immediately.