diff options
Diffstat (limited to 'docs/platform/config.md')
-rw-r--r-- | docs/platform/config.md | 110 |
1 files changed, 96 insertions, 14 deletions
diff --git a/docs/platform/config.md b/docs/platform/config.md index 2d56467..89bf934 100644 --- a/docs/platform/config.md +++ b/docs/platform/config.md @@ -1,5 +1,8 @@ -Configuration Files -================================= +Configuration files +=================================== + +File format +------------------------------------------- All configuration files are in JSON format. For example @@ -8,7 +11,7 @@ All configuration files are in JSON format. For example "key2": "value2" } -Keys should match /[a-z0-9_]/ +Keys should match `/[a-z0-9_]/` Unlike traditional JSON, comments are allowed. If the first non-whitespace character is '#' the line is treated as a comment. @@ -18,15 +21,20 @@ Unlike traditional JSON, comments are allowed. If the first non-whitespace chara "key": "value" # this is an error } -Options in the configuration files might be nested. For example: +Options in the configuration files might be nested hashes or arrays. For example: { "openvpn": { - "ip_address": "1.1.1.1" + "ip_address": "1.1.1.1", + "protocols": ["tcp", "udp"], + "options": { + "public_ip": false, + "adblock": true + } } } -If the value string is prefixed with an '=' character, the value is evaluated as ruby. For example +If the value string is prefixed with an '=' character, the value is evaluated as ruby. For example: { "domain": { @@ -37,14 +45,88 @@ If the value string is prefixed with an '=' character, the value is evaluated as In this case, "api_domain" will be set to "api.domain.org". +Inheritance +---------------------------------------- + +Suppose you have a node configuration for `bitmask/nodes/dns_europe.json` like so: + + { + "services": "dns", + "tags": ["production", "europe"], + "ip_address": "1.1.1.1" + } + +This node will have hostname "dns-europe" and it will inherit from the following files (in this order): + + 1. provider_base/common.json + 2. bitmask/common.json + 3. provider_base/services/dns.json + 4. bitmask/services/dns.json + 5. provider_base/tags/production.json + 6. bitmask/tags/production.json + 7. provider_base/tags/europe.json + 8. bitmask/tags/europe.json + 9. bitmask/nodes/dns_europe.json + +The `provider_base` directory is under the `leap_platform` specified in the file `Leapfile`. + +To see all the variables a node has inherited, you could run `leap inspect dns_europe`. + +Macros +---------------------------------------- + +When using evaluated ruby in a JSON configuration file, there are several special macros that are available. These are evaluated in the context of a node (available as the variable `self`). + The following methods are available to the evaluated ruby: -* nodes -- A list of all nodes. This list can be filtered. -* global.services -- A list of all services. -* global.tags -- A list of all tags. -* file(filename) -- Inserts the full contents of the file. If the file is an erb - template, it is rendered. -* file_path(filename) -- Ensures that the file will get rsynced to the node as an individual file. The value returned by `file_path` is where this file will utlimately live when on the node. -* secret(symbol) -- Returns the value of a secret in secrets.json (or creates it if necessary). -* variable -- Any variable inherited by a particular node is available by just referencing it using either hash notation or object notation (i.e. self['domain']['public'] or domain.public). Circular references are not allowed, but otherwise it is ok to nest evaluated values in other evaluated values. +`nodes` + + > A hash of all nodes. This list can be filtered. + +`nodes_like_me` + + > A hash of nodes that have the same deployment tags as the current node (e.g. 'production' or 'local'). + +`global.services` + + > A hash of all services, e.g. `global.services['openvpn']`. + +`global.tags` + + > A hash of all tags, e.g. `global.tags['production']`. + + `global.provider` + + > Can be used to access variables defined in `provider.json`, e.g. `global.provider.contacts.default`. + +`file(filename)` + + > Inserts the full contents of the file. If the file is an erb template, it is rendered. The filename can either be one of the pre-defined file symbols, are it can be a path relative to the "files" directory in your provider instance. E.g, `file :ca_cert` or `files 'ca/ca.crt'`. + +`file_path(filename)` + + > Ensures that the file will get rsynced to the node as an individual file. The value returned by `file_path` is the full path where this file will ultimately live when deploy to the node. e.g. `file_path :ca_cert` or `file_path 'branding/images/logo.png'`. + +`secret(:symbol)` + + > Returns the value of a secret in secrets.json (or creates it if necessary). E.g. `secret :couch_admin_password` + +`variable.variable` + + > Any variable defined or inherited by a particular node configuration is available by just referencing it using either hash notation or object field notation (e.g. `['domain']['public']` or `domain.public`). Circular references are not allowed, but otherwise it is OK to nest evaluated values in other evaluated values. If a value has not been defined, the hash notation will return nil but the field notation will raise an exception. + +Using hashes +----------------------------------------- + +The macros `nodes`, `nodes_like_me`, `global.services`, and `global.tags` all return a hash of other objects. You can reference these hashes either directly or using a filter: + +Direct access: + + nodes['vpn1'] # returns node named 'vpn1' + global.services['openvpn'] # returns service named 'openvpn' + +Filters: + nodes[:public_dns => true] # all nodes where public_dns == true + nodes[:services => 'openvpn', :services => 'tor'] # openvpn OR tor + nodes[:services => 'openvpn'][:tags => 'production'] # openvpn AND production |