website: Adding Atlas docs

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

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).
+
 

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.
+

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.

website/source/layouts/docs.erb

@@ -197,6 +197,10 @@
 				<li<%= sidebar_current("docs-guides") %>>
 				<a href="/docs/guides/index.html">Guides</a>
                 <ul class="nav">
+					<li<%= sidebar_current("docs-guides-atlas") %>>
+					<a href="/docs/guides/atlas.html">Atlas Integration</a>
+					</li>
+
 					<li<%= sidebar_current("docs-guides-servers") %>>
 					<a href="/docs/guides/servers.html">Adding/Removing Servers</a>
 					</li>