diff --git a/website/source/docs/guides/consul-aws.html.md b/website/source/docs/guides/consul-aws.html.md new file mode 100644 index 0000000000..974afda938 --- /dev/null +++ b/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. diff --git a/website/source/docs/guides/index.html.md b/website/source/docs/guides/index.html.md index 9eb97b4660..152a7b5d50 100644 --- a/website/source/docs/guides/index.html.md +++ b/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. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index ebf9dd222f..670f49f7a4 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -405,6 +405,9 @@ > Consul Template + > + Consul-AWS + > Creating Certificates