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

Website: GH-730 and cleanup for intro/getting-started/services.html

pull/784/head
Ryan Breen 2015-03-13 14:56:58 -04:00
parent f4ddec7521
commit d969655cfa
1 changed files with 50 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -3,49 +3,49 @@ layout: "intro"
page_title: "Registering Services"
sidebar_current: "gettingstarted-services"
description: |-
In the previous page, we ran our first agent, saw the cluster members, and queried that node. On this page, we'll register our first service and query that service. We're not yet running a cluster of Consul agents.
In the previous step, we ran our first agent, saw the cluster members (well, our cluster member), and queried that node. Now, we'll register our first service and query that service.
---
# Registering Services
In the previous page, we ran our first agent, saw the cluster members, and
queried that node. On this page, we'll register our first service and query
that service. We're not yet running a cluster of Consul agents.
In the previous step, we ran our first agent, saw the cluster members (well,
our cluster _member_), and queried that node. In this guide, we'll register
our first service and query that service.
## Defining a Service
A service can be registered either by providing a
[service definition](/docs/agent/services.html),
or by making the appropriate calls to the
[HTTP API](/docs/agent/http.html).
[service definition](/docs/agent/services.html) or by making the appropriate
calls to the [HTTP API](/docs/agent/http.html).
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).
A service definition is the most common way to register services, so we'll
use that approach for this step. We'll be building on the agent configuration
we covered in the [previous step](/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.
First, create a directory for Consul configuration. Consul loads all
configuration files in the configuration directory, so a common convention
on Unix systems is to name the directory something like `/etc/consul.d`
(the `.d` suffix implies "this directory contains a set of configuration
files").
```text
$ sudo mkdir /etc/consul.d
```
Next, we'll write a service definition configuration file. We'll
Next, we'll write a service definition configuration file. Let's
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.
we'll give it a tag we can use as an additional way to query the service:
```text
$ echo '{"service": {"name": "web", "tags": ["rails"], "port": 80}}' \
>/etc/consul.d/web.json
```
Now, restart the agent we're running, providing the configuration directory:
Now, restart the agent, providing the configuration directory:
```text
$ consul agent -server -bootstrap-expect 1 -data-dir /tmp/consul -config-dir /etc/consul.d
$ consul agent -server -bootstrap-expect 1 -data-dir /tmp/consul \
-config-dir /etc/consul.d
==> Starting Consul agent...
...
[INFO] agent: Synced service 'web'
@ -55,21 +55,25 @@ $ consul agent -server -bootstrap-expect 1 -data-dir /tmp/consul -config-dir /et
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.
If you wanted to register multiple services, you could create multiple
service definition files in the Consul configuration directory.
## Querying Services
Once the agent is started and the service is synced, we can query that
Once the agent is started and the service is synced, we can query the
service using either the DNS or HTTP API.
### DNS API
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 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`:
Let's first query our service using the DNS API. For the DNS API, the
DNS name for services is `NAME.service.consul`. By default, all DNS names
are always in the `consul` namespace, though
[this is configurable](/docs/agent/options.html#domain). The `service`
subdomain tells Consul we're querying services, and the `NAME` is the name
of the service.
For the web service we registered, these conventions and settings yield a
fully-qualified domain name of `web.service.consul`:
```text
$ dig @127.0.0.1 -p 8600 web.service.consul
@ -82,10 +86,11 @@ $ dig @127.0.0.1 -p 8600 web.service.consul
web.service.consul. 0 IN A 172.20.20.11
```
As you can see, an A record was returned with the IP address of the node that
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:
As you can see, an `A` record was returned with the IP address of the node on
which the service is available. `A` records can only hold IP addresses.
You can also use the DNS API to retrieve the entire address/port pair as a
`SRV` record:
```text
$ dig @127.0.0.1 -p 8600 web.service.consul SRV
@ -101,14 +106,15 @@ web.service.consul. 0 IN SRV 1 1 80 agent-one.node.dc1.consul.
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.
The `SRV` record 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.
tag. We get a successful response since we registered our service with
that tag:
```text
$ dig @127.0.0.1 -p 8600 rails.web.service.consul
@ -127,7 +133,8 @@ In addition to the DNS API, the HTTP API can be used to query services:
```text
$ curl http://localhost:8500/v1/catalog/service/web
[{"Node":"agent-one","Address":"172.20.20.11","ServiceID":"web","ServiceName":"web","ServiceTags":["rails"],"ServicePort":80}]
[{"Node":"agent-one","Address":"172.20.20.11","ServiceID":"web", \
"ServiceName":"web","ServiceTags":["rails"],"ServicePort":80}]
```
## Updating Services
@ -136,5 +143,11 @@ 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
Alternatively, the HTTP API can be used to add, remove, and modify services
dynamically.
## Next Steps
We've now configured a single agent and registered a service. This is good
progress, but let's explore the full value of Consul by [setting up our
first cluster](/intro/getting-started/join.html)!