cmdb 2.6.2 → 3.0.0rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fb66b46a8e975e3b5e821b1aa88193fc74a38399
-  data.tar.gz: 149ccf828db01f724a9da9a099ad7882a796bca4
+  metadata.gz: 3e6aea8a8e330452b914eae78b2909200d62aca4
+  data.tar.gz: ffcb1a5762568246b37e3924c793f29d36b7e3ab
 SHA512:
-  metadata.gz: 5ef9c3db1fbdeee01b0cfd1d679781dfb065e5f3158663478d84543c9247103c72d0886a4e8e7ace3b2c1cdcd2e7e4c6a982799e43ca1b8fdcd9a58c51943d89
-  data.tar.gz: 8851d93f078616c05ff7a9c445315573c7b0efcc40f41818383a138e18f47c1cd2b9afad11c6e6faca66b670191aedb6ba0eb432e11894133c3c3b46383dd33a
+  metadata.gz: f20fe6ab9ff05e6f3450117f21abbc91b215bdedb55cfee11b6ad8bfba2937826536862f8d7593a3ec60d845424288d6aab3340691bf58957d586dab37d0c4ca
+  data.tar.gz: 59dd521b9730b77d8acea1ba8587a04bc6cb172f67e79cfbfe2eda09825bc3107fd7bc799824f7a823ae00295f3509418523066cf3cc6d55694d727aadff30a8

data/.dockerignore

@@ -0,0 +1,7 @@
+Dockerfile
+features
+fixtures
+spec
+*.md
+!.git
+.*

data/.gitignore

@@ -13,6 +13,9 @@ doc
 .bundle
 pkg
 
+# pry
+.byebug_history
+
 # Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore:
 #
 # * Create a file at ~/.gitignore

data/CHANGELOG.md

@@ -1,46 +1,83 @@
-### 2.6.0 (2016-03-01)
+### 3.0.0rc1
 
-Two new command line options are added to the shim
-`--consul-url` = The URL of the consul agent. Example: http://consul:8500
-`--consul-prefix` = The prefix to use when getting keys from consul. Example: shard403
+With this major version we introduce significant compatibility-breaking changes!
+Functions and options have been removed and we have rethought how sources are
+specified.
 
-There are two ways of using the shim.
+#### New: Interactive shell
 
-1. Using to replace keys in legacy ruby apps:
----------------------------------------------
+A `shell` subcommand allows you to navigate the CMDB as if it were a
+filesystem with `ls`, `cd` and other commands.
 
-When using the shim to replace keys in configuration files, it is sufficient to specify
-the shard identifier (shard403, shard93, etc) as the prefix. Also prefix is optional so
-in dev environments if you don't have these shard identifier as prefixes, you don't have
-to specify it. When replacing keys in configuration files, the requested keys are loaded
-from consul on demand.
+#### New: Read/write sources
 
-Example:
-```
-bundle exec cmdb shim --consul-url=http://consul:8500 --consul-prefix=shard403 \
-  --dir=config -- rainbows -c config/rainbows.rb
-```
+Non-file sources allow keys to be written as well as read. You can set the values
+of keys from the shell, or programatically by calling the `#set` method of the
+source.
 
-2. Using to populate environment in modern apps:
-------------------------------------------------
+#### Removed: Environment sources
 
-The --consul-prefix command line option can be specifed multiple times just like the
-envconsul tool allows and all keys under the specified prefix are loaded in the
-environment and the prefix itself is skipped.
+We no longer treat the process environment as a _source_ for CMDB data, but
+rather a destination; the use cases for treating it as a source were spurious
+and mostly concerned with testing of this gem.
 
-Example:
-```
-bundle exec cmdb shim --consul-url=http://consul:8500 --consul-prefix=shard403/common \
-  --consul-prefix=shard403/cwf_public_service --env -- rainbows -c config/rainbows.rb
-```
+The `--env` option to the `cmdb shim` command is now the default behavior and
+there is no way _not_ to populate the environment. We retain the safeguards
+that cause CMDB to raise an error if two sources would populate the environment
+with the same key name; overlap/inheritance is still disallowed.
 
-### 2.5.0 (2015-07-16)
+#### Removed: Dichotomy between key enumeration and single-get
 
