* .---. ,---. ,---. .-. .-. ,--, ,---. * /.\ ( .-._)| .-.\ | .-.\ | | | |.' .') | .-' /.\ /..'\ (_) \ | |-' )| `-'/ | | | || |(_) | `-. /..'\ /'.'\ _ \ \ | |--' | ( | | | |\ \ | .-' /'.'\ /.''.'\ ( `-' ) | | | |\ \ | `-')| \ `-. | `--. /.''.'\ /.'.'.\ `----' /( |_| \)\`---(_) \____\/( __.' /.'.'.\ "'""""/'.''.'.\""'"'""""""(__)""""""""(__)"""""""""""""(__)""'""""/'.''.'.\""'"'" ^^^[_]^^^ ^^^[_]^^^
spruce is a general purpose YAML & JSON merging tool.
It is designed to be an intuitive utility for merging YAML/JSON templates together to generate complicated YAML/JSON config files in a repeatable fashion. It can be used to stitch together some generic/top level definitions for the config and pull in overrides for site-specific configurations to DRY your configs up as much as possible.
How do I get started?
spruce is available via Homebrew, just
brew tap starkandwayne/cf; brew install spruce
Alternatively, you can download a prebuilt binaries for 64-bit Linux, or Mac OS X
How do I compile from source?
- Install Go, e.g. on Ubuntu
sudo snap install --classic go
- Install dep
- Fetch sources via
go get github.com/geofffranks/spruce/...
- Change current directory to the source root
- Compile and execute tests
Is there a playground I can use before installing spruce?
Yes! play.spruce.cf is around for testing out data merging + transformation in a cleanroom environment. It has a number of spruce versions available to it, and can be used to reproduce/troubleshoot bugs that you're seeing in production. Once you've reproduced an issue, or solution to a problem, you can save it, and share with a colleague, or reference in a GitHub issue.
A Quick Example
# Let's build the first yaml file we will merge $ cat <<EOF first.yml some_data: this will be overwritten later a_random_map: key1: some data heres_an_array: - first element EOF # and now build the second yaml file to merge on top of it $ cat <<EOF second.yml some_data: 42 a_random_map: key2: adding more data heres_an_array: - (( prepend )) - zeroth element more_data: 84 # what happens when we spruce merge? $ spruce merge first.yml second.yml a_random_map: key1: some data key2: adding more data heres_an_array: - zeroth element - first element more_data: 84 some_data: 42
- What are all the spruce operators, and how do they work?
- What are the merge semantics of spruce?
- How can I manipulate arrays with spruce?
- Can I specify defaults for an operation, or use environment variables?
- Can I use spruce with go-patch files?
- Can I use spruce with CredHub?
- Can I use spruce with Vault?
- How can I generate spruce templates with spruce itself?
- How can I use spruce with BOSH's Cloud Config?
What else can Spruce do for you?
spruce doesn't just stop at merging datastructures together. It also has the following
spruce diff - Allows you to get a useful diff of two YAML files, to see where they differ
semantically. This is more than a simple diff tool, as it examines the functional differences,
rather than just textual (e.g. key-ordering differences would be ignored)
spruce json - Allows you to convert a YAML document into JSON, for consumption by something
that requires a JSON input.
spruce merge will handle both YAML + JSON documents, but produce
only YAML output.
spruce vaultinfo - Takes a list of files that would be merged together, and analyzes what paths
in Vault would be looked up. Useful for determining explicitly what access an automated process
might need to Vault to obtain the right credentials, and nothing more. Also useful if you need
to audit what credentials your configs are retrieving for a system..
Licensed under the MIT License