From 52bdbdade9212149e94b9cde9ecb10233f2d92d0 Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Fri, 6 Feb 2015 16:34:07 -0800 Subject: [PATCH] website: Adding Atlas docs --- .../source/docs/agent/basics.html.markdown | 6 ++ website/source/docs/faq.html.markdown | 12 ++++ .../source/docs/guides/atlas.html.markdown | 59 +++++++++++++++++++ .../source/docs/guides/index.html.markdown | 2 + website/source/layouts/docs.erb | 6 +- 5 files changed, 84 insertions(+), 1 deletion(-) create mode 100644 website/source/docs/guides/atlas.html.markdown diff --git a/website/source/docs/agent/basics.html.markdown b/website/source/docs/agent/basics.html.markdown index 3aff65da9..d520b5533 100644 --- a/website/source/docs/agent/basics.html.markdown +++ b/website/source/docs/agent/basics.html.markdown @@ -39,6 +39,7 @@ $ consul agent -data-dir=/tmp/consul Server: false (bootstrap: false) Client Addr: 127.0.0.1 (HTTP: 8500, DNS: 8600, RPC: 8400) Cluster Addr: 192.168.1.43 (LAN: 8301, WAN: 8302) + Atlas: (Infrastructure: 'hashicorp/test' Join: true) ==> Log data will now stream in as it occurs: @@ -75,6 +76,11 @@ There are several important messages that `consul agent` outputs: Consul agents in a cluster. Not all Consul agents in a cluster have to use the same port, but this address **MUST** be reachable by all other nodes. +* **Atlas**: This shows the [Atlas infrastructure](https://atlas.hashicorp.com) + the node is registered with. It also indicates if auto join is enabled. + The Atlas infrastructure is set using `-atlas` and auto-join is enabled by + setting `-atlas-join`. + ## Stopping an Agent An agent can be stopped in two ways: gracefully or forcefully. To gracefully diff --git a/website/source/docs/faq.html.markdown b/website/source/docs/faq.html.markdown index 56fdd67f5..797ec064a 100644 --- a/website/source/docs/faq.html.markdown +++ b/website/source/docs/faq.html.markdown @@ -28,4 +28,16 @@ and can be disabled. See [`disable_anonymous_signature`](/docs/agent/options.html#disable_anonymous_signature) and [`disable_update_check`](/docs/agent/options.html#disable_update_check). +## Q: How does Atlas integration work? / Does Consul call home? + +Consul makes use of a HashiCorp service called [SCADA](http://scada.hashicorp.com) +which stands for Supervisory Control And Data Acquisition. The SCADA system allows +clients to maintain a long-running connection to Atlas which is used to make requests +to Consul agents for features like the dashboard and auto joining. Standard ACLs can +be applied to the SCADA connection, which has no enhanced or elevated privileges. +Using the SCADA service is optional and only enabled by opt-in. + +See [`atlas_infrastructure`](/docs/agent/options.html#_atlas) +and [`atlas_acl_token`](/docs/agent/options.html#atlas_acl_token). + diff --git a/website/source/docs/guides/atlas.html.markdown b/website/source/docs/guides/atlas.html.markdown new file mode 100644 index 000000000..86e76cac8 --- /dev/null +++ b/website/source/docs/guides/atlas.html.markdown @@ -0,0 +1,59 @@ +--- +layout: "docs" +page_title: "Atlas Integration" +sidebar_current: "docs-guides-atlas" +description: |- + This guide covers how to integrate Atlas with Consul to provide features like an infrastructure dashboard and automatic cluster joining. +--- + +# Atlas Integration + +[Atlas](https://atlas.hashicorp.com) is service provided by HashiCorp to deploy applications and manage infrastructure. +Starting with Consul 0.5, it is possible to integrate Consul with Atlas. This is done by registering a node as part +of an Atlas infrastructure (specified with the `-atlas` flag). Consul maintains a long running connection to the +[SCADA](http://scada.hashicorp.com) service which allows Atlas to retrieve data and control nodes. + +Data acquisition allows Atlas to display the state of the Consul cluster in its dashboard as well as enabling +alerts to be setup using health checks. Remote control enables Atlas to provide features like the auto joinining +nodes. + +## Enabling Atlas Integration + +To enable Atlas integration, you must specify the name of the Atlas infrastructure and the Atlas authentication +token. The Atlas infrastructure name can be set either with the `-atlas` CLI flag, or with the `atlas_infrastructure` +[configuration option](/docs/agent/options.html). The Atlas token is set with the `-atlas-token` CLI flag, `atlas_token` +configuration option, or `ATLAS_TOKEN` environment variable. + +To verify the integration, either run the agent with `debug` level logging or use `consul monitor -log-level=debug` +and look for a line like: + + [DEBUG] scada-client: assigned session '406ca55d-1801-f964-2942-45f5f9df3995' + +This shows that the Consul agent was successfully able to register with the SCADA service. + +## Using Auto-Join + +Once integrated with Atlas, the auto join feature can be used to have nodes automatically join other +peers in their datacenter. Server nodes will automatically join peer LAN nodes and other WAN nodes. +Client nodes will only join other LAN nodes in their datacenter. + +Auto join is enabled with the `-atlas-join` CLI flag or the `atlas_join` configuration option. + +## Securing Atlas + +The connection to Atlas does not have elevated privileges. API requests made by Atlas +are served in the same way any other HTTP request is made. If ACLs are enabled, it is possible to +force an Atlas ACL token to be used instead of the agent's default token. + +When ACLs are enabled, the `atlas_acl_token` configuration option can be specified. This changes +the ACL token resolution order to be: + +1. Request specific token provided by `?token=`. These tokens are set in the Atlas UI. +2. The `atlas_acl_token` if configured. +3. The `acl_token` if configured. +4. The `anonymous` token. + +Because the `acl_token` typically has elevated permissions compared to the `anonymous` token, +the `atlas_acl_token` can be set to `anonymous` to drop privileges that would otherwise be +inherited from the agent. + diff --git a/website/source/docs/guides/index.html.markdown b/website/source/docs/guides/index.html.markdown index 6e618b048..c1a8f946b 100644 --- a/website/source/docs/guides/index.html.markdown +++ b/website/source/docs/guides/index.html.markdown @@ -14,6 +14,8 @@ guidance to do them safely. The following guides are available: +* [Atlas Integration](/docs/guides/atlas.html) - This guide covers how to integrate [Atlas](https://atlas.hashicorp.com) with Consul. + * [Adding/Removing Servers](/docs/guides/servers.html) - This guide covers how to safely add and remove Consul servers from the cluster. This should be done carefully to avoid availability outages. * [Bootstrapping](/docs/guides/bootstrapping.html) - This guide covers bootstrapping a new datacenter. This covers safely adding the initial Consul servers. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 7b99f15fa..1da41cd05 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -196,7 +196,11 @@ > Guides -