summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorelijah <elijah@riseup.net>2015-02-03 12:33:02 -0800
committerelijah <elijah@riseup.net>2015-02-03 12:33:02 -0800
commitb2c8700680b5b6d45a3760e447c4ca999f07336a (patch)
tree86ec7e0719cfca923ad9ace14a86261ef310170b
parent6ad1e45761d61dab5d3fb3db9495bf22b841c309 (diff)
added platform environments page
-rw-r--r--docs/platform/guide/environments.md69
-rw-r--r--docs/platform/guide/nodes.md14
-rw-r--r--menu.txt1
3 files changed, 82 insertions, 2 deletions
diff --git a/docs/platform/guide/environments.md b/docs/platform/guide/environments.md
new file mode 100644
index 0000000..67d8ace
--- /dev/null
+++ b/docs/platform/guide/environments.md
@@ -0,0 +1,69 @@
+@title = "Working with environments"
+@nav_title = "Environments"
+@summary = "How to partition the nodes into separate environments."
+
+With environments, you can divide your nodes into different and entirely separate sets. For example, you might have sets of nodes for 'testing', 'staging' and 'production'.
+
+Typically, the nodes in one environment are totally isolated from the nodes in a different environment. Each environment will have its own separate database, for example.
+
+There are a few exceptions to this rule: backup nodes, for example, will by default attempt to back up data from all the environments (excluding local).
+
+## Assign an environment
+
+To assign an environment to a node, you just set the `environment` node property. This is typically done with tags, although it is not necessary. For example:
+
+`tags/production.json`
+
+ {
+ "environment": "production"
+ }
+
+`nodes/mynode.json`
+
+ {
+ "tags": ["production"]
+ }
+
+There are several built-in tags that will apply a value for the environment:
+
+* `production`: An environment for nodes that are in use by end users.
+* `development`: An environment to be used for nodes that are being used for experiments or staging.
+* `local`: This environment gets automatically applied to all nodes that run only on local VMs. Nodes with a `local` environment are treated special and excluded from certain calculations.
+
+You don't need to use these and you can add your own.
+
+## Environment commands
+
+* `leap env` -- List the available environments and disply which one is active.
+* `leap env pin ENV` -- Pin the current environment to ENV.
+* `leap env unpin` -- Remove the environment pin.
+
+The environment pin is only active for your local machine: it is not recorded in the provider directory and not shared with other users.
+
+## Environment specific JSON files
+
+You can add JSON configuration files that are only applied when a specific environment is active. For example, if you create a file `provider.production.json`, these values will only get applied to the `provider.json` file for the `production` environment.
+
+This will also work for services and tags. For example:
+
+ provider.local.json
+ services/webapp.development.json
+ tags/seattle.production.json
+
+In this example, `local`, `development`, and `production` are the names of environments.
+
+## Bind an environment to a Platform version
+
+If you want to ensure that a particular environment is bound to a particular version of the LEAP Platform, you can add a `platform` section to the `provider.ENV.json` file (where ENV is the name of the environment in question).
+
+The available options are `platform.version`, `platform.branch`, or `platform.commit`. For example:
+
+ {
+ "platform": {
+ "version": "1.6.1",
+ "branch": "develop",
+ "commit": "5df867fbd3a78ca4160eb54d708d55a7d047bdb2"
+ }
+ }
+
+You can use any combination of `version`, `branch`, and `commit` to specify the binding. The values for `branch` and `commit` only work if the `leap_platform` directory is a git repository.
diff --git a/docs/platform/guide/nodes.md b/docs/platform/guide/nodes.md
index 1cfb156..30bf5b3 100644
--- a/docs/platform/guide/nodes.md
+++ b/docs/platform/guide/nodes.md
@@ -162,7 +162,17 @@ Disabling Nodes
There are two ways to temporarily disable a node:
-**Option 1: enabled == false**
+**Option 1: disabled environment**
+
+You can assign an environment to the node that marks it as disabled. Then, if you use environment pinning, the node will be ignored when you deploy. For example:
+
+ {
+ "environment": "disabled"
+ }
+
+Then use `leap env pin ENV` to pin the environment to something other than 'disabled'. This only works if all the other nodes are also assigned to some environment.
+
+**Option 2: enabled == false**
If a node has a property `enabled` set to false, then the `leap` command will skip over the node and pretend that it does not exist. For example:
@@ -172,6 +182,6 @@ If a node has a property `enabled` set to false, then the `leap` command will sk
"enabled": false
}
-**Options 2: no-deploy**
+**Options 3: no-deploy**
If the file `/etc/leap/no-deploy` exists on a node, then when you run the commmand `leap deploy` it will halt and prevent a deploy from going through (if the node was going to be included in the deploy).
diff --git a/menu.txt b/menu.txt
index bbddcd6..1061bf1 100644
--- a/menu.txt
+++ b/menu.txt
@@ -20,6 +20,7 @@ docs
guide
nodes
keys-and-certificates
+ environments
miscellaneous
config
commands