This folder contains a script for configuring and running Consul on an AWS server. This
script has been tested on the following operating systems:
Ubuntu 16.04
Ubuntu 18.04
Ubuntu 20.04
Amazon Linux 2
There is a good chance it will work on other flavors of Debian, CentOS, and RHEL as well.
Quick start
This script assumes you installed it, plus all of its dependencies (including Consul itself), using the install-consul
module. 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
This will:
Generate a Consul configuration file called default.json in the Consul config dir (default: /opt/consul/config).
See Consul configuration for details on what this configuration file will contain and how
to override it with your own configuration.
Generate a systemd configuration file called consul.service in the systemd
config dir (default: /etc/systemd/system) with a command that will run Consul: consul agent -config-dir=/opt/consul/config -data-dir=/opt/consul/data.
Tell systemd to load the new configuration file, thereby starting Consul.
We recommend using the run-consul command as part of User
Data, so that it executes
when the EC2 Instance is first booting. After runing run-consul on that initial boot, the systemd configuration
will automatically restart Consul if it crashes or the EC2 instance reboots.
Note that systemd logs to its own journal by default. To view the Consul logs, run journalctl -u consul.service. To change
the log output location, you can specify the StandardOutput and StandardError options by using the --systemd-stdout and --systemd-stderr
options. See the systemd.exec man pages for available
options, but note that the file:path option requires systemd version >= 236, which is not provided
in the base Ubuntu 16.04/18.04/20.04 and Amazon Linux 2 images.
The run-consul script accepts the following arguments:
server (optional): If set, run in server mode. Exactly one of --server or --client must be set.
client (optional): If set, run in client mode. Exactly one of --server or --client must be set.
cluster-tag-key (optional): Automatically form a cluster with Instances that have this tag key and the tag value
in --cluster-tag-value.
cluster-tag-value (optional): Automatically form a cluster with Instances that have the tag key in
--cluster-tag-key and this tag value.
datacenter (optional): The name of the datacenter the cluster reports. Default is the AWS region name.
config-dir (optional): 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 (optional): The path to the Consul config folder. Default is to take the absolute path of ../data,
relative to the run-consul script itself.
systemd-stdout (optional): The StandardOutput option of the systemd unit. If not specified, it will use systemd's default (journal).
systemd-stderr (optional): The StandardError option of the systemd unit. If not specified, it will use systemd's default (inherit).
user (optional): The user to run Consul as. Default is to use the owner of config-dir.
enable-gossip-encryption (optional): Enable encryption of gossip traffic between nodes. If set, you must also specify gossip-encryption-key.
gossip-encryption-key (optional): The key to use for encrypting gossip traffic. Must be specified with enable-gossip-encryption.
enable-rpc-encryption (optional): Enable encryption of RPC traffic between nodes. Must also specify ca-file-path, cert-file-path and key-file-path.
ca-file-path (optional): Path to the CA file used to verify outgoing connections. Must be specified with enable-rpc-encryption, cert-file-path and key-file-path.
cert-file-path (optional): Path to the certificate file used to verify incoming connections. Must be specified with enable-rpc-encryption, ca-file-path, and key-file-path.
key-file-path (optional): Path to the certificate key used to verify incoming connections. Must be specified with enable-rpc-encryption, ca-file-path and cert-file-path.
skip-consul-config (optional): 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.
run-consul generates a configuration file for Consul called default.json that tries to figure out reasonable
defaults for a Consul cluster in AWS. Check out the Consul Configuration Files
documentation for what configuration settings are
available.
Default configuration
run-consul sets the following configuration values by default:
If there is a aws:autoscaling:groupName tag, that means this EC2 Instance is part of an Auto Scaling Group
(ASG), so set this config to the desired capacity of the ASG (fetched via the describe-auto-scaling-groups
API).
Otherwise, log a warning, and set this to 1. This fallback is not recommended!
client_addr: Set to 0.0.0.0 so you can access the client
and UI endpoint on each EC2 Instance from the outside.
datacenter: Set to the current AWS region (e.g.
us-east-1), as fetched from Metadata.
If the --datacenter flag is provided, then that value is used instead.
tag_key: Set to the value of the --cluster-tag-key
argument.
tag_value: Set to the value this EC2 Instance has for
the tag_key. If the key is not set, then the retry_join_ec2 setting will NOT be included in the config file.
region: Set to the current AWS region (e.g. us-east-1),
as fetched from Metadata.
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, so that
settings in files that come later in the alphabet will override the earlier ones.
For example, to override the default retry_join_ec2 settings, you could create a file called tags.json with the
contents:
If you want to override all the default settings, you can tell run-consul not to generate a default config file
at all using the --skip-consul-config flag:
Consul can encrypt all of its network traffic (see the encryption docs for
details), but by default, encryption is not enabled in this
Module. To enable encryption, you need to do the following:
To enable Gossip encryption, you need to provide a 16-byte, Base64-encoded encryption key, which you can generate using
the consul keygen command offline. You can pass the
--enable-gossip-encryption and --gossip-encryption-key parameters to run-consul to have this script automatically
generate the gossip encryption settings in default.json in the Consul config dir.
Alternatively, you can put the key in a Consul configuration file (e.g. encryption.json) in the Consul
config dir (default location: /opt/consul/config):
{
"encrypt": "cg8StVXbQJ0gPvMd9o7yrg=="
}
RPC encryption: provide TLS certificates
To enable RPC encryption, you need to provide the paths to the CA and signing keys. Since you're already using Terraform,
it's probably easiest to use the TLS Provider to generate your
own certificates. You can find a good working example in the private-tls-cert module
within the terraform-aws-vault repo. You can pass the --enable-rpc-encryption,
--ca-file-path, --cert-file-path, and --key-file-path parameters to run-consul to have this script automatically
generate the RPC encryption settings in default.json in the Consul config dir. Please note that this does not set
"verify_server_hostname": true. Check the documentation of the verify_server_hostname field
to understand the implications of this.
Alternatively, you can specify these paths in a Consul configuration file (e.g. encryption.json) in the Consul config
dir (default location: /opt/consul/config):
Autopilot 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
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
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.
Questions? Ask away.
We're here to talk about our services, answer any questions, give advice, or just to chat.
{"treedata":{"name":"root","toggled":true,"children":[{"name":".circleci","children":[{"name":"config.yml","path":".circleci/config.yml","sha":"06f140f324996ecec28b18d6e52142789006ab89"}]},{"name":".gitignore","path":".gitignore","sha":"c749affedc4dee4e84093bef93f6ba0ebdaaf306"},{"name":".pre-commit-config.yaml","path":".pre-commit-config.yaml","sha":"81355c81b991ffeeb1224a07bfb86f0fa592b6cd"},{"name":"CODEOWNERS","path":"CODEOWNERS","sha":"4be01a6334d39aa5bf6abe6baae701f5e2a8c5ac"},{"name":"CONTRIBUTING.md","path":"CONTRIBUTING.md","sha":"bdfb309d7ff6bb05ffc1ea9453604805c022d13b"},{"name":"LICENSE","path":"LICENSE","sha":"7a4a3ea2424c09fbe48d455aed1eaa94d9124835"},{"name":"NOTICE","path":"NOTICE","sha":"2655cb5943994ab8de6faec5e5afc28ce4ec10c7"},{"name":"README.md","path":"README.md","sha":"d2cbf5451f176c46b432261675b3afc5b03ee8a7"},{"name":"_ci","children":[{"name":"publish-amis-in-new-account.md","path":"_ci/publish-amis-in-new-account.md","sha":"5b5daa55c3e36c1c4739471be92ccb53995f9783"},{"name":"publish-amis.sh","path":"_ci/publish-amis.sh","sha":"a2554844ab0693d24edd3f0439073458070350fc"}]},{"name":"_docs","children":[{"name":"architecture.png","path":"_docs/architecture.png","sha":"539fece6e8a9fd7a56245e2b63e6640a1e0591ef"},{"name":"consul-ui-screenshot.png","path":"_docs/consul-ui-screenshot.png","sha":"622c7e70d3ab805b1bb8e27e474ff8243d4bc994"},{"name":"package-managers.md","path":"_docs/package-managers.md","sha":"f382b6997245e03adba61c02346519a70ee016d4"}]},{"name":"examples","children":[{"name":"README.md","path":"examples/README.md","sha":"8eca7399ca356c90a307206147362bc35588179c"},{"name":"consul-ami","children":[{"name":"README.md","path":"examples/consul-ami/README.md","sha":"da69b57110946044c33581e84436940e31e5d159"},{"name":"consul.json","path":"examples/consul-ami/consul.json","sha":"88c2af9e8e4c313f512af2f72a184871250021d0"}]},{"name":"consul-examples-helper","children":[{"name":"README.md","path":"examples/consul-examples-helper/README.md","sha":"296f6878fd49edb27d6a6b62fa4119b6a407ba26"},{"name":"consul-examples-helper.sh","path":"examples/consul-examples-helper/consul-examples-helper.sh","sha":"cb356cf348574378bbecbf49b3d6bf0339606cbe"}]},{"name":"example-with-custom-asg-role","children":[{"name":"README.md","path":"examples/example-with-custom-asg-role/README.md","sha":"fa1fbb9d7416fa96f13afb6b82664bbe1638ea3f"},{"name":"main.tf","path":"examples/example-with-custom-asg-role/main.tf","sha":"c0fcf7631ff6b439363f80c3709691bf9c9d4383"},{"name":"outputs.tf","path":"examples/example-with-custom-asg-role/outputs.tf","sha":"493b36c2b62ad81a4d1d4eb62e268442206eeded"},{"name":"user-data-client.sh","path":"examples/example-with-custom-asg-role/user-data-client.sh","sha":"fd0158b0287de6bf2a6956718c7aa802076fe489"},{"name":"user-data-server.sh","path":"examples/example-with-custom-asg-role/user-data-server.sh","sha":"c78ebc05584513fa04f44d44ef2b9d17c98e2ea6"},{"name":"variables.tf","path":"examples/example-with-custom-asg-role/variables.tf","sha":"387fac5d0223a2466e0f671d055f8255058b3050"}]},{"name":"example-with-encryption","children":[{"name":"README.md","path":"examples/example-with-encryption/README.md","sha":"0f2de7374cf63ee0b18cae4b960b85ec88403866"},{"name":"main.tf","path":"examples/example-with-encryption/main.tf","sha":"bfc7f675ab5ba84c20001d715dec5ab224826e9f"},{"name":"outputs.tf","path":"examples/example-with-encryption/outputs.tf","sha":"493b36c2b62ad81a4d1d4eb62e268442206eeded"},{"name":"packer","children":[{"name":"README.md","path":"examples/example-with-encryption/packer/README.md","sha":"b7b8ca11120c5f69565dab81eeeed659223538e9"},{"name":"ca.crt.pem","path":"examples/example-with-encryption/packer/ca.crt.pem","sha":"c41779f19be6d742d10be51d80c29aa5d41a660c"},{"name":"consul-with-certs.json","path":"examples/example-with-encryption/packer/consul-with-certs.json","sha":"9942398f7b76dc1589394efb1348d9a727389a7a"},{"name":"consul.crt.pem","path":"examples/example-with-encryption/packer/consul.crt.pem","sha":"4a4ea11b89006f41fe2cb8b707d62463bb739184"},{"name":"consul.key.pem","path":"examples/example-with-encryption/packer/consul.key.pem","sha":"b7de428c63382b087007a236602797cc0a0a45f5"}]},{"name":"user-data-client.sh","path":"examples/example-with-encryption/user-data-client.sh","sha":"2ab3735d96777ce9324bc55f7be29c338ef0c1bb"},{"name":"user-data-server.sh","path":"examples/example-with-encryption/user-data-server.sh","sha":"5e97fc02da696b348ee26a2c1803bf7e3e018c79"},{"name":"variables.tf","path":"examples/example-with-encryption/variables.tf","sha":"9187e8892ddb952fd8adf217071d310d1c644967"}]},{"name":"root-example","children":[{"name":"README.md","path":"examples/root-example/README.md","sha":"6c562cb22c28cc5e35b5a21a94b66d6af9101081"},{"name":"user-data-client.sh","path":"examples/root-example/user-data-client.sh","sha":"fd0158b0287de6bf2a6956718c7aa802076fe489"},{"name":"user-data-server.sh","path":"examples/root-example/user-data-server.sh","sha":"c78ebc05584513fa04f44d44ef2b9d17c98e2ea6"}]}]},{"name":"main.tf","path":"main.tf","sha":"19daa7655b66775c23378dcb4382e92f05f86a34"},{"name":"modules","children":[{"name":"README.md","path":"modules/README.md","sha":"8eca7399ca356c90a307206147362bc35588179c"},{"name":"consul-client-security-group-rules","children":[{"name":"README.md","path":"modules/consul-client-security-group-rules/README.md","sha":"777b679a73df3d5c96fb584176e91449c3a72615"},{"name":"main.tf","path":"modules/consul-client-security-group-rules/main.tf","sha":"6ae3118188ae5c7806cc2ac88cc5a1ac3e50edd1"},{"name":"variables.tf","path":"modules/consul-client-security-group-rules/variables.tf","sha":"c9c25d00fdc683748570ba5e2ee718c9af8e6697"}]},{"name":"consul-cluster","children":[{"name":"README.md","path":"modules/consul-cluster/README.md","sha":"b9a3c55973ef27b0022f5eda05840f7cc65cea03"},{"name":"main.tf","path":"modules/consul-cluster/main.tf","sha":"721f6fc0c5bf9efed37d582c767b772893424a7f"},{"name":"outputs.tf","path":"modules/consul-cluster/outputs.tf","sha":"a980d658e1be410a013a7e7febcc38a49899ffdc"},{"name":"variables.tf","path":"modules/consul-cluster/variables.tf","sha":"6830617eb65853e5c8e9a6ce27f6bb49a546aa34"}]},{"name":"consul-iam-policies","children":[{"name":"README.md","path":"modules/consul-iam-policies/README.md","sha":"7725295fbdbf3d2fe881796e63074e3215854f5f"},{"name":"main.tf","path":"modules/consul-iam-policies/main.tf","sha":"803883bcb9ce412710c9e7d59873bf734c2067c2"},{"name":"variables.tf","path":"modules/consul-iam-policies/variables.tf","sha":"1bda7959f19ea4ab20108ec9fb8802036bfd22fd"}]},{"name":"consul-security-group-rules","children":[{"name":"README.md","path":"modules/consul-security-group-rules/README.md","sha":"315155181f5b42ff0fc6f16b86eaa930811366fe"},{"name":"main.tf","path":"modules/consul-security-group-rules/main.tf","sha":"c9081bfa75ebc080a68346fd104dcea22f0a89be"},{"name":"variables.tf","path":"modules/consul-security-group-rules/variables.tf","sha":"90e1bec3a64824c9416088e46cae9d7ffcc45638"}]},{"name":"install-consul","children":[{"name":"README.md","path":"modules/install-consul/README.md","sha":"26c636fc061fc894c41c792d28428f0266056e86"},{"name":"install-consul","path":"modules/install-consul/install-consul","sha":"f33c659cbb0dc5ab7d5846e7ece811481d42792e"}]},{"name":"install-dnsmasq","children":[{"name":"README.md","path":"modules/install-dnsmasq/README.md","sha":"dbfcd308061679992e9afc3c11264b8140cfe04c"},{"name":"install-dnsmasq","path":"modules/install-dnsmasq/install-dnsmasq","sha":"6ff5256cf38477fe3693c93056a37b96fcb37b16"}]},{"name":"run-consul","children":[{"name":"README.md","path":"modules/run-consul/README.md","sha":"b5e8ec01a3de18d23095cfdf943e4243a74a32d3","toggled":true},{"name":"run-consul","path":"modules/run-consul/run-consul","sha":"ffb5dece503f333949b73553e27039cc7caa1f99"}],"toggled":true},{"name":"setup-systemd-resolved","children":[{"name":"README.md","path":"modules/setup-systemd-resolved/README.md","sha":"c71225757127230251fa0774fe608eac9102ea09"},{"name":"setup-systemd-resolved","path":"modules/setup-systemd-resolved/setup-systemd-resolved","sha":"28670839d4c362281407b394303b6ab6162d7ebf"}]}],"toggled":true},{"name":"outputs.tf","path":"outputs.tf","sha":"493b36c2b62ad81a4d1d4eb62e268442206eeded"},{"name":"test","children":[{"name":"README.md","path":"test/README.md","sha":"874818e6da7a9c0c9338edde0c27fa3f8a3b3d05"},{"name":"aws_helpers.go","path":"test/aws_helpers.go","sha":"a340f3a3779fb5efd7c9410f3e72734f9ad4a324"},{"name":"consul_cluster_test.go","path":"test/consul_cluster_test.go","sha":"b44bd7d665b26d7d672f3c557b5eaa3a8fd59df2"},{"name":"consul_cluster_with_custom_asg_role_test.go","path":"test/consul_cluster_with_custom_asg_role_test.go","sha":"9ae0ef139943ab35a8d419e6dac36a3a63a3851e"},{"name":"consul_cluster_with_encryption_test.go","path":"test/consul_cluster_with_encryption_test.go","sha":"7d5b18e14addba8ea16423bcf7efae7019bad66b"},{"name":"consul_enterprise_test.go","path":"test/consul_enterprise_test.go","sha":"8ef7e432973510e89f3dc5207856e1211c208b1f"},{"name":"consul_helpers.go","path":"test/consul_helpers.go","sha":"153811288dee25b13c3e15b73d740e18dadfe8db"},{"name":"go.mod","path":"test/go.mod","sha":"6a500c12e474d5afd9a4a6a958895cca0ba80281"},{"name":"go.sum","path":"test/go.sum","sha":"061b1735dfb194fc921bb33058c4ae93af1c3fe8"},{"name":"terratest_helpers.go","path":"test/terratest_helpers.go","sha":"7376d9065d4958533286b82c0a00f86c4f173fce"}]},{"name":"variables.tf","path":"variables.tf","sha":"6e69029d26449d2d967bf43875c681cbcb901200"}]},"detailsContent":"<h1 class=\"preview__body--title\" id=\"consul-run-script\">Consul Run Script</h1><div class=\"preview__body--border\"></div><p>This folder contains a script for configuring and running Consul on an <a href=\"https://aws.amazon.com/\" class=\"preview__body--description--blue\" target=\"_blank\">AWS</a> server. This\nscript has been tested on the following operating systems:</p>\n<ul>\n<li>Ubuntu 16.04</li>\n<li>Ubuntu 18.04</li>\n<li>Ubuntu 20.04</li>\n<li>Amazon Linux 2</li>\n</ul>\n<p>There is a good chance it will work on other flavors of Debian, CentOS, and RHEL as well.</p>\n<h2 class=\"preview__body--subtitle\" id=\"quick-start\">Quick start</h2>\n<p>This script assumes you installed it, plus all of its dependencies (including Consul itself), using the <a href=\"/repos/v0.11.0/terraform-aws-consul/modules/install-consul\" class=\"preview__body--description--blue\">install-consul\nmodule</a>. The default install path is <code>/opt/consul/bin</code>, so to start Consul in server mode,\nyou run:</p>\n<pre>/opt/consul/bin/<span class=\"hljs-built_in\">run</span>-consul <span class=\"hljs-comment\">--server</span>\n</pre>\n<p>To start Consul in client mode, you run:</p>\n<pre>/opt/consul/bin/<span class=\"hljs-built_in\">run</span>-consul <span class=\"hljs-comment\">--client</span>\n</pre>\n<p>This will:</p>\n<ol>\n<li>\n<p>Generate a Consul configuration file called <code>default.json</code> in the Consul config dir (default: <code>/opt/consul/config</code>).\nSee <a href=\"#consul-configuration\" class=\"preview__body--description--blue\">Consul configuration</a> for details on what this configuration file will contain and how\nto override it with your own configuration.</p>\n</li>\n<li>\n<p>Generate a <a href=\"https://www.freedesktop.org/wiki/Software/systemd/\" class=\"preview__body--description--blue\" target=\"_blank\">systemd</a> configuration file called <code>consul.service</code> in the systemd\nconfig dir (default: <code>/etc/systemd/system</code>) with a command that will run Consul:<br>\n<code>consul agent -config-dir=/opt/consul/config -data-dir=/opt/consul/data</code>.</p>\n</li>\n<li>\n<p>Tell systemd to load the new configuration file, thereby starting Consul.</p>\n</li>\n</ol>\n<p>We recommend using the <code>run-consul</code> command as part of <a href=\"http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html#user-data-shell-scripts\" class=\"preview__body--description--blue\" target=\"_blank\">User\nData</a>, so that it executes\nwhen the EC2 Instance is first booting. After runing <code>run-consul</code> on that initial boot, the <code>systemd</code> configuration\nwill automatically restart Consul if it crashes or the EC2 instance reboots.</p>\n<p>Note that <code>systemd</code> logs to its own journal by default. To view the Consul logs, run <code>journalctl -u consul.service</code>. To change\nthe log output location, you can specify the <code>StandardOutput</code> and <code>StandardError</code> options by using the <code>--systemd-stdout</code> and <code>--systemd-stderr</code>\noptions. See the <a href=\"https://www.freedesktop.org/software/systemd/man/systemd.exec.html#StandardOutput=\" class=\"preview__body--description--blue\" target=\"_blank\"><code>systemd.exec</code> man pages</a> for available\noptions, but note that the <code>file:path</code> option requires <a href=\"https://stackoverflow.com/a/48052152\" class=\"preview__body--description--blue\" target=\"_blank\">systemd version >= 236</a>, which is not provided\nin the base Ubuntu 16.04/18.04/20.04 and Amazon Linux 2 images.</p>\n<p>See the <a href=\"/repos/v0.11.0/terraform-aws-consul/examples/root-example\" class=\"preview__body--description--blue\">consul-cluster example</a> for fully-working sample code.</p>\n<h2 class=\"preview__body--subtitle\" id=\"command-line-arguments\">Command line Arguments</h2>\n<p>The <code>run-consul</code> script accepts the following arguments:</p>\n<ul>\n<li><code>server</code> (optional): If set, run in server mode. Exactly one of <code>--server</code> or <code>--client</code> must be set.</li>\n<li><code>client</code> (optional): If set, run in client mode. Exactly one of <code>--server</code> or <code>--client</code> must be set.</li>\n<li><code>cluster-tag-key</code> (optional): Automatically form a cluster with Instances that have this tag key and the tag value\nin <code>--cluster-tag-value</code>.</li>\n<li><code>cluster-tag-value</code> (optional): Automatically form a cluster with Instances that have the tag key in\n<code>--cluster-tag-key</code> and this tag value.</li>\n<li><code>datacenter</code> (optional): The name of the datacenter the cluster reports. Default is the AWS region name.</li>\n<li><code>config-dir</code> (optional): The path to the Consul config folder. Default is to take the absolute path of <code>../config</code>,\nrelative to the <code>run-consul</code> script itself.</li>\n<li><code>data-dir</code> (optional): The path to the Consul config folder. Default is to take the absolute path of <code>../data</code>,\nrelative to the <code>run-consul</code> script itself.</li>\n<li><code>systemd-stdout</code> (optional): The StandardOutput option of the systemd unit. If not specified, it will use systemd's default (journal).</li>\n<li><code>systemd-stderr</code> (optional): The StandardError option of the systemd unit. If not specified, it will use systemd's default (inherit).</li>\n<li><code>user</code> (optional): The user to run Consul as. Default is to use the owner of <code>config-dir</code>.</li>\n<li><code>enable-gossip-encryption</code> (optional): Enable encryption of gossip traffic between nodes. If set, you must also specify <code>gossip-encryption-key</code>.</li>\n<li><code>gossip-encryption-key</code> (optional): The key to use for encrypting gossip traffic. Must be specified with <code>enable-gossip-encryption</code>.</li>\n<li><code>enable-rpc-encryption</code> (optional): Enable encryption of RPC traffic between nodes. Must also specify <code>ca-file-path</code>, <code>cert-file-path</code> and <code>key-file-path</code>.</li>\n<li><code>ca-file-path</code> (optional): Path to the CA file used to verify outgoing connections. Must be specified with <code>enable-rpc-encryption</code>, <code>cert-file-path</code> and <code>key-file-path</code>.</li>\n<li><code>cert-file-path</code> (optional): Path to the certificate file used to verify incoming connections. Must be specified with <code>enable-rpc-encryption</code>, <code>ca-file-path</code>, and <code>key-file-path</code>.</li>\n<li><code>key-file-path</code> (optional): Path to the certificate key used to verify incoming connections. Must be specified with <code>enable-rpc-encryption</code>, <code>ca-file-path</code> and <code>cert-file-path</code>.</li>\n<li><code>skip-consul-config</code> (optional): If this flag is set, don't generate a Consul configuration file. This is useful if\nyou have a custom configuration file and don't want to use any of of the default settings from <code>run-consul</code>.</li>\n</ul>\n<p>Options for Consul Autopilot:</p>\n<ul>\n<li><code>--autopilot-cleanup-dead-servers</code> (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.</li>\n<li><code>--autopilot-last-contact-threshold</code> (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.</li>\n<li><code>--autopilot-max-trailing-logs</code> (optional): Controls the maximum number of log entries that a server can trail the leader by before being considered unhealthy. Defaults to 250.</li>\n<li><code>--autopilot-server-stabilization-time</code> (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.</li>\n<li><code>--autopilot-redundancy-zone-tag</code> (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.</li>\n<li><code>--autopilot-disable-upgrade-migration</code> (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.</li>\n<li><code>--autopilot-upgrade-version-tag</code> (optional)(enterprise-only): That tag to be used to override the version information used during a migration.</li>\n</ul>\n<p>Example:</p>\n<pre>/opt/consul/bin/<span class=\"hljs-keyword\">run</span>-consul --server --<span class=\"hljs-keyword\">cluster</span>-tag-key consul-<span class=\"hljs-keyword\">cluster</span> --<span class=\"hljs-keyword\">cluster</span>-tag-value prod-<span class=\"hljs-keyword\">cluster</span>\n</pre>\n<h2 class=\"preview__body--subtitle\" id=\"consul-configuration\">Consul configuration</h2>\n<p><code>run-consul</code> generates a configuration file for Consul called <code>default.json</code> that tries to figure out reasonable\ndefaults for a Consul cluster in AWS. Check out the <a href=\"https://www.consul.io/docs/agent/options.html#configuration-files\" class=\"preview__body--description--blue\" target=\"_blank\">Consul Configuration Files\ndocumentation</a> for what configuration settings are\navailable.</p>\n<h3 class=\"preview__body--subtitle\" id=\"default-configuration\">Default configuration</h3>\n<p><code>run-consul</code> sets the following configuration values by default:</p>\n<ul>\n<li>\n<p><a href=\"https://www.consul.io/docs/agent/options.html#advertise_addr\" class=\"preview__body--description--blue\" target=\"_blank\">advertise_addr</a>: Set to the EC2 Instance's private IP\naddress, as fetched from <a href=\"http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html\" class=\"preview__body--description--blue\" target=\"_blank\">Metadata</a>.</p>\n</li>\n<li>\n<p><a href=\"https://www.consul.io/docs/agent/options.html#bind_addr\" class=\"preview__body--description--blue\" target=\"_blank\">bind_addr</a>: Set to the EC2 Instance's private IP address,\nas fetched from <a href=\"http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html\" class=\"preview__body--description--blue\" target=\"_blank\">Metadata</a>.</p>\n</li>\n<li>\n<p><a href=\"https://www.consul.io/docs/agent/options.html#bootstrap_expect\" class=\"preview__body--description--blue\" target=\"_blank\">bootstrap_expect</a>: If <code>--server</code> is set,\nset this config based on the EC2 Instance's tags (using the\n<a href=\"https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-tags.html\" class=\"preview__body--description--blue\" target=\"_blank\">describe-tags API</a>):</p>\n<ul>\n<li>If there is a <code>aws:autoscaling:groupName</code> tag, that means this EC2 Instance is part of an Auto Scaling Group\n(ASG), so set this config to the desired capacity of the ASG (fetched via the <a href=\"https://docs.aws.amazon.com/cli/latest/reference/autoscaling/describe-auto-scaling-groups.html\" class=\"preview__body--description--blue\" target=\"_blank\">describe-auto-scaling-groups\nAPI</a>).</li>\n<li>Otherwise, log a warning, and set this to 1. This fallback is not recommended!</li>\n</ul>\n</li>\n<li>\n<p><a href=\"https://www.consul.io/docs/agent/options.html#client_addr\" class=\"preview__body--description--blue\" target=\"_blank\">client_addr</a>: Set to 0.0.0.0 so you can access the client\nand UI endpoint on each EC2 Instance from the outside.</p>\n</li>\n<li>\n<p><a href=\"https://www.consul.io/docs/agent/options.html#datacenter\" class=\"preview__body--description--blue\" target=\"_blank\">datacenter</a>: Set to the current AWS region (e.g.\n<code>us-east-1</code>), as fetched from <a href=\"http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html\" class=\"preview__body--description--blue\" target=\"_blank\">Metadata</a>.\nIf the <code>--datacenter</code> flag is provided, then that value is used instead.</p>\n</li>\n<li>\n<p><a href=\"https://www.consul.io/docs/agent/options.html#node_name\" class=\"preview__body--description--blue\" target=\"_blank\">node_name</a>: Set to the instance id, as fetched from\n<a href=\"http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html\" class=\"preview__body--description--blue\" target=\"_blank\">Metadata</a>.</p>\n</li>\n<li>\n<p><a href=\"https://www.consul.io/docs/agent/options.html#retry_join_ec2\" class=\"preview__body--description--blue\" target=\"_blank\">retry_join_ec2</a>: Look up the EC2 Instances tags\n(using the <a href=\"https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-tags.html\" class=\"preview__body--description--blue\" target=\"_blank\">describe-tags API</a>) and set the\nfollowing keys for this setting:</p>\n<ul>\n<li><a href=\"https://www.consul.io/docs/agent/options.html#tag_key\" class=\"preview__body--description--blue\" target=\"_blank\">tag_key</a>: Set to the value of the <code>--cluster-tag-key</code>\nargument.</li>\n<li><a href=\"https://www.consul.io/docs/agent/options.html#tag_value\" class=\"preview__body--description--blue\" target=\"_blank\">tag_value</a>: Set to the value this EC2 Instance has for\nthe <code>tag_key</code>. If the key is not set, then the <code>retry_join_ec2</code> setting will NOT be included in the config file.</li>\n<li><a href=\"https://www.consul.io/docs/agent/options.html#region\" class=\"preview__body--description--blue\" target=\"_blank\">region</a>: Set to the current AWS region (e.g. <code>us-east-1</code>),\nas fetched from <a href=\"http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html\" class=\"preview__body--description--blue\" target=\"_blank\">Metadata</a>.</li>\n</ul>\n</li>\n<li>\n<p><a href=\"https://www.consul.io/docs/agent/options.html#server\" class=\"preview__body--description--blue\" target=\"_blank\">server</a>: Set to true if <code>--server</code> is set.</p>\n</li>\n<li>\n<p><a href=\"https://www.consul.io/docs/agent/options.html#ui\" class=\"preview__body--description--blue\" target=\"_blank\">ui</a>: Set to true.</p>\n</li>\n</ul>\n<h3 class=\"preview__body--subtitle\" id=\"overriding-the-configuration\">Overriding the configuration</h3>\n<p>To override the default configuration, simply put your own configuration file in the Consul config folder (default:\n<code>/opt/consul/config</code>), but with a name that comes later in the alphabet than <code>default.json</code> (e.g.\n<code>my-custom-config.json</code>). Consul will load all the <code>.json</code> configuration files in the config dir and\n<a href=\"https://www.consul.io/docs/agent/options.html#_config_dir\" class=\"preview__body--description--blue\" target=\"_blank\">merge them together in alphabetical order</a>, so that\nsettings in files that come later in the alphabet will override the earlier ones.</p>\n<p>For example, to override the default <code>retry_join_ec2</code> settings, you could create a file called <code>tags.json</code> with the\ncontents:</p>\n<pre>{\n <span class=\"hljs-attr\">\"retry_join_ec2\"</span>: {\n <span class=\"hljs-attr\">\"tag_key\"</span>: <span class=\"hljs-string\">\"custom-key\"</span>,\n <span class=\"hljs-attr\">\"tag_value\"</span>: <span class=\"hljs-string\">\"custom-value\"</span>,\n <span class=\"hljs-attr\">\"region\"</span>: <span class=\"hljs-string\">\"us-west-1\"</span>\n }\n}\n</pre>\n<p>If you want to override <em>all</em> the default settings, you can tell <code>run-consul</code> not to generate a default config file\nat all using the <code>--skip-consul-config</code> flag:</p>\n<pre><span class=\"hljs-string\">/opt/consul/bin/run-consul</span> <span class=\"hljs-params\">--server</span> <span class=\"hljs-params\">--skip-consul-config</span>\n</pre>\n<h3 class=\"preview__body--subtitle\" id=\"required-permissions\">Required permissions</h3>\n<p>The <code>run-consul</code> script assumes it is running on an EC2 Instance with an <a href=\"http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html\" class=\"preview__body--description--blue\" target=\"_blank\">IAM\nRole</a> that has the following permissions:</p>\n<ul>\n<li><code>ec2:DescribeInstances</code></li>\n<li><code>ec2:DescribeTags</code></li>\n<li><code>autoscaling:DescribeAutoScalingGroups</code></li>\n</ul>\n<p>These permissions are automatically added by the <a href=\"/repos/v0.11.0/terraform-aws-consul/modules/consul-cluster\" class=\"preview__body--description--blue\">consul-cluster module</a>.</p>\n<h2 class=\"preview__body--subtitle\" id=\"how-do-you-handle-encryption\">How do you handle encryption?</h2>\n<p>Consul can encrypt all of its network traffic (see the <a href=\"https://www.consul.io/docs/agent/encryption.html\" class=\"preview__body--description--blue\" target=\"_blank\">encryption docs for\ndetails</a>), but by default, encryption is not enabled in this\nModule. To enable encryption, you need to do the following:</p>\n<ol>\n<li><a href=\"#gossip-encryption-provide-an-encryption-key\" class=\"preview__body--description--blue\">Gossip encryption: provide an encryption key</a></li>\n<li><a href=\"#rpc-encryption-provide-tls-certificates\" class=\"preview__body--description--blue\">RPC encryption: provide TLS certificates</a></li>\n</ol>\n<h3 class=\"preview__body--subtitle\" id=\"gossip-encryption-provide-an-encryption-key\">Gossip encryption: provide an encryption key</h3>\n<p>To enable Gossip encryption, you need to provide a 16-byte, Base64-encoded encryption key, which you can generate using\nthe <a href=\"https://www.consul.io/docs/commands/keygen.html\" class=\"preview__body--description--blue\" target=\"_blank\">consul keygen command</a> offline. You can pass the\n<code>--enable-gossip-encryption</code> and <code>--gossip-encryption-key</code> parameters to <code>run-consul</code> to have this script automatically\ngenerate the gossip encryption settings in <code>default.json</code> in the Consul config dir.</p>\n<p>Alternatively, you can put the key in a Consul configuration file (e.g. <code>encryption.json</code>) in the Consul\nconfig dir (default location: <code>/opt/consul/config</code>):</p>\n<pre>{\n <span class=\"hljs-attr\">\"encrypt\"</span>: <span class=\"hljs-string\">\"cg8StVXbQJ0gPvMd9o7yrg==\"</span>\n}\n</pre>\n<h3 class=\"preview__body--subtitle\" id=\"rpc-encryption-provide-tls-certificates\">RPC encryption: provide TLS certificates</h3>\n<p>To enable RPC encryption, you need to provide the paths to the CA and signing keys. Since you're already using Terraform,\nit's probably easiest to use the <a href=\"https://www.terraform.io/docs/providers/tls/index.html\" class=\"preview__body--description--blue\" target=\"_blank\">TLS Provider</a> to generate your\nown certificates. You can find a good working example in the <a href=\"/repos/terraform-aws-vault/modules/private-tls-cert\" class=\"preview__body--description--blue\">private-tls-cert module</a>\nwithin the <a href=\"/repos/terraform-aws-vault\" class=\"preview__body--description--blue\">terraform-aws-vault repo</a>. You can pass the <code>--enable-rpc-encryption</code>,\n<code>--ca-file-path</code>, <code>--cert-file-path</code>, and <code>--key-file-path</code> parameters to <code>run-consul</code> to have this script automatically\ngenerate the RPC encryption settings in <code>default.json</code> in the Consul config dir. Please note that this <strong>does not</strong> set\n<code>"verify_server_hostname": true</code>. Check the documentation of the <a href=\"https://www.consul.io/docs/agent/options.html#verify_server_hostname\" class=\"preview__body--description--blue\" target=\"_blank\">verify_server_hostname field</a>\nto understand the implications of this.</p>\n<p>Alternatively, you can specify these paths in a Consul configuration file (e.g. <code>encryption.json</code>) in the Consul config\ndir (default location: <code>/opt/consul/config</code>):</p>\n<pre>{\n <span class=\"hljs-attr\">\"ca_file\"</span>: <span class=\"hljs-string\">\"/opt/consul/tls/certs/ca-bundle.crt\"</span>,\n <span class=\"hljs-attr\">\"cert_file\"</span>: <span class=\"hljs-string\">\"/opt/consul/tls/certs/my.crt\"</span>,\n <span class=\"hljs-attr\">\"key_file\"</span>: <span class=\"hljs-string\">\"/opt/consul/tls/private/my.key\"</span>\n}\n</pre>\n<p>You will also want to set the <a href=\"https://www.consul.io/docs/agent/options.html#verify_incoming\" class=\"preview__body--description--blue\" target=\"_blank\">verify_incoming</a> and\n<a href=\"https://www.consul.io/docs/agent/options.html#verify_outgoing\" class=\"preview__body--description--blue\" target=\"_blank\">verify_outgoing</a> settings to verify TLS certs on\nincoming and outgoing connections, respectively:</p>\n<pre>{\n <span class=\"hljs-attr\">\"ca_file\"</span>: <span class=\"hljs-string\">\"/opt/consul/tls/certs/ca-bundle.crt\"</span>,\n <span class=\"hljs-attr\">\"cert_file\"</span>: <span class=\"hljs-string\">\"/opt/consul/tls/certs/my.crt\"</span>,\n <span class=\"hljs-attr\">\"key_file\"</span>: <span class=\"hljs-string\">\"/opt/consul/tls/private/my.key\"</span>,\n <span class=\"hljs-attr\">\"verify_incoming\"</span>: <span class=\"hljs-literal\">true</span>,\n <span class=\"hljs-attr\">\"verify_outgoing\"</span>: <span class=\"hljs-literal\">true</span>\n}\n</pre>\n<h3 class=\"preview__body--subtitle\" id=\"autopilot\">Autopilot</h3>\n<p><a href=\"https://www.consul.io/docs/guides/autopilot.html\" class=\"preview__body--description--blue\" target=\"_blank\">Autopilot</a> is a set of features for the\nautomatic management of consul servers. These features are enabled by default and already\nset with reasonable defaults. It includes automatic cleaning up of dead servers as soon as\na replacement Consul server comes online. The internal health check runs on the leader to\ntrack other servers. A server is considered healthy when:</p>\n<ul>\n<li>Its status is <code>Alive</code></li>\n<li>The time since its last contact with the current leader is below <code>autopilot-last-contact-threshold</code></li>\n<li>Its latest <a href=\"https://raft.github.io/\" class=\"preview__body--description--blue\" target=\"_blank\">Raft consensus algorithm</a> term matches the leader's term</li>\n<li>The number of Raft log entries it trails the leader by does not exceed <code>autopilot-max-trailing-logs</code></li>\n</ul>\n<p>There are Autopilot settings called <a href=\"https://www.consul.io/docs/guides/autopilot.html#upgrade-migrations\" class=\"preview__body--description--blue\" target=\"_blank\">upgrade migrations</a>\nthat are useful when adding new members to the cluster either with newer configurations or using\nnewer versions of Consul. These configurations manage how Consul will promote new servers and demote\nold ones. These settings, however, are only available at the Consul Enterprise version.</p>\n","repoName":"terraform-aws-consul","repoRef":"v0.11.0","serviceDescriptor":{"serviceName":"HashiCorp Consul","serviceRepoName":"terraform-aws-consul","serviceRepoOrg":"hashicorp","cloudProviders":["aws"],"description":"Deploy a Consul cluster. Supports automatic bootstrapping, DNS, Consul UI, and auto healing.","imageUrl":"consul.png","licenseType":"open-source","technologies":["Terraform","Bash"],"compliance":[],"tags":[""]},"serviceCategoryName":"Service Mesh","fileName":"README.md","filePath":"/modules/run-consul","title":"Repo Browser: HashiCorp Consul","description":"Browse the repos in the Gruntwork Infrastructure as Code Library."}