github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

explain how consul and atlas work together

pull/759/head
Kevin Fishner 2015-03-04 16:12:14 -08:00
parent 57a9928d48
commit b4bbbdf6c2
5 changed files with 77 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
website/source/assets/images/atlas_web_ui.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 74 KiB

23
website/source/docs/guides/atlas.html.markdown
View File

@ -8,22 +8,19 @@ description: |-
# Atlas Integration # Atlas Integration
[Atlas](https://atlas.hashicorp.com) is a service provided by HashiCorp to deploy applications and manage infrastructure. [Atlas](https://atlas.hashicorp.com?utm_source=oss&utm_medium=guide-atlas&utm_campaign=consul) is a 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 Starting with Consul 0.5, it is possible to integrate Consul with Atlas. Atlas is able to display the state of the Consul cluster in its dashboard and set up alerts based on health checks. Additionally, nodes can use Atlas to auto-join a Consul cluster without hardcoding any configurations.
of an Atlas infrastructure (specified with the [`-atlas`](/docs/agent/options.html#_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 and set up alerts Atlas is able to securely retrieve data from nodes as Consul maintains a long-running connection to the
based on health checks. Remote control enables Atlas to provide features like auto-joinining nodes. [SCADA](http://scada.hashicorp.com) service.
## Enabling Atlas Integration ## Enabling Atlas Integration
To enable Atlas integration, you must specify the name of the Atlas infrastructure and the Atlas authentication 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`](/docs/agent/options.html#_atlas) token in your Consul configuration. The Atlas infrastructure name can be set either with the [`-atlas` CLI flag](/docs/agent/options.html#_atlas) or with the [`atlas_infrastructure` configuration option](/docs/agent/options.html#atlas_infrastructure). The Atlas token is set with the [`-atlas-token` CLI flag](/docs/agent/options.html#_atlas_token),
CLI flag or with the [`atlas_infrastructure`](/docs/agent/options.html#atlas_infrastructure) config option. [`-atlas-token` configuration option](/docs/agent/options.html#atlas_token), or `ATLAS_TOKEN` environment variable.
The Atlas token is set with the [`-atlas-token`](/docs/agent/options.html#_atlas_token) CLI flag,
[`-atlas-token`](/docs/agent/options.html#atlas_token) configuration option, or `ATLAS_TOKEN` To get an Atlas username and token, [create an account here](https://atlas.hashicorp.com/account/new?utm_source=oss&utm_medium=guide-atlasn&utm_campaign=consul) and replace the respective values in your Consul configuration with your credentials.
environment variable.
To verify the integration, either run the agent with `debug`-level logging or use `consul monitor -log-level=debug` 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: and look for a line like:
@ -38,8 +35,8 @@ Once integrated with Atlas, the auto-join feature can be used to have nodes auto
peers in their datacenter. Server nodes will automatically join peer LAN nodes and other WAN nodes. 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. Client nodes will only join other LAN nodes in their datacenter.
Auto-join is enabled with the [`-atlas-join`](/docs/agent/options.html#_atlas_join) CLI flag or the Auto-join is enabled with the [`-atlas-join` CLI flag](/docs/agent/options.html#_atlas_join) or the
[`atlas_join`](/docs/agent/options.html#atlas_join) configuration option. [`atlas_join` configuration option](/docs/agent/options.html#atlas_join).
## Securing Atlas ## Securing Atlas

22
website/source/docs/guides/bootstrapping.html.markdown
View File

@ -14,7 +14,7 @@ The client nodes are mostly stateless and rely heavily on the server nodes.
Before a Consul cluster can begin to service requests, a server node must be elected leader. Before a Consul cluster can begin to service requests, a server node must be elected leader.
Thus, the first nodes that are started are generally the server nodes. Bootstrapping is the process Thus, the first nodes that are started are generally the server nodes. Bootstrapping is the process
of joining these server nodes into a cluster. of joining these initial server nodes into a cluster.
The recommended way to bootstrap is to use the [`-bootstrap-expect`](/docs/agent/options.html#_bootstrap_expect) The recommended way to bootstrap is to use the [`-bootstrap-expect`](/docs/agent/options.html#_bootstrap_expect)
configuration option. This option informs Consul of the expected number of configuration option. This option informs Consul of the expected number of
@ -38,17 +38,29 @@ providing the `-bootstrap-expect 3` flag. Once the nodes are started, you should
This indicates that the nodes are expecting 2 peers but none are known yet. To provent a split-brain This indicates that the nodes are expecting 2 peers but none are known yet. To provent a split-brain
scenario, the servers will not elect themselves leader. scenario, the servers will not elect themselves leader.
To trigger leader election, we must join these machines together. Since a join operation is symmetric, ## Creating a cluster
it does not matter which node initiates it.
From any node, you can do the following: To trigger leader election, we must join these machines together and create a cluster. There are two options for joining; you can use [Atlas by HashiCorp](https://atlas.hashicorp.com?utm_source=oss&utm_medium=guide-bootstrapping&utm_campaign=consul) to auto-join or you can access the machine and manually run the join.
For auto-join using Atlas, you must set three configurations — the name of your Atlas infrastructure with the [`-atlas` flag](/docs/agent/options.html#_atlas), your Atlas token with the [`-atlas-token` CLI flag](/docs/agent/options.html#_atlas_token), and the [`-atlas-join` flag](/docs/agent/options.html#_atlas_join). Below is an example configuration:
```text
$ consul agent -server -data-dir="/tmp/consul" -bootstrap-expect 3 \
-atlas=ATLAS_USERNAME/infrastructure \
-atlas-join \
-atlas-token="YOUR_ATLAS_TOKEN"
```
To get an Atlas username and token, [create an account here](https://atlas.hashicorp.com/account/new?utm_source=oss&utm_medium=guide-bootstrapping&utm_campaign=consul) and replace the respective values in your Consul configuration with your credentials.
To manually create a cluster, access one of the machines and run the following:
```text ```text
$ consul join <Node A Address> <Node B Address> <Node C Address> $ consul join <Node A Address> <Node B Address> <Node C Address>
Successfully joined cluster by contacting 3 nodes. Successfully joined cluster by contacting 3 nodes.
``` ```
Once the join is successful, one of the nodes will output something like: Since a join operation is symmetric, it does not matter which node initiates it. Once the join is successful, one of the nodes will output something like:
```text ```text
[INFO] consul: adding server foo (Addr: 127.0.0.2:8300) (DC: dc1) [INFO] consul: adding server foo (Addr: 127.0.0.2:8300) (DC: dc1)

14
website/source/intro/getting-started/join.html.markdown
View File

@ -82,8 +82,18 @@ agent-two 172.20.20.11:8301 alive role=node,dc=dc1,vsn=2,vsn_min=1,vsn_max
learn about <em>one existing member</em>. After joining the cluster, the learn about <em>one existing member</em>. After joining the cluster, the
agents gossip with each other to propagate full membership information. agents gossip with each other to propagate full membership information.
In addition to using `consul join` you can use the `-join` flag on ## Auto-joining a Cluster on Start
`consul agent` to join a cluster as part of starting up the agent. Ideally whenever a new node is brought up in your datacenter, it should automatically join the Consul cluster without human intervention. To accomplish this, you can use [Atlas by HashiCorp](https://atlas.hashicorp.com?utm_source=oss&utm_medium=getting-started-join&utm_campaign=consul) and the [`-atlas-join` flag](/docs/agent/options.html#_atlas_join). An example configuration is shown below:
```text
$ consul agent -atlas-join \
-atlas=ATLAS_USERNAME/infrastructure \
-atlas-token="YOUR_ATLAS_TOKEN"
```
To get an Atlas username and token, [create an account here](https://atlas.hashicorp.com/account/new?utm_source=oss&utm_medium=getting-started-join&utm_campaign=consul) and replace the respective values in your Consul configuration with your credentials. Now whenever a new node comes up with a Consul agent, it automatically joins your Consul cluster without any hardcoded configurations.
Alternatively, you can use the [`-join` flag](http://www.consul.io/docs/agent/options.html#_join)
with a hardcoded address of a known Consul agent to join a cluster.
## Querying Nodes ## Querying Nodes

63
website/source/intro/getting-started/ui.html.markdown
View File

@ -8,19 +8,47 @@ description: |-
# Consul Web UI # Consul Web UI
Consul comes with support for a Consul comes with support for a beautiful, functional web UI.
[beautiful, functional web UI](http://demo.consul.io) out of the box. The UI can be used for viewing all services and nodes, viewing all
This UI can be used for viewing all services and nodes, viewing all
health checks and their current status, and for reading and setting health checks and their current status, and for reading and setting
key/value data. The UI automatically supports multi-datacenter. key/value data. The UI automatically supports multi-datacenter.
For ease of deployment, the UI is There are two options for running a web UI for Consul. The first option is self-hosting and using the [open-source UI](/downloads.html), the second option is using [Atlas by HashiCorp](https://atlas.hashicorp.com) to host the dashboard for you.
[distributed](/downloads.html)
as static HTML and JavaScript.
You don't need a separate web server to run the web UI. The Consul
agent itself can be configured to serve the UI.
## Screenshot and Demo ## Atlas-hosted Dashboard
To setup the Atlas UI for Consul, you must add two fields to your configuration — the name of your Atlas infrastructure and your Atlas token. Below is an example configuration:
```text
$ consul agent -atlas=ATLAS_USERNAME/demo -atlas-token="ATLAS_TOKEN"
```
To get an Atlas username and token, [create an account here](https://atlas.hashicorp.com/account/new?utm_source=oss&utm_medium=getting-started-ui&utm_campaign=packer) and replace the respective values in your Consul configuration with your credentials.
You can view a live demo of the Atlas UI [here](https://atlas.hashicorp.com/hashicorp/infrastructures/consul-demo).
A screenshot of one page of the demo is shown below so you can get an
idea of what the web UI is like.
<div class="center">
![Atlas Web UI](atlas_web_ui.png)
</div>
## Self-hosted Dashboard
To set up the self-hosted UI,
[download the web UI package](/downloads.html)
and unzip it to a directory somewhere on the server where the Consul agent
is also being run. Then append the `-ui-dir` to the `consul agent`
command pointing to the directory where you unzipped the UI (the
directory with the `index.html` file):
```text
$ consul agent -ui-dir /path/to/ui
...
```
The UI is available at the `/ui` path on the same port as the HTTP API.
By default this is `http://localhost:8500/ui`.
-datacenter.
You can view a live demo of the Consul Web UI You can view a live demo of the Consul Web UI
[here](http://demo.consul.io). [here](http://demo.consul.io).
@ -37,20 +65,3 @@ idea of what the web UI is like. Click the screenshot for the full size.
<div class="center"> <div class="center">
![Consul Web UI](consul_web_ui.png) ![Consul Web UI](consul_web_ui.png)
</div> </div>
## Set Up
To set up the web UI,
[download the web UI package](/downloads.html)
and unzip it to a directory somewhere on the server where the Consul agent
is also being run. Then, just append the `-ui-dir` to the `consul agent`
command pointing to the directory where you unzipped the UI (the
directory with the `index.html` file):
```text
$ consul agent -ui-dir /path/to/ui
...
```
The UI is available at the `/ui` path on the same port as the HTTP API.
By default this is `http://localhost:8500/ui`.