status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

website: getting started registeringa service changes

This commit is contained in:
Mitchell Hashimoto 2014-04-14 12:38:24 -07:00
parent 586c6c6ac7
commit 5f50c80aef
2 changed files with 95 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

137
website/source/intro/getting-started/services.html.markdown
View File

@ -6,58 +6,72 @@ sidebar_current: "gettingstarted-services"
# Registering Services # Registering Services
In the previous page, we created a simple cluster. Although the cluster members In the previous page, we ran our first agent, saw the cluster members, and
could see each other, there were no registered services. In this page, we'll queried that node. On this page, we'll register our first service and query
modify our client to export a service. that service. We're not yet running a cluster of Consul agents.
## Defining a Service ## Defining a Service
A service can be registered either by providing a [service definition](/docs/agent/services.html), A service can be registered either by providing a
or by making the appropriate calls to the [HTTP API](/docs/agent/http.html). First we [service definition](/docs/agent/services.html),
start by providing a simple service definition. We will by using the same setup as in the or by making the appropriate calls to the
[last page](/intro/getting-started/join.html). On the second node, we start by creating a [HTTP API](/docs/agent/http.html).
simple configuration:
We're going to start by registering a service using a service definition,
since this is the most common way that services are registered. We'll be
building on what we covered in the
[previous page](/intro/getting-started/agent.html).
First, create a directory for Consul configurations. A good directory
is typically `/etc/consul.d`. Consul loads all configuration files in the
configuration directory.
``` ```
$ sudo mkdir /etc/consul $ sudo mkdir /etc/consul.d
$ echo '{"service": {"name": "web", "tags": ["rails"], "port": 80}}' | sudo tee /etc/consul/web.json
``` ```
We now restart the second agent, providing the configuration directory as well as the Next, we'll write a service definition configuration file. We'll
first node to re-join: pretend we have a service named "web" running on port 80. Additionally,
we'll give it some tags, which we can use as additional ways to query
it later.
``` ```
$ consul agent -data-dir /tmp/consul -node=agent-two -bind=172.20.20.11 -config-dir /etc/consul/ $ echo '{"service": {"name": "web", "tags": ["rails"], "port": 80}}' \
>/etc/consul.d/web.json
```
Now, restart the agent we're running, providing the configuration directory:
```
$ consul agent -server -bootstrap -data-dir /tmp/consul -config-dir /etc/consul.d
==> Starting Consul agent... ==> Starting Consul agent...
... ...
[INFO] agent: Synced service 'web' [INFO] agent: Synced service 'web'
... ...
``` ```
You'll notice in the output that it "synced" the web service. This means
that it loaded the information from the configuration.
If you wanted to register multiple services, you create multiple service
definition files in the Consul configuration directory.
## Querying Services ## Querying Services
Once the agent gets started, we should see a log output indicating that the `web` service Once the agent is started and the service is synced, we can query that
has been synced with the Consul servers. We can first check using the HTTP API: service using either the DNS or HTTP API.
``` ### DNS API
$ curl http://localhost:8500/v1/catalog/service/web
[{"Node":"agent-two","Address":"172.20.20.11","ServiceID":"web","ServiceName":"web","ServiceTags":["rails"],"ServicePort":80}]
```
We can also do a simple DNS lookup for any nodes providing the `web` service: Let's first query it using the DNS API. For the DNS API, the DNS name
for services is `NAME.service.consul`. All DNS names are always in the
`consul` namespace. The `service` subdomain on that tells Consul we're
querying services, and the `NAME` is the name of the service. For the
web service we registered, that would be `web.service.consul`:
``` ```
$ dig @127.0.0.1 -p 8600 web.service.consul $ dig @127.0.0.1 -p 8600 web.service.consul
...
; <<>> DiG 9.8.1-P1 <<>> @127.0.0.1 -p 8600 web.service.consul
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 1204
;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0
;; WARNING: recursion requested but not available
;; QUESTION SECTION: ;; QUESTION SECTION:
;web.service.consul. IN A ;web.service.consul. IN A
@ -66,31 +80,60 @@ $ dig @127.0.0.1 -p 8600 web.service.consul
web.service.consul. 0 IN A 172.20.20.11 web.service.consul. 0 IN A 172.20.20.11
``` ```
We can also filter on tags, here only requesting services matching the `rails` tag, As you can see, an A record was returned with the IP address of the node that
and specifically requesting SRV records: the service is available on. A records can only hold IP addresses. You can
also use the DNS API to retrieve the entire address/port pair using SRV
records:
```
$ dig @127.0.0.1 -p 8600 web.service.consul SRV
...
;; QUESTION SECTION:
;web.service.consul. IN SRV
;; ANSWER SECTION:
web.service.consul. 0 IN SRV 1 1 80 agent-one.node.dc1.consul.
;; ADDITIONAL SECTION:
agent-one.node.dc1.consul. 0 IN A 172.20.20.11
```
The SRV record returned says that the web service is running on port 80
and exists on the node `agent-one.node.dc1.consul.`. An additional section
is returned by the DNS with the A record for that node.
Finally, we can also use the DNS API to filter services by tags. The
format for tag-based service queries is `TAG.NAME.service.consul`. In
the example below, we ask Consul for all web services with the "rails"
tag. We get a response since we registered our service with that tag.
``` ```
$ dig @127.0.0.1 -p 8600 rails.web.service.consul SRV $ dig @127.0.0.1 -p 8600 rails.web.service.consul SRV
...
; <<>> DiG 9.8.1-P1 <<>> @127.0.0.1 -p 8600 rails.web.service.consul SRV
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 45798
;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
;; WARNING: recursion requested but not available
;; QUESTION SECTION: ;; QUESTION SECTION:
;rails.web.service.consul. IN SRV ;rails.web.service.consul. IN A
;; ANSWER SECTION: ;; ANSWER SECTION:
rails.web.service.consul. 0 IN SRV 1 1 80 agent-two.node.dc1.consul. rails.web.service.consul. 0 IN A 172.20.20.11
;; ADDITIONAL SECTION:
agent-two.node.dc1.consul. 0 IN A 172.20.20.11
``` ```
This shows how simple it is to get started with services. Service definitions ### HTTP API
can be updated by changing configuration files and sending a `SIGHUP` to the agent.
Alternatively the HTTP API can be used to add, remove and modify services dynamically. In addition to the DNS API, the HTTP API can be used to query services:
```
$ curl http://localhost:8500/v1/catalog/service/web
[{"Node":"agent-one","Address":"172.20.20.11","ServiceID":"web","ServiceName":"web","ServiceTags":["rails"],"ServicePort":80}]
```
## Updating Services
Service definitions can be updated by changing configuration files and
sending a `SIGHUP` to the agent. This lets you update services without
any downtime or unavailability to service queries.
Alternatively the HTTP API can be used to add, remove, and modify services
dynamically.

8
website/source/layouts/intro.erb
View File

@ -50,14 +50,14 @@
<a href="/intro/getting-started/agent.html">Run the Agent</a> <a href="/intro/getting-started/agent.html">Run the Agent</a>
</li> </li>
<li<%= sidebar_current("gettingstarted-join") %>>
<a href="/intro/getting-started/join.html">Join a Cluster</a>
</li>
<li<%= sidebar_current("gettingstarted-services") %>> <li<%= sidebar_current("gettingstarted-services") %>>
<a href="/intro/getting-started/services.html">Services</a> <a href="/intro/getting-started/services.html">Services</a>
</li> </li>
<li<%= sidebar_current("gettingstarted-join") %>>
<a href="/intro/getting-started/join.html">Join a Cluster</a>
</li>
<li<%= sidebar_current("gettingstarted-checks") %>> <li<%= sidebar_current("gettingstarted-checks") %>>
<a href="/intro/getting-started/checks.html">Health Checks</a> <a href="/intro/getting-started/checks.html">Health Checks</a>
</li> </li>