Skip to content
This repository has been archived by the owner on Jan 25, 2023. It is now read-only.

Commit

Permalink
Merge pull request #36 from hashicorp/autopilot
Browse files Browse the repository at this point in the history 
Allow overriding auto-pilot configuration
  • Loading branch information
@Etiene
Etiene authored Dec 21, 2018
2 parents 235b6ae + 8b1d3f7 commit af17bd3
Show file tree
Hide file tree
Showing 2 changed files with 149 additions and 38 deletions.
100 changes: 63 additions & 37 deletions modules/run-consul/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Consul Run Script

This folder contains a script for configuring and running Consul on a [GCP](https://cloud.google.com/) Compute Instance.
This folder contains a script for configuring and running Consul on a [GCP](https://cloud.google.com/) Compute Instance.
This script has been tested on the following operating systems:

* Ubuntu 16.04
Expand All @@ -12,16 +12,16 @@ There is a good chance it will work on other flavors of Debian as well.

## Quick start

This script assumes you installed it, plus all of its dependencies (including Consul itself), using the [install-consul
module](https://github.com/hashicorp/terraform-google-consul/tree/master/modules/install-consul). The default install path is `/opt/consul/bin`, so to start Consul in server mode,
This script assumes you installed it, plus all of its dependencies (including Consul itself), using the [install-consul
module](https://github.com/hashicorp/terraform-google-consul/tree/master/modules/install-consul). The default install path is `/opt/consul/bin`, so to start Consul in server mode,
you run:

```
/opt/consul/bin/run-consul --server
```

To start Consul in client mode, you run:

```
/opt/consul/bin/run-consul --client
```
Expand All @@ -31,7 +31,7 @@ This will:
1. Generate a Consul configuration file called `default.json` in the Consul config dir (default: `/opt/consul/config`).
See [Consul configuration](#consul-configuration) for details on what this configuration file will contain and how
to override it with your own configuration.

1. Generate a [Supervisor](http://supervisord.org/) configuration file called `run-consul.conf` in the Supervisor
config dir (default: `/etc/supervisor/conf.d`) with a command that will run Consul:
`consul agent -config-dir=/opt/consul/config -data-dir=/opt/consul/data`.
Expand All @@ -57,60 +57,71 @@ The `run-consul` script accepts the following arguments:
* `client` If set, run in client mode. Exactly one of `--server` or `--client` must be set.

**Optional:**

* `cluster-tag-name` Automatically form a cluster with Instances that have the same value for this Compute Instance tag
name.
* `raft-protocol` This controls the internal version of the Raft consensus protocol used for server communications. Must
be set to 3 in order to gain access to Autopilot features, with the exception of `cleanup_dead_servers`. Default is 3.
* `config-dir` The path to the Consul config folder. Default is to take the absolute path of `../config`,
* `config-dir` The path to the Consul config folder. Default is to take the absolute path of `../config`,
relative to the `run-consul` script itself.
* `data-dir` The path to the Consul config folder. Default is to take the absolute path of `../data`,
* `data-dir` The path to the Consul config folder. Default is to take the absolute path of `../data`,
relative to the `run-consul` script itself.
* `log-dir` The path to the Consul log folder. Default is the absolute path of '../log', relative to this script.
* `bin-dir` The path to the folder with Consul binary. Default is the absolute path of the parent folder of this script."
* `user` The user to run Consul as. Default is to use the owner of `config-dir`.
* `skip-consul-config` If this flag is set, don't generate a Consul configuration file. This is useful if
you have a custom configuration file and don't want to use any of of the default settings from `run-consul`.
* `skip-consul-config` If this flag is set, don't generate a Consul configuration file. This is useful if
you have a custom configuration file and don't want to use any of of the default settings from `run-consul`.

Options for Consul Autopilot:

* `--autopilot-cleanup-dead-servers` (optional): Set to true or false to control the automatic removal of dead server nodes periodically and whenever a new server is added to the cluster. Defaults to true.
* `--autopilot-last-contact-threshold` (optional): Controls the maximum amount of time a server can go without contact from the leader before being considered unhealthy. Must be a duration value such as 10s. Defaults to 200ms.
* `--autopilot-max-trailing-logs` (optional): Controls the maximum number of log entries that a server can trail the leader by before being considered unhealthy. Defaults to 250.
* `--autopilot-server-stabilization-time` (optional): Controls the minimum amount of time a server must be stable in the 'healthy' state before being added to the cluster. Only takes effect if all servers are running Raft protocol version 3 or higher. Must be a duration value such as 30s. Defaults to 10s.
* `--autopilot-redundancy-zone-tag` (optional)(enterprise-only): This controls the -node-meta key to use when Autopilot is separating servers into zones for redundancy. Only one server in each zone can be a voting member at one time. If left blank, this feature will be disabled. Defaults to az.
* `--autopilot-disable-upgrade-migration` (optional)(enterprise-only): If this flag is set, this will disable Autopilot's upgrade migration strategy in Consul Enterprise of waiting until enough newer-versioned servers have been added to the cluster before promoting any of them to voters. Defaults to false.
* `--autopilot-upgrade-version-tag` (optional)(enterprise-only): That tag to be used to override the version information used during a migration.


Example:

```
/opt/consul/bin/run-consul --server --cluster-tag-name consul-server-prod
/opt/consul/bin/run-consul --server --cluster-tag-name consul-server-prod
```




## Consul configuration

`run-consul` generates a configuration file for Consul called `default.json` that tries to figure out reasonable
defaults for a Consul cluster in GCP. Check out the [Consul Configuration Files
`run-consul` generates a configuration file for Consul called `default.json` that tries to figure out reasonable
defaults for a Consul cluster in GCP. Check out the [Consul Configuration Files
documentation](https://www.consul.io/docs/agent/options.html#configuration-files) for what configuration settings are
available.


### Default configuration

`run-consul` sets the following configuration values by default:
* [advertise_addr](https://www.consul.io/docs/agent/options.html#advertise_addr): Set to the Compute Instance's private IP

* [advertise_addr](https://www.consul.io/docs/agent/options.html#advertise_addr): Set to the Compute Instance's private IP
address.

* [bind_addr](https://www.consul.io/docs/agent/options.html#bind_addr): Set to the Compute Instance's private IP address.

* [bootstrap_expect](https://www.consul.io/docs/agent/options.html#bootstrap_expect): If `--server` is set,
set this config based on the [Instance Metadata](https://cloud.google.com/compute/docs/storing-retrieving-metadata) tags:
* [bootstrap_expect](https://www.consul.io/docs/agent/options.html#bootstrap_expect): If `--server` is set,
set this config based on the [Instance Metadata](https://cloud.google.com/compute/docs/storing-retrieving-metadata) tags:
* Set this config to the value of the `cluster-size` tag.

* [client_addr](https://www.consul.io/docs/agent/options.html#client_addr): Set to 0.0.0.0 so you can access the client
and UI endpoint on each Compute Instance from the outside.

* [datacenter](https://www.consul.io/docs/agent/options.html#datacenter): Set to the current Instance Region (e.g.
* [datacenter](https://www.consul.io/docs/agent/options.html#datacenter): Set to the current Instance Region (e.g.
`us-west1`), as fetched from [Instance Metadata](https://cloud.google.com/compute/docs/storing-retrieving-metadata).

* [node_name](https://www.consul.io/docs/agent/options.html#node_name): Set to the instance name, as fetched from
[Instance Metadata](https://cloud.google.com/compute/docs/storing-retrieving-metadata).
* [node_name](https://www.consul.io/docs/agent/options.html#node_name): Set to the instance name, as fetched from
[Instance Metadata](https://cloud.google.com/compute/docs/storing-retrieving-metadata).


* [raft-protocol](https://www.consul.io/docs/agent/options.html#raft_protocol) Set to the value of `--raft-protocol`.

Expand All @@ -121,19 +132,19 @@ available.
the Consul Servers are located.
* [tag_value](https://www.consul.io/docs/agent/options.html#tag_value-2): Set to the value of the tag shared by all
Consul Server nodes.

* [server](https://www.consul.io/docs/agent/options.html#server): Set to true if `--server` is set.

* [ui](https://www.consul.io/docs/agent/options.html#ui): Set to true to make the UI available.


### Overriding the configuration

To override the default configuration, simply put your own configuration file in the Consul config folder (default:
`/opt/consul/config`), but with a name that comes later in the alphabet than `default.json` (e.g.
`my-custom-config.json`). Consul will load all the `.json` configuration files in the config dir and
[merge them together in alphabetical order](https://www.consul.io/docs/agent/options.html#_config_dir), so that
settings in files that come later in the alphabet will override the earlier ones.
To override the default configuration, simply put your own configuration file in the Consul config folder (default:
`/opt/consul/config`), but with a name that comes later in the alphabet than `default.json` (e.g.
`my-custom-config.json`). Consul will load all the `.json` configuration files in the config dir and
[merge them together in alphabetical order](https://www.consul.io/docs/agent/options.html#_config_dir), so that
settings in files that come later in the alphabet will override the earlier ones.

For example, to override the default `retry_join` settings, you could create a file called `tags.json` with the
contents:
Expand All @@ -158,16 +169,16 @@ at all using the `--skip-consul-config` flag:

### Required permissions

The `run-consul` script assumes only that the Compute Instance can query its own metadata, a permission enabled by
The `run-consul` script assumes only that the Compute Instance can query its own metadata, a permission enabled by
default on all Compute Instances.




## How do you handle encryption?

Consul can encrypt all of its network traffic (see the [encryption docs for
details](https://www.consul.io/docs/agent/encryption.html)), but by default, encryption is not enabled in this
Consul can encrypt all of its network traffic (see the [encryption docs for
details](https://www.consul.io/docs/agent/encryption.html)), but by default, encryption is not enabled in this
Module. To enable encryption, you need to do the following:

1. [Gossip encryption: provide an encryption key](#gossip-encryption-provide-an-encryption-key)
Expand All @@ -177,7 +188,7 @@ Module. To enable encryption, you need to do the following:
### Gossip encryption: provide an encryption key

To enable Gossip encryption, you need to provide a 16-byte, Base64-encoded encryption key, which you can generate using
the [consul keygen command](https://www.consul.io/docs/commands/keygen.html). You can put the key in a Consul
the [consul keygen command](https://www.consul.io/docs/commands/keygen.html). You can put the key in a Consul
configuration file (e.g. `encryption.json`) in the Consul config dir (default location: `/opt/consul/config`):

```json
Expand All @@ -189,9 +200,9 @@ configuration file (e.g. `encryption.json`) in the Consul config dir (default lo

### RPC encryption: provide TLS certificates

To enable RPC encryption, you need to provide the paths to the CA and signing keys ([here is a tutorial on generating
these keys](http://russellsimpkins.blogspot.com/2015/10/consul-adding-tls-using-self-signed.html)). You can specify
these paths in a Consul configuration file (e.g. `encryption.json`) in the Consul config dir (default location:
To enable RPC encryption, you need to provide the paths to the CA and signing keys ([here is a tutorial on generating
these keys](http://russellsimpkins.blogspot.com/2015/10/consul-adding-tls-using-self-signed.html)). You can specify
these paths in a Consul configuration file (e.g. `encryption.json`) in the Consul config dir (default location:
`/opt/consul/config`):

```json
Expand All @@ -203,7 +214,7 @@ these paths in a Consul configuration file (e.g. `encryption.json`) in the Consu
```

You will also want to set the [verify_incoming](https://www.consul.io/docs/agent/options.html#verify_incoming) and
[verify_outgoing](https://www.consul.io/docs/agent/options.html#verify_outgoing) settings to verify TLS certs on
[verify_outgoing](https://www.consul.io/docs/agent/options.html#verify_outgoing) settings to verify TLS certs on
incoming and outgoing connections, respectively:

```json
Expand All @@ -216,5 +227,20 @@ incoming and outgoing connections, respectively:
}
```

### Autopilot

[Autopilot](https://www.consul.io/docs/guides/autopilot.html) is a set of features for the
automatic management of consul servers. These features are enabled by default and already
set with reasonable defaults. It includes automatic cleaning up of dead servers as soon as
a replacement Consul server comes online. The internal health check runs on the leader to
track other servers. A server is considered healthy when:

* Its status is `Alive`
* The time since its last contact with the current leader is below `autopilot-last-contact-threshold`
* Its latest [Raft consensus algorithm](https://raft.github.io/) term matches the leader's term
* The number of Raft log entries it trails the leader by does not exceed `autopilot-max-trailing-logs`

There are Autopilot settings called [upgrade migrations](https://www.consul.io/docs/guides/autopilot.html#upgrade-migrations)
that are useful when adding new members to the cluster either with newer configurations or using
newer versions of Consul. These configurations manage how Consul will promote new servers and demote
old ones. These settings, however, are only available at the Consul Enterprise version.
Loading

0 comments on commit af17bd3

Please sign in to comment.