-So many changes! View the diffs for info.
+In v2, calls to `#get` were required to include a source's prefix in the key
+name (e.g. `common.sandwich.size` whereas the key names returned from 
+`#each_pair` lacked a prefix (e.g. `sandwich.size`). This was confusing and
+served no real purpose, so all methods have been normalized to always include
+the prefix in the key name.
 
-### 2.1.0
+Naturally, sources with a nil prefix do not enforce this requirement!
 
-Initial release. Contains the following features:
- - API for querying a CMDB
- - Command-line shim for rewriting config files
- - Server restart feature to aid debugging
+It is safe to call `#get` on a source whose prefix does not match; the source
+will simply return nil. However, calling `#set` with an invalid key prefix
+will cause settable sources to raise `CMDB::BadKey`.
+
+#### Changed: Command-line interface
+
+The `cmdb` command now supports a number of common options that apply to all
+subcommands.
+
+Rather than have a hodgepodge of CLI options for each type of source, all sources 
+are represented by URLs where the scheme tells the gem what type of source to 
+create: `file://`, or `consul://`. You can specify as many sources as
+you'd like by passing `--source` option multiple times with different URLs.
+
+If you omit `--source` entirely, the CLI will scan the network for common
+locations of supported sources. If it finds nothing, it will exit with an
+error.
+ 
+#### Changed: data file locations
+
+The gem no longer scans fixed directories for JSON/YML files on startup; you 
+must explicitly provide the locations of every file that has CMDB keys by
+passing `--source=file:///foo/bar.yml` to the CLI.
+
+### Changed: shim command
+
+The `--dir` option has been renamed to `--rewrite` for clarity.
+
+The `--reload` and --reload-signal` options are no longer supported; CMDB has
+lost its ability to reload the app when your files change. As a result, we
+no longer depend on the `listen` gem.
+
+The option to specify a `--root` for the CMDB interface as a whole has been 
+removed.
+
+#### Implementation changes
+
+The dependency on Diplomat has been removed; we now speak to consul without a
+middleman.
+
+#### Design changes
+
+All sources have a new common base class `Source`, which also serves as an
+enclosing namespace for all derived classes (`Source::Consul`, 
+`Source::File`, etc).

data/Gemfile

@@ -4,11 +4,12 @@ source 'https://rubygems.org'
 gemspec
 
 gem 'rake'
-gem 'backticks'
-gem 'cucumber'
-gem 'rspec'
 
 group :test do
+  gem 'backticks', '1.0.0rc1'
+  gem 'docker-compose', '1.0.0rc2'
+  gem 'cucumber'
+  gem 'rspec'
   gem 'rubocop'
   gem 'webmock'
 end

data/Gemfile.lock

@@ -1,9 +1,7 @@
 PATH
   remote: .
   specs:
-    cmdb (2.6.2)
-      diplomat (~> 0.15)
-      listen (~> 3.0)
+    cmdb (3.0.0rc1)
       trollop (~> 2.0)
 
 GEM
@@ -11,7 +9,7 @@ GEM
   specs:
     addressable (2.4.0)
     ast (2.2.0)
-    backticks (0.4.0)
+    backticks (1.0.0rc1)
     builder (3.2.2)
     byebug (8.2.2)
     coderay (1.1.1)
@@ -29,22 +27,13 @@ GEM
       gherkin (~> 3.2.0)
     cucumber-wire (0.0.1)
     diff-lcs (1.2.5)
-    diplomat (0.15.0)
-      faraday (~> 0.9)
-      json (~> 1.8)
-    faraday (0.9.2)
-      multipart-post (>= 1.2, < 3)
-    ffi (1.9.10)
+    docker-compose (1.0.0rc2)
+      backticks (>= 1.0.0rc1)
     gherkin (3.2.0)
     hashdiff (0.3.0)
-    json (1.8.3)
-    listen (3.0.6)
-      rb-fsevent (>= 0.9.3)
-      rb-inotify (>= 0.9.7)
     method_source (0.8.2)
     multi_json (1.11.2)
     multi_test (0.1.2)
-    multipart-post (2.0.0)
     parser (2.3.0.6)
       ast (~> 2.2)
     powerpack (0.1.1)
@@ -57,9 +46,6 @@ GEM
       pry (~> 0.10)
     rainbow (2.1.0)
     rake (10.5.0)
-    rb-fsevent (0.9.7)
-    rb-inotify (0.9.7)
-      ffi (>= 0.5.0)
     rspec (3.4.0)
       rspec-core (~> 3.4.0)
       rspec-expectations (~> 3.4.0)
@@ -94,10 +80,11 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  backticks
+  backticks (= 1.0.0rc1)
   bundler (~> 1.10)
   cmdb!
   cucumber
+  docker-compose (= 1.0.0rc2)
   pry
   pry-byebug
   rake

data/LICENSE

@@ -0,0 +1,25 @@
+License
+-------
+
+(The MIT License)
+
+Copyright (c) 2015-2016 RightScale, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -3,17 +3,12 @@
 [![TravisCI][travis_ci_img]](https://travis-ci.org/rightscale/cmdb)
 [travis_ci_img]: https://travis-ci.org/rightscale/cmdb.svg?branch=master
 
-*NOTE:* this gem is under heavy development and it is likely that v3 will contain several interface-breaking
-changes and simplifications. We encourage you to play with our toys and give us feedback on how you would
-like to see the project evolve, but if you use this gem for production-grade software, please make sure to
-pin to version `~> 2.6` in your Gemfile to avoid breakage!
-
 CMDB is a Ruby interface for consuming data from one or more configuration management databases
 (CMDBs) and making that information available to Web applications.
 
 It is intended to support multiple CM technologies, including:
-  - JSON/YAML files on a local disk
   - consul
+  - JSON/YAML files on a local disk
   - (someday) etcd
   - (someday) ZooKeeper
 
@@ -26,39 +21,127 @@ CMDB supports two primary use cases:
 
   1. Decouple your modern (12-factor) application from the CM mechanism that is used to deploy it,
      transforming CMDB keys and values into the enviroment variables that your app expects.
-  2. Help you deploy your "legacy" application that expects its configuration to be written to
-     disk files, rewriting those files with data taken from the CMDB.
+  2. Deploy legacy applications that expect their configuration to be
+     written to disk files by rewriting files at app-load time, substituting
+     CMDB variables into the files as required.
+
+CMDB has three primary interfaces:
+
+  1. The `cmdb shim` command populates the environment with values and/or rewrites hardcoded
+     config files, then spawns your application.
+  2. The `CMDB::Interface` object provides a programmatic API for querying CMDBs. Its `#to_h`
+     method transforms the whole configuration into an environment-friendly hash if you prefer to seed the
+     environment yourself, without using the shim.
+  3. The `cmdb shell` command navigates your k/v store using filesystem-like
+  metaphors (`ls`, `cd`, and so forth)   
+
+# Data Model
+
+CMDB models all data sources as hierarchical trees whose nodes are named, and
+whose leaf nodes can contain a piece of data: strings, numbers, booleans, or
+lists are all supported data types. Maps are disallowed on order to prevent
+ambiguity; a map always represents a subtree of the k/v store, never a value.
+
+This model is a "least common denominator" simplification of the data models of
+YML, JSON, ZooKeeper and etcd; by disallowing maps as the values of keys, it
+avoids ambiguity over whether a map should be treated as a subtree or as a
+distinct value.
+
+## Source Prefixes
+
+Some CMDB sources have a `prefix`, indicating that _all_ keys contained in
+that source begin with the same prefix. No two sources may share a prefix,
+ensuring that sources don't "hide" each others' data. The prefix of a source is
+usually automatically determined by the final component of its URL, e.g. the
+filename in the case of `file://` sources and the final path component in the
+case of `consul://` or other network sources.
+
+## Inheritance
+
+The uniqueness constraint on prefixes means that all sources' keys are
+disjoint; there is no such thing as "inheritance" in the CMDB data model.
 
-The gem has two primary interfaces:
-- The `cmdb shim` command populates the environment with values and/or rewrites hardcoded
-  config files, then spawns your application. It can also be told to watch the filesystem for changes and
-  send a signal e.g. `SIGHUP` to your application, bringing reload-on-edit functionality to any app.
-- The `CMDB::Interface` object provides a programmatic API for querying CMDBs. Its `#to_h`
-  method transforms the whole configuration into an environment-friendly hash if you prefer to seed the
-  environment yourself, without using the shim.
+When keys are exported to the environment, the prefix is stripped from the
+key name; however, CMDB _still_ prevents overlap in this case.
+ 
+Inheritance may be supported in future as an optional behavior, but is omitted
+for the time being because in practice, it causes more problems than it solves.
+
+## Ambiguous Key Names
+
+Consider a file that defines the following variables:
+
+    # confusing.yml
+    this:
+      is:
+        ambiguous
+      was:
+        very: ambiguous
+        extremely: confusing
+
+At first glance, ths file defines two CMDB keys:
+  - `confusing.this.is` (a string)
+  - `confusing.this.was` (a map)
+
+However, an equally valid interpretation would be:
+  - `confusing.this.is`
+  - `confusing.this.was.very`
+  - `confusing.this.was.extremely`
+
+Because CMDB keys cannot contain maps, the first interpretation is wrong. The second
+interpretation is valid according to the data model, but results in a situation where the type
+of the keys could change if the structure of the YML file changes.
+
+For this reason, any YAML file that defines an "ambiguous" key name will cause an error at
+initialization time. To avoid ambiguous key names, think of your YAML file as a tree and remember
+that _leaf nodes must define data_ and _internal nodes must define structure_.
 
 # Getting Started
 
-## Create CMDB Data Files
+## Determine sources
+
+Sources are specified with the `--source` option when you run the CLI. This
+option applies to all subcommands (`shim`, `shell`, etc) and must appear
+before the subcommand name.
+
+You can add as many sources as you'd like. All sources are specified as a URI,
+where the scheme tells CMDB which driver to use and how to interpret the rest
+of the URI.
+
+
 
-The shim looks in two locations to find data files. In order of precedence:
+Sources can optionally have a "prefix" which is used as a common prefix of all
+key names under the source. When CMDB can identify the prefix for your source,
+it makes merge operations more efficient, helps provide semantic context
+for your key names, and makes it easier to identify and avoid naming collisions
+between different sources.
 
-  1. `/var/lib/cmdb` -- typically at deployment time
-  2. `~/.cmdb` -- useful for developers when testing the app
+Examples:
 
-The base name (minus extension) of each file is important; it determines the top-level name of
-the keys in that file and it *must be unique* across all of the directories. For instance,
-`my_app.json` defines CMDB keys in the `my_app.*` hierarchy.
+  * `file:///var/lib/cmdb/myapp.yml` creates a file source with the prefix
+    `myapp`; the value `foo: bar` in the file would have the key `myapp.foo`
+  * `consul://localhost` creates a source with no key prefix that talks to a local
+    consul agent on the standard port (8500); a value `foo/bar` in Consul would
+    have the key `foo.bar
+  * `consul://kv:18500/myapp` creates a source with the prefix `myapp.` that
+    talks to a remote consul agent on a nonstandard port (18500); this source
+    only "sees" Consul values under the path `/myapp/` and their key
+    names always begin with `myapp.`
+  * `consul://localhost/mycorp/staging/myapp` creates a source with the prefix
+    `myapp.`; this source only "sees" Consul values under the path
+    `staging/myapp` and their key names always begin with `myapp.`
+  * `consul://localhost/mycorp/staging` creates a source with the prefix `staging.`
+    that has all keys in the staging environment. (It is probably a bad idea to
+    use this source with the `myapp` source in the example above!)
 
-Create a data file in one of these directories; for example, you might create `my_app.yml` with
-the following contents:
+If no sources are specified on the command line, CMDB will run an auto-detect
+algorithm to check for network agents listening at localhost. 
 
-    db:
-      hostname: db1.local
-    widgets:
-      flavors:
-        - vanilla
-        - chocolate
+To learn more about sources and prefixes, see "Data model," below.
+
+## Invoke the CMDB Shell
+
+To enter an interactive sh-like shell, just type `cmdb shell`. 
 
 ## Invoke the CMDB Shim
 
@@ -75,23 +158,30 @@ your application. The shim can do several things for you:
 If you have an app that uses 12-factor (dotenv) style configuration, the shim
 can populate the environment with CMDB values:
 
-    bundle exec cmdb shim --env
+    bundle exec cmdb shim
 
     # Now your app can refer to ENV['DB_HOSTNAME'] or ENV['WIDGETS_FLAVORS]
     # Note missing "my_app" prefix that would be present if you asked for these using their CMDB key names
 
+Note that when we export CMDB keys into the environment, we _remove_ the prefix of
+each key; in the example above, the values could have come from `common.db.hostname`
+and `myapp.widgets.flavors` but their names have been simplified. If any two sources
+have keys whose simplified names are identical, CMDB prints a detailed error message
+and fails rather than putting ambiguous data into the environment.
+
 Note that the data type of CMDB inputs is preserved: lists remain lists, numbers remain numbers,
 and so forth. This works irrespective of the format of your configuration files, and also holds true
 for CMDB values that are serialized to the environment (as a JSON document, in the case of lists).
 
-### Rewriting configuration files with CMDB values
+### Rewrite static configuration files with dynamic CMDB values
 
-If the `--dir` option is provided, the shim recursively scans your working
-directory (`Dir.pwd`) for data files that contain replacement tokens; when a token is
+If the `--rewrite` option is provided, the shim recursively scans the provided
+subdirectory for data files that contain replacement tokens; when a token is
 found, it substitutes the corresponding CMDB key's value.
 
 Replacement tokens look like this: `<<name.of.my.key>>` and can appear anywhere in a file as a YAML
-or JSON _value_ (but never a key).
+or JSON _value_ (but never a key). Unlike environment variables, replacement tokens always use
+the fully-qualified key name, including prefix. 
 
 Replacement tokens should appear inside string literals in your configuration files so they don't
 invalidate syntax or render the files unparsable by other tools.
@@ -100,10 +190,6 @@ The shim performs replacement in-memory and saves all of the edits at once, maki
 operation nearly atomic. If any keys are missing, then no files are changed on disk and the shim
 exits with a helpful error message.
 
-*NOTE:* the shim does not perform rewriting in development mode; the expectation is that your app's
-configuration files will already provide reasonable dev-mode defaults and that rewriting them
-is not necessary.
-
 Given `my_app.yml` and an application with two configuration files:
 
     # config/database.yml
@@ -136,135 +222,21 @@ can do this for you. Just add the `--user` flag when you invoke it:
 
     bundle exec cmdb shim --user=www-data whoami
 
-### Reload the App When Code Changes
-
-You can pass the `--reload=key.name` option to `cmdb shim` in order to enable filesystem
-watching. The shim will signal your application server whenever files are created,
-updated or deleted, generally causing a graceful restart of the server process.
-
-Needless to say, your app server must support graceful restart upon receipt of
-a certain signal! The CMDB gem uses SIGHUP by default, but you can override this
-with --reload-signal=SIGWHATEVER.
+# Data Sources
 
-The parameter names a CMDB key (such as `key.name`) whose value determines whether filesystem
-watching is enabled. It *should* be a boolean, but *may* be nil or any "truthy" value such as a
-number or string. If the key is truthy, then the shim will perform filesystem-watching.
+## Network Servers
 
-## Query the CMDB Directly
+To read CMDB data from a consul server, add a CLI parameter such as
+`--source=consul://some-host/key/subkey`. This will create a source whose
+prefix is `subkey` that encompasses the  subtree of the k/v store that lies
+underneath `/key/subkey`.
 
-Ruby applications can access the CMDB as a Ruby proxy object:
+## Flat Files
 
-    # Ready to use; no bootstrapping required.
-    require 'cmdb'
+To read CMDB data from a flat file on disk, add a CLI parameter such as
+`--source=file:///var/lib/cmdb/mykeys.yml`. This will parse the YAML file
+located in `/var/lib/cmdb` and present it as a source whose prefix is `mykeys`.
 
-    cmdb = CMDB::Interface.new
-    cmdb.get('my_app.my_setting')
-    cmdb.get('my_app.some_other_setting')
-
-This allows you to read CMDB values from the directly from your code.
-
-# Data Model
-
-This library models all CMDBs as hierarchical key/value stores whose leaf nodes can be strings,
-numbers, or arrays of like-typed objects. This model is a "least common denominator" simplification
-of the data models of YML, JSON, ZooKeeper and etcd, allowing all of those technologies to be
-treated as interchangeable sources of configuration information.
-
-CMDB key names consist of a dot-separated string e.g. `my_app.category_of_settings.some_value`. The
-value of a CMDB key can be a string, boolean, number, nil, or a list of any of those types.
-
-CMDB keys *cannot* contain maps/hashes, nor can lists contain differently-typed data.
-
-When a CMDB key is accessed through the Ruby API or referenced with a file-rewrite <<token>>, its
-name always begins with the file or path name of its *source* (JSON file, consul path, etc).
-
-When a CMDB key is written into the process environment or accessed via `Source#to_h`, its name
-is "bare" and the source name is irrelevant.
-
-If we use a `--consul-prefix` of `/kv/rightscale/intregration/shard403/common`
-then a key names would look like `common.debug.enabled` and environment names
-would look like `DEBUG_ENABLED`. The same is true if we load a `common.json`
-file source from `/var/lib/cmdb`.
-
-A future version of cmdb will harmonize the treatment of names; the prefix
-will be insignificant to the key name and keys will look like environment
-variables.
-
-## Network Data Sources
-
-To read from a consul server, pass `--consul-url` with a consul server address
-and `--consul-prefix` one or more times with a top-level path to treat as a
-named source.
-
-## Disk-Based Data Sources
-
-When the CMDB interface is initialized, it searches two directories for YAML files:
- - /var/lib/cmdb
- - ~/.cmdb
-
-YAML files in these directories are assumed to contain CMDB values and loaded into memory in the
-order they are encountered. The hierarchy of the YAML keys is flattened in order to derive
-dot-separated key names. Consider the following YAML file:
-
-    # beverages.yml
-    coffee:
-      - latte
-      - cappucino
-      - mocha
-      - macchiato
-    tea:
-      - chai
-      - herbal
-      - black
-    to_go: true
-
-This defines three CMDB values: `beverages.coffee` (a list of four items), `beverages.tea`
-(a list of three items), and `beverages.to_go` (a boolean).
-
-### Key Namespaces
-
-The name of a CMDB file is important; it defines a namespace for all of the variables contained
-inside. No two files may share a name; therefore, no two CMDB keys can have the same name.
-Likewise, all keys with a given prefix are guaranteed to come from the same source.
-
-### Overlapping Namespaces
-
-Because CMDB files can come from several directories, it's possible for two same-named data files
-to define values in the same namespace. In this case, the behavior of RightService varies depending
-on the value of RACK_ENV or RAILS_ENV:
-
-  - unset, development or test: CMDB chooses the highest-precedence file and ignores the others
-    after printing a warning. Files in `/etc` win over files in `$HOME`, which win over
-    files in the working directory.
-
-  - any other environment: CMDB fails with an error message that describes the problem and
-    the locations of the overlapping files.
-
-### Ambiguous Key Names
-
-Consider a file that defines the following variables:
-
-    # confusing.yml
-    this:
-      is:
-        ambiguous
-      was:
-        very: ambiguous
-        extremely: confusing
-
-At first glance, ths file defines two CMDB keys:
-  - `confusing.this.is` (a string)
-  - `confusing.this.was` (a map)
-
-However, an equally valid interpretation would be:
-  - `confusing.this.is`
-  - `confusing.this.was.very`
-  - `confusing.this.was.extremely`
-
-Because CMDB keys cannot contain maps, the first interpretation is wrong. The second
-interpretation is valid according to the data model, but results in a situation where the type
-of the keys could change if the structure of the YML file changes.
-
-For this reason, any YAML file that defines an "ambiguous" key name will cause an error at
-initialization time. To avoid ambiguous key names, think of your YAML file as a tree and remember
-that _leaf nodes must define data_ and _internal nodes must define structure_.
+JSON and YAML files are both supported. The structured data within each file
+can contain arbitrarily-deep subtrees which are interpreted as subkeys,
+sub-subkeys and so forth.

data/Rakefile

@@ -15,3 +15,16 @@ require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new(:spec)
 
 task default: [:spec, :cucumber]
+
+
+require 'docker/compose'
+desc 'Create Consul source using Docker Compose and invoke cmdb shell'
+task :sandbox do
+  compose = Docker::Compose::Session.new
+  compose.up 'consul', detached:true
+  mapper = Docker::Compose::Mapper.new(compose)
+  url = mapper.map('consul://consul:8500/sandbox')
+
+  lib = File.expand_path('../lib', __FILE__)
+  exec "ruby -I#{lib} -rpry exe/cmdb --source=#{url} shell"
+end

data/cmdb.gemspec

@@ -19,10 +19,8 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.required_ruby_version = Gem::Requirement.new('~> 2.0')
+  spec.required_ruby_version = Gem::Requirement.new('~> 2.1')
 
-  spec.add_dependency 'listen', '~> 3.0'
-  spec.add_dependency 'diplomat', '~> 0.15'
   spec.add_dependency 'trollop', '~> 2.0'
 
   spec.add_development_dependency 'bundler', '~> 1.10'