website: add consul-aws guide from @i0rek (#5023)
* website: add consul-aws guide from @i0rek
This commit is contained in:
Jack Pearkes
Hans Hasselberg
parent
741e8647a2
commit
c8965c840d
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
|
|||
Loading…
Reference in New Issue