update /doc directory with latest from leap docs/platform

Change-Id: I696af649806a7321f92baaf55dc5d404ce5c3d93

1 files changed, 129 insertions, 32 deletions

diff --git a/doc/guide/config.md b/doc/guide/config.md
index be67e6bd..bcea26c4 100644
--- a/doc/guide/config.md
+++ b/doc/guide/config.md
@@ -1,39 +1,69 @@
 @title = "Configuration Files"
-@summary = "How to edit configuration files."
+@summary = "Understanding and editing the configuration files."
 
 Files
 -------------------------------------------
 
-Here are a list of some of the common files that make up a provider. Except for Leapfile and provider.json, the files are optional. Unless otherwise specified, all file names are relative to the 'provider directory' root (where the Leapfile is).
-
-`Leapfile` -- If present, this file tells `leap` that the directory is a provider directory. This file is usually empty, but can contain global options.
-
-`~/.leaprc` -- Evaluated the same as Leapfile, but not committed to source control.
-
-`provider.json` -- Global options related to this provider.
-
-`provider.ENVIRONMENT.json` -- Global options for the provider that are applied to only a single environment.
-
-`common.json` -- All nodes inherit from this file.
-
-`secrets.json` -- An automatically generated file that contains any randomly generated strings needed in order to deploy. These strings are often secret and should be protected, although any need for a random string or number that is remembered will produce another entry in this file. This file is automatically generated and refreshed each time you run `leap compile` or `leap deploy`. If an entry is no longer needed, it will get removed. If you want to change a secret, you can remove this file and have it regenerated, or remove the particular line item and just those items will be created anew.
-
-`facts.json` -- If some of your servers are running on AWS or OpenStack, you will need to discover certain properties about how networking is configured on these machines in order for a full deploy to work. In these cases, make sure to run `leap facts update` to periodically regenerate the facts.json file.
-
-`nodes/NAME.json` -- The configuration file for node called NAME.
-
-`services/SERVICE.json` -- The properties in this configuration file are applied to any node that includes SERVICE in its `services` property.
-
-`services/SERVICE.ENVIRONMENT.json` -- The properties in this configuration file are applied to any node that includes SERVICE in its services and has environment equal to ENVIRONMENT.
-
-`services/TAG.json` -- The properties in this configuration file are applied to any node that has includes TAG in its `tags` property.
-
-`services/TAG.ENVIRONMENT.json` -- The properties in this configuration file are applied to any node that has includes TAG in its `tags` property and has `environment` property equal to ENVIRONMENT.
-
-`files/*` -- Various static files used by the platform (e.g. keys, certificates, webapp customization, etc).
-
-`users/USER/` -- A directory that stores the public keys of the sysadmin with name USER. This person will have root access to all the servers.
-
+Here are a list of some of the common files that make up a provider. Except for `Leapfile` and `provider.json`, the files are optional. Unless otherwise specified, all file names are relative to the 'provider directory' root (where the Leapfile is).
+
+<table class="table table-striped">
+<tr>
+  <td><code>Leapfile</code></td>
+  <td>If present, this file tells <code>leap</code> that the directory is a provider directory. This file is usually empty, but can contain global options.</td>
+</tr>
+<tr>
+  <td><code>~/.leaprc</code></td>
+  <td>Evaluated the same as Leapfile, but not committed to source control.</td>
+</tr>
+<tr>
+  <td><code>provider.json</code></td>
+  <td>Global options related to this provider. See [[provider-configuration]].</td>
+</tr>
+<tr>
+  <td><code>provider.ENVIRONMENT.json</code></td>
+  <td>Global options for the provider that are applied to only a single environment.</td>
+</tr>
+<tr>
+  <td><code>nodes/NAME.json</code></td>
+  <td>The configuration file for node called NAME.</td>
+</tr>
+<tr>
+  <td><code>common.json</code></td>
+  <td>All nodes inherit from this file. In other words, any options that appear in <code>common.json</code> will be added as default values to each node configuration, value that can be locally overridden.</td>
+</tr>
+<tr>
+  <td><code>services/SERVICE.json</code></td>
+  <td>The properties in this configuration file are applied to any node that includes SERVICE in its <code>services</code> property.</td>
+</tr>
+<tr>
+  <td><code>services/SERVICE.ENVIRONMENT.json</code></td>
+  <td>The properties in this configuration file are applied to any node that includes SERVICE in its services and has environment equal to ENVIRONMENT.</td>
+</tr>
+<tr>
+  <td><code>tags/TAG.json</code></td>
+  <td>The properties in this configuration file are applied to any node that has includes TAG in its <code>tags</code> property.</td>
+</tr>
+<tr>
+  <td><code>tags/TAG.ENVIRONMENT.json</code></td>
+  <td>The properties in this configuration file are applied to any node that has includes TAG in its <code>tags</code> property and has <code>environment</code> property equal to ENVIRONMENT.</td>
+</tr>
+<tr>
+  <td><code>secrets.json </code></td>
+  <td>An automatically generated file that contains any randomly generated strings needed in order to deploy. These strings are often secret and should be protected, although any need for a random string or number that is remembered will produce another entry in this file. This file is automatically generated and refreshed each time you run <code>leap compile</code> or <code>leap deploy</code>. If an entry is no longer needed, it will get removed. If you want to change a secret, you can remove this file and have it regenerated, or remove the particular line item and just those items will be created anew.</td>
+</tr>
+<tr>
+  <td><code>facts.json</code></td>
+  <td>If some of your servers are running on AWS or OpenStack, you will need to discover certain properties about how networking is configured on these machines in order for a full deploy to work. In these cases, make sure to run <code>leap facts update</code> to periodically regenerate the facts.json file.</td>
+</tr>
+<tr>
+  <td><code>files/*</code></td>
+  <td>Various static files used by the platform (e.g. keys, certificates, webapp customization, etc). In general, only generated files and files used to customize the provider (such as images) live in the <code>files</code> directory.</td>
+</tr>
+<tr>
+  <td><code>users/USER/</code></td>
+  <td>A directory that stores the public keys of the sysadmin with name USER. This person will have root access to all the servers.</td>
+</tr>
+</table>
 
 Leapfile
 -------------------------------------------
@@ -51,8 +81,10 @@ Platform options:
 
 Vagrant options:
 
+* `@vagrant_provider`. Changes the default vagrant provider ("virtualbox"). For example, `@vagrant_provider = "libvirt"`.
 * `@vagrant_network`. Allows you to override the default network used for local nodes. It should include a netmask like `@vagrant_network = '10.0.0.0/24'`.
 * `@custom_vagrant_vm_line`. Insert arbitrary text into the auto-generated Vagrantfile. For example, `@custom_vagrant_vm_line = "config.vm.boot_mode = :gui"`.
+* `@vagrant_basebox` allows specifying a different basebox as the default one. For example, `@vagrant_basebox = "LEAP/jessie"`.
 
 Logging options:
 
@@ -69,7 +101,7 @@ All configuration files, other than `Leapfile`, are in the JSON format. For exam
       "key2": "value2"
     }
 
-Keys should match `/[a-z0-9_]/`
+Keys should match `/[a-z0-9_]/` and must be in double quotes.
 
 Unlike traditional JSON, comments are allowed. If the first non-whitespace characters are `//` then the line is treated as a comment.
 
@@ -141,6 +173,71 @@ The `provider_base` directory is under the `leap_platform` specified in the file
 
 To see all the variables a node has inherited, you could run `leap inspect willamette`.
 
+### Inheritance rules
+
+Suppose you have a node configuration `mynode.json`:
+
+    {
+      "tags": "production",
+      "simple_value": 100,
+      "replaced_array": ["dolphin", "kangaroo"],
+      "+add_array": ["red", "black"],
+      "-subtract_array": ["bitter"],
+      "converted_to_array": "not_array_element",
+      "!override": ["insist on this value"],
+      "hash": {
+        "key1": 1,
+        "key2": 2
+      }
+    }
+
+And a file `tags/production.json`:
+
+    {
+      "simple_value": 99999,
+      "replaced_array": ["zebra"],
+      "add_array": ["green],
+      "subtract_array": ["bitter", "sweet", "salty"],
+      "converted_to_array": ["array_element"],
+      "override": "this value will be overridden",
+      "hash": {
+        "key1": "one"
+      }
+    }
+
+In this scenario, `mynode.json` will inherit from `production.json`. The output of this inheritance will be:
+
+    {
+      "tags": "production",
+      "simple_value": 100,
+      "replaced_array": ["dolphin", "kangaroo"],
+      "add_array": ["red", "black", "green"],
+      "subtract_array": ["sweet", "salty"],
+      "converted_to_array": ["not_array_element", "array_element"],
+      "override": ["insist on this value"],
+      "hash": {
+        "key1": 1,
+        "key2": 2
+      }
+
+The rules for inheritance (where 'old' refers to the parent, and 'new' refers to the child):
+
+* Simple values (strings, numbers, boolean):
+  * Replace the old value with the new value.
+* Array values:
+  * Two arrays: replace the old array with the new array.
+  * One array and one simple value: add the simple value to the array.
+  * If property name is prefixed with "+": merge the old and new arrays.
+  * If property name is prefixed with "-": subtract new array from old array.
+* Hash values:
+  * Hashes are always merged (the result includes the keys of both hashes). If there is a key in common, the new one overrides the old one.
+* Mismatch:
+  * Although you can mix arrays and simple values, you cannot mix arrays with hashes or hashes with simple values. If you attempt to do so, it will fail to compile and give you an error message.
+* Override:
+  * If property name is prefixed with "!": then ensure that new value is always used, regardless of old value. In this case, the override takes precedence over type checking, so you will never get a type mismatch.
+
+NOTE: special property name prefixes, like "+", "-", or "!", are not included in the property name. These prefixes determine the merge strategy, but are stripped out when compiling the resulting JSON file.
+
 Common configuration options
 ----------------------------------------