From cc7ce233d04172122e4502a4a8e63ce158ad448e Mon Sep 17 00:00:00 2001 From: Hope Ngerebara Date: Mon, 25 Nov 2019 14:28:09 +0100 Subject: [PATCH 1/4] README update for service catalog --- CONTRIBUTING.md | 20 ++++-- README.md | 163 +++++++++++++++++++---------------------------- _docs/consul.png | Bin 0 -> 8583 bytes 3 files changed, 80 insertions(+), 103 deletions(-) create mode 100755 _docs/consul.png diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bdfb309d..f79d33a6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,12 +3,16 @@ Contributions to this Module are very welcome! We follow a fairly standard [pull request process](https://help.github.com/articles/about-pull-requests/) for contributions, subject to the following guidelines: -1. [File a GitHub issue](#file-a-github-issue) -1. [Update the documentation](#update-the-documentation) -1. [Update the tests](#update-the-tests) -1. [Update the code](#update-the-code) -1. [Create a pull request](#create-a-pull-request) -1. [Merge and release](#merge-and-release) +- [Contribution Guidelines](#contribution-guidelines) + - [File a GitHub issue](#file-a-github-issue) + - [Update the documentation](#update-the-documentation) + - [Update the tests](#update-the-tests) + - [Update the code](#update-the-code) + - [Backwards compatibility](#backwards-compatibility) + - [Downtime](#downtime) + - [Create a pull request](#create-a-pull-request) + - [Sign HashiCorp CLA](#sign-hashicorp-cla) + - [Merge and release](#merge-and-release) ## File a GitHub issue @@ -80,6 +84,10 @@ to include the following: test output so we can verify that everything is working. 1. Any notes on backwards incompatibility or downtime. +## Sign HashiCorp CLA + +We require that all contributors sign our Contributor License Agreement ("CLA") before we can accept the contribution. You can read more about HashiCorp's CLA and why we require all contributors to sign it in our [guide to the CLA](https://www.hashicorp.com/cla) + ## Merge and release The maintainers for this repo will review your code and provide feedback. If everything looks good, they will merge the diff --git a/README.md b/README.md index 2f70405c..39568a4d 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,67 @@ -[![Maintained by Gruntwork.io](https://img.shields.io/badge/maintained%20by-gruntwork.io-%235849a6.svg)](https://gruntwork.io/?ref=repo_aws_consul) + + + +# Consul AWS Module + +[![Maintained by Gruntwork.io](https://img.shields.io/badge/maintained%20by-gruntwork.io-%235849a6.svg)](https://gruntwork.io/?ref=repo_terraform_aws_consul) +![Terraform Version](https://img.shields.io/badge/tf-%3E%3D0.12.0-blue.svg) + +This repo contains a Module for running Kubernetes clusters on [AWS](https://aws.amazon.com) using [Elastic Kubernetes Service (EKS)](https://docs.aws.amazon.com/eks/latest/userguide/clusters.html) with [Terraform](https://www.terraform.io). + +![Terraform AWS Consul](https://raw.githubusercontent.com/hashicorp/terraform-aws-consul/master/_docs/architecture.png) + + # Consul AWS Module -This repo contains a set of modules in the [modules folder](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules) for deploying a [Consul](https://www.consul.io/) cluster on -[AWS](https://aws.amazon.com/) using [Terraform](https://www.terraform.io/). Consul is a distributed, highly-available -tool that you can use for service discovery and key/value storage. A Consul cluster typically includes a small number -of server nodes, which are responsible for being part of the [consensus -quorum](https://www.consul.io/docs/internals/consensus.html), and a larger number of client nodes, which you typically -run alongside your apps: -![Consul architecture](https://github.com/hashicorp/terraform-aws-consul/blob/master/_docs/architecture.png?raw=true) +## Features +* Secure service communication and observe communication between your services without modifying their code. +* Automate load balancer. +* Provides any number of health checks. +* MuliData centers out of the box. + + + +## Learn + +This repo is maintained by [Gruntwork](https://www.gruntwork.io), and follows the same patterns as [the Gruntwork Infrastructure as Code Library](https://gruntwork.io/infrastructure-as-code-library/), a collection of reusable, battle-tested, production ready infrastructure code. You can read [How to use the Gruntwork Infrastructure as Code Library](https://gruntwork.io/guides/foundations/how-to-use-gruntwork-infrastructure-as-code-library/) for an overview of how to use modules maintained by Gruntwork! +## Core concepts -## How to use this Module +* Consul Use Cases: overview of various use cases that consul is optimized for. + * [Service Discovery](https://www.consul.io/discovery.html) -This repo has the following folder structure: + * [Service Mesh](https://www.consul.io/mesh.html) -* [modules](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules): This folder contains several standalone, reusable, production-grade modules that you can use to deploy Consul. +* [Consul Guides](https://learn.hashicorp.com/consul?utm_source=consul.io&utm_medium=docs&utm_content=top-nav): official guide on how to use Consul service to discover services and secure network traffic. + +## Repo organization + +* [modules](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules): the main implementation code for this repo, broken down into multiple standalone, orthogonal submodules. * [examples](https://github.com/hashicorp/terraform-aws-consul/tree/master/examples): This folder shows examples of different ways to combine the modules in the `modules` folder to deploy Consul. * [test](https://github.com/hashicorp/terraform-aws-consul/tree/master/test): Automated tests for the modules and examples. -* [root folder](https://github.com/hashicorp/terraform-aws-consul/tree/master): The root folder is *an example* of how to use the [consul-cluster module](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/consul-cluster) - module to deploy a [Consul](https://www.consul.io/) cluster in [AWS](https://aws.amazon.com/). 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](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules) directly. +* [root](https://github.com/hashicorp/terraform-aws-consul/tree/master): The root folder is *an example* of how to use the [consul-cluster module](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/consul-cluster) module to deploy a [Consul](https://www.consul.io/) cluster in [AWS](https://aws.amazon.com/). 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](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules) directly. + + +## Deploy + +### Non-production deployment (quick start for learning) +If you just want to try this repo out for experimenting and learning, check out the following resources: + +* [examples folder](https://github.com/hashicorp/terraform-aws-consul/tree/master/examples): The `examples` folder contains sample code optimized for learning, experimenting, and testing (but not production usage). + +### Production deployment To deploy Consul servers for production using this repo: @@ -28,87 +69,28 @@ To deploy Consul servers for production using this repo: Here is an [example Packer template](https://github.com/hashicorp/terraform-aws-consul/tree/master/examples/consul-ami#quick-start). 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](https://github.com/hashicorp/terraform-aws-consul/tree/master/_docs/ubuntu16-ami-list.md). - - [Latest Amazon Linux 2 AMIs](https://github.com/hashicorp/terraform-aws-consul/tree/master/_docs/amazon-linux-ami-list.md). + - [Latest Ubuntu 16 AMIs](https://github.com/hashicorp/terraform-aws-consul/blob/master/_docs/ubuntu16-ami-list.md). + - [Latest Amazon Linux 2 AMIs](https://github.com/hashicorp/terraform-aws-consul/blob/master/_docs/amazon-linux-ami-list.md). **WARNING! Do NOT use these AMIs in your production setup. In production, you should build your own AMIs in your own AWS account.** -1. Deploy that AMI across an Auto Scaling Group using the Terraform [consul-cluster module](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/consul-cluster) - and execute the [run-consul script](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/run-consul) 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](https://github.com/hashicorp/terraform-aws-consul/tree/master/examples/root-example#quick-start) to provision a Consul cluster. +2. Deploy that AMI across an Auto Scaling Group using the Terraform link:/modules/consul-cluster[consul-cluster module] + and execute the link:/modules/run-consul[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](https://github.com/hashicorp/terraform-aws-consul/tree/master/examples/root-example#quick-start) to provision a Consul cluster. To deploy Consul clients for production using this repo: 1. Use the [install-consul module](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/install-consul) to install Consul alongside your application code. -1. Before booting your app, execute the [run-consul script](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/run-consul) with `--client` flag. -1. Your app can now use the local Consul agent for service discovery and key/value storage. -1. Optionally, you can use the [install-dnsmasq module](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/install-dnsmasq) for Ubuntu 16.04 and Amazon Linux 2 or [setup-systemd-resolved](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/setup-systemd-resolved) for Ubuntu 18.04 to configure Consul as the DNS for a +2. Before booting your app, execute the [run-consul script](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/run-consul) 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](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/install-dnsmasq) for Ubuntu 16.04 and Amazon Linux 2 or [setup-systemd-resolved](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/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). - - - - -## What's a Module? - -A Module is a canonical, reusable, best-practices definition for how to run a single piece of infrastructure, such -as a database or server cluster. Each Module is created using [Terraform](https://www.terraform.io/), and -includes automated tests, examples, and documentation. It is maintained both by the open source community and -companies that provide commercial support. - -Instead of figuring out the details of how to run a piece of infrastructure from scratch, you can reuse -existing code that has been proven in production. And instead of maintaining all that infrastructure code yourself, -you can leverage the work of the Module community to pick up infrastructure improvements through -a version number bump. - - - -## Who maintains this Module? - -This Module is maintained by [Gruntwork](http://www.gruntwork.io/). If you're looking for help or commercial -support, send an email to [modules@gruntwork.io](mailto:modules@gruntwork.io?Subject=Consul%20Module). -Gruntwork can help with: - -* Setup, customization, and support for this Module. -* Modules for other types of infrastructure, such as VPCs, Docker clusters, databases, and continuous integration. -* Modules that meet compliance requirements, such as HIPAA. -* Consulting & Training on AWS, Terraform, and DevOps. - - - -## Code included in this Module: - -* [install-consul](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/install-consul): This module installs Consul using a - [Packer](https://www.packer.io/) template to create a Consul - [Amazon Machine Image (AMI)](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html). - -* [consul-cluster](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/consul-cluster): The module includes Terraform code to deploy a Consul AMI across an [Auto - Scaling Group](https://aws.amazon.com/autoscaling/). - -* [run-consul](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/run-consul): This module includes the scripts to configure and run Consul. It is used - by the above Packer module at build-time to set configurations, and by the Terraform module at runtime - with [User Data](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html#user-data-shell-scripts) - to create the cluster. - -* [install-dnsmasq module](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/install-dnsmasq): Install [Dnsmasq](http://www.thekelleys.org.uk/dnsmasq/doc.html) - for Ubuntu 16.04 and Amazon Linux 2 and configure it to forward requests for a specific domain to Consul. This allows you to use Consul as a DNS server - for URLs such as `foo.service.consul`. - -* [setup-systemd-resolved module](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/setup-systemd-resolved): Setup [systemd-resolved](https://www.freedesktop.org/software/systemd/man/resolved.conf.html) - for ubuntu 18.04 and configure it to forward requests for a specific domain to Consul. This allows you to use Consul as a DNS server - for URLs such as `foo.service.consul`. - -* [consul-iam-policies](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/consul-iam-policies): Defines the IAM policies necessary for a Consul cluster. - -* [consul-security-group-rules](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/consul-security-group-rules): Defines the security group rules used by a - Consul cluster to control the traffic that is allowed to go in and out of the cluster. - -* [consul-client-security-group-rules](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/consul-client-security-group-rules): Defines the security group rules - used by a Consul agent to control the traffic that is allowed to go in and out. +## Support +If you need help with this repo or anything else related to infrastructure or DevOps, Gruntwork offers [Commercial Support](https://gruntwork.io/support/) via Slack, email, and phone/video. If you're already a Gruntwork customer, hop on Slack and ask away! If not, [subscribe now](https://www.gruntwork.io/pricing/). If you're not sure, feel free to email us at [support@gruntwork.io](mailto:support@gruntwork.io). ## How do I contribute to this Module? @@ -116,21 +98,8 @@ Gruntwork can help with: Contributions are very welcome! Check out the [Contribution Guidelines](https://github.com/hashicorp/terraform-aws-consul/tree/master/CONTRIBUTING.md) for instructions. - -## How is this Module versioned? - -This Module follows the principles of [Semantic Versioning](http://semver.org/). You can find each new release, -along with the changelog, in the [Releases Page](../../releases). - -During initial development, the major version will be 0 (e.g., `0.x.y`), which indicates the code does not yet have a -stable API. Once we hit `1.0.0`, we will make every effort to maintain a backwards compatible API and use the MAJOR, -MINOR, and PATCH versions on each release to indicate any incompatibilities. - - - ## License -This code is released under the Apache 2.0 License. Please see [LICENSE](https://github.com/hashicorp/terraform-aws-consul/tree/master/LICENSE) and [NOTICE](https://github.com/hashicorp/terraform-aws-consul/tree/master/NOTICE) for more -details. +Please see [LICENSE](LICENSE) for details on how the code in this repo is licensed. -Copyright © 2017 Gruntwork, Inc. +Copyright © 2019 Gruntwork, Inc. \ No newline at end of file diff --git a/_docs/consul.png b/_docs/consul.png new file mode 100755 index 0000000000000000000000000000000000000000..82fc387cbf3a0490536804c780a5f47d6cc99335 GIT binary patch literal 8583 zcmY*<1ymf(w)Nl=ECiQ8a0za~-5F$XhhV{NaQ6`0WrBpDgS$&`cemi~?mWJG?|=XI zdadfJ+I4E5+P$i}Pp#^3WkqRpR3cOW0DvwlBLRBLp>K&D8S(8tEG|;=mcd(y0!0CU z%9wXg#t3h9auXR45CHI`0Ra4i0f2`$$bSz2aA5@i4vYW*zEl7J-{EJIioja~ii3={ zGXU`J!#@cIkp7bZ0D#f9RMP@$0TuX6>}{EiP3^y$F}vG3yjcSP0`7coMO!nlF}b^~ zjh!=}yCB8CEco8a|G+F1Hby|r1%B~JMgivxVgD8yKykvJ6W)>@$&Mru(GqTvopO}FgbhJfsNgn?3^k8P4fSE zB+Q&moGcx{miBh!|L_`rwRZsvQc(Qk=)c#$#|gGH|Noxsoc|;1O(4rZEi7!ztStZK ze(Ngm56Y+HWNG&1`5%5EHi3Ux{vYf=egs(lasIys^KYg9Lf@ncp$f44_pu3~Ds<9n z0{~>HvJ#?d?l8w0NU3U)b$v>=S6e@g5K%bdadEJeC6ra*yPyrH;k*LVN;tQTy}Ktw zb7nJR1s7VB%{x9#dtD6?4b~zsaL9645}jDVgfwHUjRlVxhAwjs1^cq>K}VfwjXtNP zx-L+=nRdktD4+V=wq|@ZwkYzpD_6*s`doyYX5KU|j{Hcd{$xe1nm5<=24gYq`2!UN zhXDm>qdOskPGx}}dxcUwrwY`aL9o&-ZUfTux;ychuhldSlHc^XU2)4RDN$f<+`_iB zu}Lh*^3{pv-67z;nKyw@cRaZ9jb;k!N<|WUGU~(qV2`gY|fQzD0js zT-4!xJgVLh7n?qE4{CJCQ1eTpy?%$**?!rKM$jVxs9&xn3iP2AEF8(*9H>At{*#m+#+DRRsd6szwo$M@L3-J`ocU4HE)3 zF@=#BYsm_M02f&kkEleS7M;PrI`l4M+Xw+gY5a6@%VE?EXt<^Zej*|i9#L27HbD!> zDXUQN45b5u75dt8yEt}jDmMHbnMn_6*}(zv?u1M%I?SvGXPM(?6`9J)Ncb#+7s ze}+$=MDbV*KHsi-mBTPhp8a4fi`~ugGZ1>dQvEcn@3ul6goK$aP3EI!;IWMhbM_9O znG*nK3h>! z4AAB&WeHuZhmj51`#tLN-ftyf$_*?rXFuSwG9yH`x2X&Y>oZDX`cb)@+Nyr({q7aa zz3c0f-w~{btcZ|Hro3UA`#bZ~QtoD1p$lfz`}4hDzSgf7LDMZ&Dsp|F?1khY>^Sw~*wSz4)zHA>n2iG_Vz^!%Q$FFN0`qK_G*oa^me7HVD*UIv_(dIqx{s1)FFS&iTSfApcta|Lq>g#8?w;D7a*DaaujsKFO*sS(@eW~(!bk(l;78edz9|X*@B`mBf z(o9tQ{G#ZZDXi4O@5(5m+GBY9!LLy+G#L4u=b^j4YS5q6Nvo-QnOEeGORB`R3>RMk zzua$S%cJ7kALT6?2bc1BuBrjk%*)K^WLw0@%}Cu5{IirVa@$1~V~+bEL5mEV#~S4a z<~Bu&$ql&p1vyhWXauqYZ2rkgGx1ttN(wRk?V@!#p?=cNb2x1#>j4a)>EWO_3POmm^i-I~{y0it!ExhmCI<*dpFr$D ztPoj7_evAs$qI7M<_=KHJ=>N9x$hhH%xLEAeU~^-DN>7^sMD$3)Hf(|;*i3&`^Ye` z`_Yz9B92ftpWdF4qjgSQc4QW|NUK7}Rk%{B-SK}Fk6v>CaOz6nq$q__#NNp zhqO`5Ie%FF8jG<^rx|t4fgntw@6`ftD@V%DXDd#6D~!xH_H9mzhoTd|eTF!<0nhmm zJM516VojFt@bI|xuCO6hB|++H^AYxr)}3_gtx0(nF3){*o@FC|u=y|nrQ|U(94Qa- zN)oDs0C*XL+fwdh!&M$cQ{^4VWyJ5|6a;>TJ&#n-qy~{5sH4mLi0$R#TGaERz7H^= zer}n-o?PMGI%U6mCg}bXWV%>mDaGUZ@HYiavS(~- zFkijzeE=j6!vQbeoE%Bf<;Zh wE8HLZVIjd@Zb-@Mw*;e=MjpaN$^B|GlTE?-Q7dna8(HBS9U^El=@9R{2T%04x8yg$LM;|zp_xJbnDSKJfEK~~NPd~RI5s^Xu?rowi zFzGkdXk!Pp`gW|x$GauVUdtc$aOm{O$h#EM@rtz!$x++R2Ah-HBIcMM@vZlwjAOY{ z+p{DJmQ( z|8$jqauKIGgrdNdiMFr*-V>W62eeW**YXwFl}xT?;N?vrxdbv8(J9Z}@V>{(t?RQT zWN(j|t|1KL_vP(hPERM|2hy@}Qe?Me zNXO>_-28&LU$Lnd>J{)b^>V@Cii@jmC>pU_s-ZHCpWmO-O7gKPGoomsC8Ub-aUvr8 zA!)dGY{$zbNMZflO(Gmh?H@y=m_P9phCL!I5~?V8t!9$ldHrY7=CUk9R-<-9Ax*?; zV=F$iQ?BT4iU)gw=g%--BQ_k+cSqhr7HpS)zD&($>GhWxxidH}Og^i;Jn5q6kQxL; zR8`{Fv8bt;!iRVAS_rwc5FI?i1o8w+PQQgIQ74ub5l+s|Be{SV%N%9Q!uz|R)U4C~ z1}F-6uV93P72D-jlQ`G7=%z#}|9iV!fkeb1wUbOJ8(M%kJ{Yp7pp}5ckQf*!Or`cT z!Mjs2me$FIr@{AioG@wNAa7V|B0wx>GOhDqAHV%Bq%yWj1iob2Gn3L1hOw9arV;r2 z(uO)%kU#6(*H(6Y+~L>Dv9njGpV!?+4C|;vgLc*Ve6@@HQ2VvT*!ol0MU8KU1!k8L zuAgDCk(!G-#4ANHhP$jZIdP#+*0jFcCtjoQ-5@!ZAwTM$G*)MzvK5MP&cfr)7NJ~1^fU>VRU+Hpu31hJY8o23XxGe&pH|^(yYLFuAtukEo47=y z+GoexWP@|PyJ%zw1$mF-S2bH>O>Wce=(|OKRcKsZ=gXY$`En--ctc#cx%2DbrFC!cVlNPTner#A=x^G0Gg7m`{6`gCPukkrJ36-RBhEvAGi$N$Y9|SV1wF4=Eoy}>i&?*I z6a;pb<5}&bMQ5gRSe{LL*Q+`!q(m2s`RTIIm?UpQWo9UpZ$;PS30DHDjZO1wu%pyDqRg<}PaRN|T75AS|Ri zUSs;Kv6+O6?PkhSG{6`O6)uVEcNA0roYGQ*&i`1+5+qOk;)EbC-AzQ=bx9w_?2cuz zSp0O9N+_^fX-fOWoQoT5YL*RY^!c3og>}C73q+vSv|M`!*0?{)_+~hbqZHpcpW3Lq zQ;v5shL-}H7|!<2fpt3c)18VmsaYpmN$B}I&|-d6g^buJfdi#rMlgJc&7xTONY@&s zZ|t<9@R>`f%Y&PN*MY`1V{8uG13lun99x*1w^e-qH}fCdHVLnXei3^c@4|_HGKI5Q zh8DEfskC|BG0~^i>x@30`O5BpfYrDHZmRkv;+xuNMjQKT6&Z;Rn?Pu0J+#Ml>RJDcc(N{^V}|JbChTJs&TL9Tofgu$D{-9k zMKLLe6Xb9BKDmm`uHZdKi@m-)o&xX2$-p9^!{qtYMRbc25U(qF8`DM$QA%uraJMnRTV#KDcf2$I zOhP`}4WQOz^p2FDOhT#hEYtGBLuGbd65~(90!UwT?c~)}6iyCpX{(=7Rl1yuzfF#t z?K}nKwL)Yg^cu(B*wz_iv1T)wwJ^oTd(DKt(dtL;^|9p>PU}nBmeO-XZ&dtA(h*OA z+#>I9nMhMZw{)tHbB07e7=|lwDq*^_T1CurP^57$k zqJOqfMB$;1A+|qKK5I{MiUE}A1tJS+6;h3;sC(y!17VzINFg2Tkr@I=*>@qSZ3s^? zMpSg??~~;KTKn)m&)0M2*8$r>H6h=#6iINydqO`Kqm+_#Bl(xs)L0A^7mxALnEh5( z`xdBgmjUN+sy%0tRp*IOw=lDf%V(0yCu7Z!0jq#-A>+7;0jFl4H~2RUPriE%jf3ex zm0nN4IgTnzK#eIEr(qBh@IvDRt5R-)gqX|@*&Ve2!rZ)uls0&Hc+fbZ>hojfOP6MF z{fYl8D`4TWFODf_IxGLFHr7T)Y#PAW^V4`w{daK{(Hc+tebhP%K?Z>D`DzMXc|tI5 zFA_Q1UdPE`X@|tpPV~og5ZUd|j8>l^6Tb|X@Ky?#3dBEkO79Pc;8SZm5x7KOZOmg~ zB3I-p&9e<2c@CRi6=sBGHLaHw()lSTN^@Pv$QBea=X7#k6ET(Ng>FDh2nr!!By5^UI8@pkSNsgb~ zKGDFW%yAGw0s4Q?!kgbKS*J_PLU_M!Gp{WC%iG3`++Y}gKYJvDe-1qS?d7lgCOQX$ ze;JUsqn;`Amm_$#b!keo0O%q~FRqGM2&MEKD(3J0tElgK_*WP4+4INIi}`Q&s_8)F zBIJr1*aiXUGj!?1h1hiMlt$i45l|?RnB#oY_;)1s$ZafT8GTNEvccbUT{}F`!MVN9 zZ0USVezj)|5g;34^(`@@dS__%LuMSQ#Y_2Cl#fn5HYn(Q)aYIXyby9fEE0LG)UPp= zFoVH-JT%8oBQVSv9GPreJ=k`kW%-I3RyX)YVgMoT(bf}ndH9I$Op+YTY>LB-R@3^1H;RIQqxlZjsYrbZku!EDjc;OZb`RWcho$vf7eg#OCusH0 zI7TkgnC69IeH4^IlS-#nJRx%tIz#Y~yWk_v`+LLF6qQ$>42k?c+2?dI%ey+695DLy zUYJEcFUzYAc2lu&-Rz=yTFGrMx5yYUH|6LPIV#vj`F+agJnpT@v)SJ$Ik+REkGi*t zeEf`Rw3SZ-3-jhAE6Ewg^M?M43k{B&k&*;nD6Ac0SOoES<6?Y|W_*q#gLc9#QM7gT z$#@MIsV3XMtaJ6Cq8fg+k}x@I>ipBu;F`}`o9yvsPr#J^vv*17#X;#Swndav89{aEhYlx6!w8C1LwS%B>7^oiSDVR8#M-PJmo*DH2}#?@VO{ zX}?6H&Wop|DGQ(M_TkAjIIJ)G>OpUqaLkPU3>J3C(q@=q>NS)rDT}OiV5T z-w1EM_S*DClL9+zl^AS1PUS;xC2nP=@<=T=Ry6WB1U@=q#>6!V+r=&FM!+uZgDb|F zv^)a3kHF6JDU~S4GR9^4O zl4mf~v3Eu(;&z*gd-V_CzecjpM`v(dOe?acLGxnh}o1DM~(3`ZvtlH_{W_e%4#rvKVlFQ6o3dw=e z#l9<;;~{-jB$XAXS#m>ms~ZE7KZ}AyM^}Y6b7GUsyG`E3EPVRDz{nreGi{|A?}G_J zWO%n(OtRH8=6l2OL9hv0>dq7;F<(_{;qK%Ra}rTD#K~mRp@Cd;y8;Fq;-@PLh%u09 z*^AOdUj&O+N0s|)fU zvVlMD)XoRP7d3qjM6Vyfp(ukRBU~1!A@nkPv%2M`$c;TJa;j{GIX+SJj& zUTwL>=!!}DX^NYgB!f}KqzRI7rRTW#R3I(eRYj2mWu(5$sbtWnYlyBmHf^VYgA*WB zD%Gmd$g_s#9@2?g*k>pI?l97l0zMAgV2=pJhm?}@(gCai8+t#!{&m0D8gPm~@WLVY zZS*^By+vE2Cr3P62>a2hkyaWQTXp-_uf0(!=RKKGUID3{#-RJr8fN^GEC72G_r_Dw z%A}|Vinvh+_uSG9#8<7I?M>X*moJ3JGOpOp+w4IjmZqy5V>Id^J9i5PqpEA(?e{jy zYNDs)Sf1`X;pi_Hgi^hirjk21Ba@w+55QibrOd{+N_b3AuE&?!UXmFeM3*1@;YNWK+B+fQmwm(vj}8pq=YfoytaFF**e*+!3l1 zn@^SjawM+Y-+5hVVX(j=os{aotjk+x@4~WFHK|FD>AxL@Rg9i-8?2sIj|p+q+pMo* z$C>wPvO(MSaw5_rb4TAg~*;iQRriC&R=)C;$8o)b@8}KWv z!;sH2N_Me}gdx~o@bM_&mG-y;=0r;(Rey!*AhR#nYZC%r&*8OK;yFO$2ezN9Y0x@C z6+!zyaHo?r4J=RSB`|iTZM}n~7b$+(s>(}N%IlU0cZvAPyfa>uzr#dQEB=u1ks&=P z^{nm`DOHx3JY;@4^+zxnpvRpNM3`-YB`y?efKg^k65PXbFS;8^TBl2K=L7&x!W2bA zLyCEhEYgK8CFsArM&+Z^QAknupJ+3h&Bfa6k1oDs8#>$3Co?_VWE0YC8JXDBs||7PDoqKv1!qOXj%dB(-XMP#(ib1;9FLnn$9dIcgE0L5Uh z7*pWP|11jjCK#O>?2Bfh9MG>y#UxS-$jAPIl1bn!4mM&!xXDCCrR-I_%x@>>VzG<+ zZtS>GKA|&IGI=34;CZ+k?|Q=);E+u+?uzh-*y#eZcdnvZp>E}i=E2T^T4uDOY1^+} zf?Y&ZPOQR9-vL&}fz+?24_GUxtr+y;2@;=vB}^nvFz!T}Rsng694~%p=lZXOyhm>N z9@G;MEG<1eGV>D1?J-)BjPx>LQQBQ4c$s{q^@NQ%iSv;}h8*5TO|>^4gX}U>KquC+vNQEJnzi{@Y+KvkBxi5OyK2^loKg|T?@skB2bLsTP zn9DTxzb{2sP0^&{C!4gLpHZy1HNg)#?MRzOOjurRSWLgp>!JEagPSH)E|U)712Z4(M0${0ia!LeuL{8%U0ao^=O121usmu# zu{E709XRbPDI}Kc7lgj^=|3hP4rmRKqxsUIb9YeyawjB%jI*Rr9XbTqWz#tRkZbpi zH#f`c7GU!-|d zO$cl3(Z$h(!b$Q3R|i_vsK>`{_b3E}2=|}7l}xmw*q9d%F9n}Bx-+m#;Gw5gEY@AS zdDw!Ssu+e}R=_`h?tk(K+glq9NDhz_%0`8*6ucmlNi5xudlz}?34c${>o~~sf;kiA zEdOZLTAm!Z6ZGu`=t2~UV9Mte_-*!+u?gYkLxRu$CqGumIw&0xTC`R} zB>e$O5PRy=%OyJ&Oo_SqNS_(G)=@<{3dgvFk!S9=EAkj%rMd%%xkr1*_b$?E(6CCj zO?u!#z2b;}U_*q{`;5G=j^L@mM_D%Kji_J0J(2&nH0vdzg;n*d^v(2GHl~n~P>`MB z<@kNaU_dln(iNOWx^16`u%X&|F}2G*HK@S4?4Uj={rTD_uZcM9A*%m7M@CM6W)qC& z7-#t4v~#`bvw?aCsNXc={U1+Uc5kyx(g)r`=e1XuDhsn45{2RNe|~q6l~j}{6Eh0@ EAGQHu2><{9 literal 0 HcmV?d00001 From b2e21318940b62982d9693b32122011542cefd9d Mon Sep 17 00:00:00 2001 From: Hope Ngerebara Date: Mon, 25 Nov 2019 14:34:39 +0100 Subject: [PATCH 2/4] fix typo --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 39568a4d..dd3e2964 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ This repo contains a Module for running Kubernetes clusters on [AWS](https://aws * Secure service communication and observe communication between your services without modifying their code. * Automate load balancer. * Provides any number of health checks. -* MuliData centers out of the box. +* Multi-Data centers out of the box. @@ -69,22 +69,22 @@ To deploy Consul servers for production using this repo: Here is an [example Packer template](https://github.com/hashicorp/terraform-aws-consul/tree/master/examples/consul-ami#quick-start). 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](https://github.com/hashicorp/terraform-aws-consul/blob/master/_docs/ubuntu16-ami-list.md). - - [Latest Amazon Linux 2 AMIs](https://github.com/hashicorp/terraform-aws-consul/blob/master/_docs/amazon-linux-ami-list.md). + - [Latest Ubuntu 16 AMIs](https://github.com/hashicorp/terraform-aws-consul/tree/master/_docs/ubuntu16-ami-list.md). + - [Latest Amazon Linux 2 AMIs](https://github.com/hashicorp/terraform-aws-consul/master/_docs/amazon-linux-ami-list.md). **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 link:/modules/consul-cluster[consul-cluster module] +1. Deploy that AMI across an Auto Scaling Group using the Terraform link:/modules/consul-cluster[consul-cluster module] and execute the link:/modules/run-consul[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](https://github.com/hashicorp/terraform-aws-consul/tree/master/examples/root-example#quick-start) to provision a Consul cluster. To deploy Consul clients for production using this repo: 1. Use the [install-consul module](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/install-consul) to install Consul alongside your application code. -2. Before booting your app, execute the [run-consul script](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/run-consul) 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](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/install-dnsmasq) for Ubuntu 16.04 and Amazon Linux 2 or [setup-systemd-resolved](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/setup-systemd-resolved) for Ubuntu 18.04 to configure Consul as the DNS for a +1. Before booting your app, execute the [run-consul script](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/run-consul) with `--client` flag. +1. Your app can now use the local Consul agent for service discovery and key/value storage. +1. Optionally, you can use the [install-dnsmasq module](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/install-dnsmasq) for Ubuntu 16.04 and Amazon Linux 2 or [setup-systemd-resolved](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/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). From 43ddfb31560209106ce9d6184b3beaaadfcbf080 Mon Sep 17 00:00:00 2001 From: Hope Ngerebara Date: Mon, 25 Nov 2019 15:40:24 +0100 Subject: [PATCH 3/4] change adoc links to md links --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index dd3e2964..24696c37 100644 --- a/README.md +++ b/README.md @@ -75,8 +75,8 @@ To deploy Consul servers for production using this repo: **WARNING! Do NOT use these AMIs in your production setup. In production, you should build your own AMIs in your own AWS account.** -1. Deploy that AMI across an Auto Scaling Group using the Terraform link:/modules/consul-cluster[consul-cluster module] - and execute the link:/modules/run-consul[run-consul script] with the `--server` flag during boot on each +1. Deploy that AMI across an Auto Scaling Group using the Terraform [consul-cluster module](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/consul-cluster) + and execute the [run-consul script](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/run-consul) 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](https://github.com/hashicorp/terraform-aws-consul/tree/master/examples/root-example#quick-start) to provision a Consul cluster. To deploy Consul clients for production using this repo: From 5302af17b17d226c655d87f4fb64c172b14457db Mon Sep 17 00:00:00 2001 From: Hope Ngerebara Date: Wed, 4 Dec 2019 12:09:34 +0100 Subject: [PATCH 4/4] remove indentation move consul server and client deployments to core-concepts modify features --- CONTRIBUTING.md | 3 --- README.md | 39 ++++++++++----------------------------- core-concepts.md | 27 +++++++++++++++++++++++++++ 3 files changed, 37 insertions(+), 32 deletions(-) create mode 100644 core-concepts.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f79d33a6..d2a6274d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,13 +3,10 @@ Contributions to this Module are very welcome! We follow a fairly standard [pull request process](https://help.github.com/articles/about-pull-requests/) for contributions, subject to the following guidelines: -- [Contribution Guidelines](#contribution-guidelines) - [File a GitHub issue](#file-a-github-issue) - [Update the documentation](#update-the-documentation) - [Update the tests](#update-the-tests) - [Update the code](#update-the-code) - - [Backwards compatibility](#backwards-compatibility) - - [Downtime](#downtime) - [Create a pull request](#create-a-pull-request) - [Sign HashiCorp CLA](#sign-hashicorp-cla) - [Merge and release](#merge-and-release) diff --git a/README.md b/README.md index 24696c37..cff1da81 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ :category: Service discovery, service mesh :cloud: aws :tags: consul, mesh -:license: gruntwork +:license: open-source :built-with: terraform, bash --> @@ -16,7 +16,7 @@ [![Maintained by Gruntwork.io](https://img.shields.io/badge/maintained%20by-gruntwork.io-%235849a6.svg)](https://gruntwork.io/?ref=repo_terraform_aws_consul) ![Terraform Version](https://img.shields.io/badge/tf-%3E%3D0.12.0-blue.svg) -This repo contains a Module for running Kubernetes clusters on [AWS](https://aws.amazon.com) using [Elastic Kubernetes Service (EKS)](https://docs.aws.amazon.com/eks/latest/userguide/clusters.html) with [Terraform](https://www.terraform.io). +This repo contains a set of modules in the [modules folder](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules) for deploying a [Consul](https://www.consul.io/) cluster on [AWS](https://aws.amazon.com/) using [Terraform](https://www.terraform.io/). Consul is a distributed, highly-available tool that you can use for service discovery and key/value storage. A Consul cluster typically includes a small number of server nodes, which are responsible for being part of the [consensus quorum](https://www.consul.io/docs/internals/consensus.html), and a larger number of client nodes, which you typically run alongside your apps: ![Terraform AWS Consul](https://raw.githubusercontent.com/hashicorp/terraform-aws-consul/master/_docs/architecture.png) @@ -26,10 +26,11 @@ This repo contains a Module for running Kubernetes clusters on [AWS](https://aws ## Features -* Secure service communication and observe communication between your services without modifying their code. -* Automate load balancer. -* Provides any number of health checks. -* Multi-Data centers out of the box. +* Deploy Consul servers and agents +* Automatic bootstrapping +* Auto healing +* Auto DNS configuration +* Consul UI @@ -45,6 +46,7 @@ This repo is maintained by [Gruntwork](https://www.gruntwork.io), and follows th * [Service Mesh](https://www.consul.io/mesh.html) * [Consul Guides](https://learn.hashicorp.com/consul?utm_source=consul.io&utm_medium=docs&utm_content=top-nav): official guide on how to use Consul service to discover services and secure network traffic. +* [Deploy Consul Servers and Clients](core-concepts.md): Learn how to deploy consul servers and clients using this repo. ## Repo organization @@ -62,32 +64,11 @@ If you just want to try this repo out for experimenting and learning, check out * [examples folder](https://github.com/hashicorp/terraform-aws-consul/tree/master/examples): The `examples` folder contains sample code optimized for learning, experimenting, and testing (but not production usage). ### Production deployment +If you want to deploy this repo in production, check out the following resources: -To deploy Consul servers for production using this repo: -1. Create a Consul AMI using a Packer template that references the [install-consul module](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/install-consul). - Here is an [example Packer template](https://github.com/hashicorp/terraform-aws-consul/tree/master/examples/consul-ami#quick-start). - - 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](https://github.com/hashicorp/terraform-aws-consul/tree/master/_docs/ubuntu16-ami-list.md). - - [Latest Amazon Linux 2 AMIs](https://github.com/hashicorp/terraform-aws-consul/master/_docs/amazon-linux-ami-list.md). +[Consul Setup Guide](https://learn.hashicorp.com/consul/datacenter-deploy/deployment-guide) - **WARNING! Do NOT use these AMIs in your production setup. In production, you should build your own AMIs in your own - AWS account.** - -1. Deploy that AMI across an Auto Scaling Group using the Terraform [consul-cluster module](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/consul-cluster) - and execute the [run-consul script](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/run-consul) 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](https://github.com/hashicorp/terraform-aws-consul/tree/master/examples/root-example#quick-start) to provision a Consul cluster. - -To deploy Consul clients for production using this repo: - -1. Use the [install-consul module](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/install-consul) to install Consul alongside your application code. -1. Before booting your app, execute the [run-consul script](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/run-consul) with `--client` flag. -1. Your app can now use the local Consul agent for service discovery and key/value storage. -1. Optionally, you can use the [install-dnsmasq module](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/install-dnsmasq) for Ubuntu 16.04 and Amazon Linux 2 or [setup-systemd-resolved](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/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). ## Support If you need help with this repo or anything else related to infrastructure or DevOps, Gruntwork offers [Commercial Support](https://gruntwork.io/support/) via Slack, email, and phone/video. If you're already a Gruntwork customer, hop on Slack and ask away! If not, [subscribe now](https://www.gruntwork.io/pricing/). If you're not sure, feel free to email us at [support@gruntwork.io](mailto:support@gruntwork.io). diff --git a/core-concepts.md b/core-concepts.md new file mode 100644 index 00000000..d1e23a0d --- /dev/null +++ b/core-concepts.md @@ -0,0 +1,27 @@ + +## To deploy Consul servers for production using this repo: + + +1. Create a Consul AMI using a Packer template that references the [install-consul module](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/install-consul). + Here is an [example Packer template](https://github.com/hashicorp/terraform-aws-consul/tree/master/examples/consul-ami#quick-start). + + 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](https://github.com/hashicorp/terraform-aws-consul/tree/master/_docs/ubuntu16-ami-list.md). + - [Latest Amazon Linux 2 AMIs](https://github.com/hashicorp/terraform-aws-consul/master/_docs/amazon-linux-ami-list.md). + + **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](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/consul-cluster) + and execute the [run-consul script](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/run-consul) 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](https://github.com/hashicorp/terraform-aws-consul/tree/master/examples/root-example#quick-start) to provision a Consul cluster. + +## To deploy Consul clients for production using this repo: + +1. Use the [install-consul module](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/install-consul) to install Consul alongside your application code. +1. Before booting your app, execute the [run-consul script](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/run-consul) with `--client` flag. +1. Your app can now use the local Consul agent for service discovery and key/value storage. +1. Optionally, you can use the [install-dnsmasq module](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/install-dnsmasq) for Ubuntu 16.04 and Amazon Linux 2 or [setup-systemd-resolved](https://github.com/hashicorp/terraform-aws-consul/tree/master/modules/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).