website: add consul-aws guide from @i0rek (#5023)

* website: add consul-aws guide from @i0rek

website/source/docs/guides/consul-aws.html.md

@@ -0,0 +1,88 @@
+---
+layout: "docs"
+page_title: "Consul-AWS"
+sidebar_current: "docs-guides-consul-aws"
+description: |-
+  Consul-AWS provides a tool, which syncs Consul's and AWS Cloud Map's service catalog
+---
+
+# consul-aws
+
+[Consul-AWS](https://github.com/hashicorp/consul-aws/) syncs the services in an AWS Cloud Map namespace to a Consul datacenter. Consul services will be created in AWS Cloud Map and the other way around. This enables native service discovery across Consul and AWS Cloud Map.
+This guide will describe how to configure and how to start the sync.
+
+## Authentication
+
+`consul-aws` needs access to Consul and AWS for uni- and bidirectional sync.
+
+For Consul, the process accepts both the standard CLI flags, `-token` and the environment variables `CONSUL_HTTP_TOKEN`. This should be set to a Consul ACL token if ACLs are enabled.
+
+For AWS, `consul-aws` uses the default credential provider chain to find AWS credentials. The default provider chain looks for credentials in the following order:
+1. Environment variables.
+2. Shared credentials file.
+3. If your application is running on an Amazon EC2 instance, IAM role for Amazon EC2.
+
+## Configuration
+
+There are two subcommands available on `consul-aws`:
+
+* version: display version number
+* sync-catalog: start syncing the catalogs
+
+The version subcommand doesn’t do anything besides showing the version, so lets focus on sync-catalog. The following flags are available:
+
+* A set of parameters to connect to your Consul Cluster like `-http-addr`, `-token`, `-ca-file`, `-client-cert`, and everything else you might need in order to do that
+* `-aws-namespace-id`: The AWS namespace to sync with Consul services.
+* `-aws-service-prefix`: A prefix to prepend to all services written to AWS from Consul. If this is not set then services will have no prefix.
+* `-consul-service-prefix`: A prefix to prepend to all services written to Consul from AWS. If this is not set then services will have no prefix.
+* `-to-aws`: If true, Consul services will be synced to AWS (defaults to false).
+* `-to-consul`: If true, AWS services will be synced to Consul (defaults to false).
+* `-aws-pull-interval`: The interval between fetching from AWS Cloud Map. Accepts a sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "10s", "1.5m" (defaults to 30s).
+* `-aws-dns-ttl`: DNS TTL for services created in AWS Cloud Map in seconds (defaults to 60).
+
+Independent of how you want to use `consul-aws` it needs to be able to connect to Consul and AWS. Apart from making sure you setup up authenticated access, `-aws-namespace-id` is mandatory.
+
+## Syncing Consul services to AWS Cloud Map
+
+Assuming authenticated access is set up, there is little left to do before starting the sync. Using `-to-aws` command line flag will start the sync to AWS Cloud Map. If `-aws-service-prefix` is provided, every imported service from Consul will be prefixed. For example:
+
+```shell
+$ consul-aws -aws-namespace-id ns-hjrgt3bapp7phzff -to-aws -consul-service-prefix consul_
+```
+
+At this point `consul-aws` will start importing services into AWS Cloud Map. A service in Consul named `web` will end up becoming `consul_web` in AWS. The individual service instances from Consul will be created in AWS as well.
+
+Services in AWS Cloud Map that were imported from Consul have the following properties:
+
+* Description:  “Imported from Consul”
+* Record types: A and SRV
+* DNS routing policy: Multivalue answer routing
+
+## Syncing AWS Cloud Map services to Consul
+
+Similar to the previous chapter, there are two relevant flags: `-to-consul` to turn on the sync and optionally `-consul-service-prefix` to prefix every service imported into Consul. For example:
+
+```shell
+$ consul-aws -aws-namespace-id ns-hjrgt3bapp7phzff -to-consul -aws-service-prefix aws_
+```
+
+At this point `consul-aws` will start importing services into Consul. A service in AWS named `redis` will end up becoming `aws_redis` in Consul. The individual service instances from AWS will be created in Consul as well.
+
+* Services in Consul that were imported from AWS Cloud Map have the following properties:
+* Tag: aws
+* Meta-Data: has aws as the source set, as well as the aws-id, the aws-namespace and every custom attribute the instance had in AWS Cloud Map
+* Node: the node name is consul-aws
+
+## Syncing both directions
+
+To enable bidirectional sync only put together the previous two sections and provide `-to-consul` and `-to-aws` as well as optionally `-aws-service-prefix` and `-consul-service-prefix`:
+
+```shell
+$ consul-aws -aws-namespace-id ns-hjrgt3bapp7phzff -to-consul -aws-service-prefix aws_ -to-aws -consul-service-prefix consul_
+```
+
+At this point `consul-aws` will start importing services into Consul from AWS Cloud Map and from AWS Cloud Map to Consul.
+
+## Summary
+
+At this point, either uni- or bidirectional sync is set up and service discovery is available across Consul and AWS seamlessly. If you haven’t enabled [ACL](/docs/guides/acl.html), now is a good time to read about it.

website/source/docs/guides/index.html.md

@@ -30,6 +30,8 @@ The following guides are available:
 
 * [Consul Template](/docs/guides/consul-template.html) - This guide covers the Consul template tool, which provides a programmatic method for populating values into the file system.
 
+* [Consul-AWS](/docs/guides/consul-aws.html) - This guide covers the Consul-AWS tool, which syncs Consul's and AWS Cloud Map's service catalog.
+
 * [Creating Certificates](/docs/guides/creating-certificates.html) - This guide describes how to setup CA and certificates to secure a Consul cluster with TLS.
 
 * [Deployment Guide](/docs/guides/deployment-guide.html) - This deployment guide covers the steps required to install and configure a single HashiCorp Consul cluster as defined in the Consul Reference Architecture.

website/source/layouts/docs.erb

@@ -405,6 +405,9 @@
           <li<%= sidebar_current("docs-guides-consul-template") %>>
             <a href="/docs/guides/consul-template.html">Consul Template</a>
           </li>
+          <li<%= sidebar_current("docs-guides-consul-aws") %>>
+            <a href="/docs/guides/consul-aws.html">Consul-AWS</a>
+          </li>
           <li<%= sidebar_current("docs-guides-creating-certificates") %>>
             <a href="/docs/guides/creating-certificates.html">Creating Certificates</a>
           </li>