How to use this Module

This repo has the following folder structure:

• modules: This folder contains several standalone, reusable, production-grade modules that you can use to deploy Consul.
• examples: This folder shows examples of different ways to combine the modules in the modules folder to deploy Consul.
• test: Automated tests for the modules and examples.
• root folder: The root folder is an example of how to use the consul-cluster module module to deploy a Consul cluster in AWS. The Terraform Registry requires the root of every repo to contain Terraform code, so we've put one of the examples there. This example is great for learning and experimenting, but for production use, please use the underlying modules in the modules folder directly.

To deploy Consul servers for production using this repo:

1. Create a Consul AMI using a Packer template that references the install-consul module. Here is an example Packer template.

   If you are just experimenting with this Module, you may find it more convenient to use one of our official public AMIs:

   • Latest Ubuntu 16 AMIs.
   • Latest Amazon Linux 2 AMIs.

   WARNING! Do NOT use these AMIs in your production setup. In production, you should build your own AMIs in your own AWS account.

2. Deploy that AMI across an Auto Scaling Group using the Terraform consul-cluster module and execute the run-consul script with the --server flag during boot on each Instance in the Auto Scaling Group to form the Consul cluster. Here is an example Terraform configuration to provision a Consul cluster.

To deploy Consul clients for production using this repo:

1. Use the install-consul module to install Consul alongside your application code.
2. Before booting your app, execute the run-consul script with --client flag.
3. Your app can now use the local Consul agent for service discovery and key/value storage.
4. Optionally, you can use the install-dnsmasq module for Ubuntu 16.04 and Amazon Linux 2 or setup-systemd-resolved for Ubuntu 18.04 to configure Consul as the DNS for a specific domain (e.g. .consul) so that URLs such as foo.service.consul resolve automatically to the IP address(es) for a service foo registered in Consul (all other domain names will be continue to resolve using the default resolver on the OS).