diff options
Diffstat (limited to 'doc/guide')
| -rw-r--r-- | doc/guide/commands.md | 2 | ||||
| -rw-r--r-- | doc/guide/en.haml | 2 | ||||
| -rw-r--r-- | doc/guide/environments.md | 75 | ||||
| -rw-r--r-- | doc/guide/keys-and-certificates.md | 22 | ||||
| -rw-r--r-- | doc/guide/nodes.md | 74 |
5 files changed, 142 insertions, 33 deletions
diff --git a/doc/guide/commands.md b/doc/guide/commands.md index 0cee709a..7d0aa1b2 100644 --- a/doc/guide/commands.md +++ b/doc/guide/commands.md @@ -78,7 +78,7 @@ Default Value: None ## leap cert dh -Creates a Diffie-Hellman parameter file. +Creates a Diffie-Hellman parameter file, needed for forward secret OpenVPN ciphers. You don't need this file if you don't provide the VPN service. diff --git a/doc/guide/en.haml b/doc/guide/en.haml index 4c9bd69f..61c24ea8 100644 --- a/doc/guide/en.haml +++ b/doc/guide/en.haml @@ -1,6 +1,4 @@ - @nav_title = "Guide" - @title = "Platform Guide" -%h1.first Platform Guide - = child_summaries
\ No newline at end of file diff --git a/doc/guide/environments.md b/doc/guide/environments.md new file mode 100644 index 00000000..752e0608 --- /dev/null +++ b/doc/guide/environments.md @@ -0,0 +1,75 @@ +@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. + +The value for `commit` is passed directly through to `git log` to query for a list of acceptable commits. See [[man gitrevisions => https://www.kernel.org/pub/software/scm/git/docs/gitrevisions.html#_specifying_ranges]] to see how to specify ranges. For example: + +* `HEAD^..HEAD` - current commit must be head of the branch. +* `3172444652af71bd771609d6b80258e70cc82ce9..HEAD` - current commit must be after 3172444652af71bd771609d6b80258e70cc82ce9. +* `refs/tags/0.6.0rc1..refs/tags/0.6.0rc2` - current commit must be after tag 0.6.0rc1 and before or including tag 0.6.0rc2.
\ No newline at end of file diff --git a/doc/guide/keys-and-certificates.md b/doc/guide/keys-and-certificates.md index bd7f3495..aef02ac6 100644 --- a/doc/guide/keys-and-certificates.md +++ b/doc/guide/keys-and-certificates.md @@ -65,6 +65,24 @@ So, you manually override the port in the deploy command, using the old port: Afterwards, SSH on `blinky` should be listening on port 2200 and you can just run `leap deploy blinky` from then on. +Sysadmins with multiple SSH keys +----------------------------------- + +The command `leap add-user --self` allows only one SSH key. If you want to specify more than one key for a user, you can do it manually: + + users/userx/userx_ssh.pub + users/userx/otherkey_ssh.pub + +All keys matching 'userx/*_ssh.pub' will be usable. + +Removing sysadmin access +-------------------------------- + +Suppose you want to remove `userx` from having any further ssh access to the servers. Do this: + + rm -r users/userx + leap deploy + X.509 Certificates ================================ @@ -153,7 +171,7 @@ This command will generate the CSR and private key matching `provider.domain` (y The related commercial cert files are: files/ - certs/ + cert/ domain.org.crt # Server certificate for domain.org, obtained by commercial CA. domain.org.csr # Certificate signing request domain.org.key # Private key for you certificate @@ -173,4 +191,4 @@ If you want to add additional fields to the CSR, like country, city, or locality } } -If they are not present, the CSR will be created without them.
\ No newline at end of file +If they are not present, the CSR will be created without them. diff --git a/doc/guide/nodes.md b/doc/guide/nodes.md index bc48ff32..cf225449 100644 --- a/doc/guide/nodes.md +++ b/doc/guide/nodes.md @@ -20,7 +20,7 @@ Brief overview of the services: * **soledad**: Handles the data syncing with clients. Typically combined with `couchdb` service, since it communicates heavily with couchdb. * **mx**: Incoming and outgoing MX servers. Communicates with the public internet, clients, and `couchdb` nodes. * **openvpn**: OpenVPN gateway for clients. You need at least one, but want as many as needed to support the bandwidth your users are doing. The `openvpn` nodes are autonomous and don't need to communicate with any other nodes. Often combined with `tor` service. -* **monitor**: Internal service to monitor all the other nodes. Currently, you can have zero or one `monitor` nodes. +* **monitor**: Internal service to monitor all the other nodes. Currently, you can have zero or one `monitor` service defined. It is required that the monitor be on the webapp node. It was not designed to be run as a separate node service. * **tor**: Sets up a tor exit node, unconnected to any other service. * **dns**: Not yet implemented. @@ -52,46 +52,54 @@ What nodes do you need for a provider that offers particular services? <table class="table table-striped"> <tr> -<th>Node Type</th> -<th>VPN Service</th> -<th>Email Service</th> + <th>Node Type</th> + <th>VPN Service</th> + <th>Email Service</th> + <th>Notes</th> </tr> <tr> -<td>webapp</td> -<td>required</td> -<td>required</td> + <td>webapp</td> + <td>required</td> + <td>required</td> + <td></td> </tr> <tr> -<td>couchdb</td> -<td>required</td> -<td>required</td> + <td>couchdb</td> + <td>required</td> + <td>required</td> +<td></td> </tr> <tr> -<td>soledad</td> -<td>not used</td> -<td>required</td> + <td>soledad</td> + <td>not used</td> + <td>required</td> +<td></td> </tr> <tr> -<td>mx</td> -<td>not used</td> -<td>required</td> + <td>mx</td> + <td>not used</td> + <td>required</td> + <td></td> </tr> <tr> -<td>openvpn</td> -<td>required</td> -<td>not used</td> + <td>openvpn</td> + <td>required</td> + <td>not used</td> + <td></td> </tr> <tr> -<td>monitor</td> -<td>optional</td> -<td>optional</td> + <td>monitor</td> + <td>optional</td> + <td>optional</td> + <td>This service must be on the webapp node</td> </tr> <tr> -<td>tor</td> -<td>optional</td> -<td>optional</td> + <td>tor</td> + <td>optional</td> + <td>optional</td> + <td></td> </tr> -<table> +</table> Locations ================================ @@ -154,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: @@ -164,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). |