github.com/outbrain/consul@v1.4.5/website/source/intro/getting-started/services.html.md (about)

     1  ---
     2  layout: "intro"
     3  page_title: "Registering Services"
     4  sidebar_current: "gettingstarted-services"
     5  description: >
     6    A service can be registered either by providing a service definition or by
     7    making the appropriate calls to the HTTP API. A configuration file is the
     8    most common, so we will use this approach to register a service, and then
     9    query that service using the REST API and DNS interfaces.
    10  ---
    11  
    12  # Registering Services
    13  
    14  In the previous step, we ran our first agent, saw the cluster members (well,
    15  our cluster _member_), and queried that node. In this guide, we'll register
    16  our first service and query that service.
    17  
    18  ## Defining a Service
    19  
    20  A service can be registered either by providing a
    21  [service definition](/docs/agent/services.html) or by making the appropriate
    22  calls to the [HTTP API](/api/index.html).
    23  
    24  A service definition is the most common way to register services, so we'll
    25  use that approach for this step. We'll be building on the agent configuration
    26  we covered in the [previous step](/intro/getting-started/agent.html).
    27  
    28  First, create a directory for Consul configuration. Consul loads all
    29  configuration files in the configuration directory, so a common convention
    30  on Unix systems is to name the directory something like `/etc/consul.d`
    31  (the `.d` suffix implies "this directory contains a set of configuration
    32  files").
    33  
    34  ```text
    35  $ sudo mkdir /etc/consul.d
    36  ```
    37  
    38  Next, we'll write a service definition configuration file. Let's
    39  pretend we have a service named "web" running on port 80. Additionally,
    40  we'll give it a tag we can use as an additional way to query the service:
    41  
    42  ```text
    43  $ echo '{"service": {"name": "web", "tags": ["rails"], "port": 80}}' \
    44      | sudo tee /etc/consul.d/web.json
    45  ```
    46  
    47  Now, restart the agent, providing the configuration directory:
    48  
    49  ```text
    50  $ consul agent -dev -config-dir=/etc/consul.d
    51  ==> Starting Consul agent...
    52  ...
    53      [INFO] agent: Synced service 'web'
    54  ...
    55  ```
    56  
    57  You'll notice in the output that it "synced" the web service. This means
    58  that the agent loaded the service definition from the configuration file,
    59  and has successfully registered it in the service catalog.
    60  
    61  If you wanted to register multiple services, you could create multiple
    62  service definition files in the Consul configuration directory.
    63  
    64  ## Querying Services
    65  
    66  Once the agent is started and the service is synced, we can query the
    67  service using either the DNS or HTTP API.
    68  
    69  ### DNS API
    70  
    71  Let's first query our service using the DNS API. For the DNS API, the
    72  DNS name for services is `NAME.service.consul`. By default, all DNS names
    73  are always in the `consul` namespace, though
    74  [this is configurable](/docs/agent/options.html#domain). The `service`
    75  subdomain tells Consul we're querying services, and the `NAME` is the name
    76  of the service.
    77  
    78  For the web service we registered, these conventions and settings yield a
    79  fully-qualified domain name of `web.service.consul`:
    80  
    81  ```text
    82  $ dig @127.0.0.1 -p 8600 web.service.consul
    83  ...
    84  
    85  ;; QUESTION SECTION:
    86  ;web.service.consul.		IN	A
    87  
    88  ;; ANSWER SECTION:
    89  web.service.consul.	0	IN	A	172.20.20.11
    90  ```
    91  
    92  As you can see, an `A` record was returned with the IP address of the node on
    93  which the service is available. `A` records can only hold IP addresses.
    94  
    95  You can also use the DNS API to retrieve the entire address/port pair as a
    96  `SRV` record:
    97  
    98  ```text
    99  $ dig @127.0.0.1 -p 8600 web.service.consul SRV
   100  ...
   101  
   102  ;; QUESTION SECTION:
   103  ;web.service.consul.		IN	SRV
   104  
   105  ;; ANSWER SECTION:
   106  web.service.consul.	0	IN	SRV	1 1 80 Armons-MacBook-Air.node.dc1.consul.
   107  
   108  ;; ADDITIONAL SECTION:
   109  Armons-MacBook-Air.node.dc1.consul. 0 IN A	172.20.20.11
   110  ```
   111  
   112  The `SRV` record says that the web service is running on port 80 and exists on
   113  the node `Armons-MacBook-Air.node.dc1.consul.`. An additional section is returned by the
   114  DNS with the `A` record for that node.
   115  
   116  Finally, we can also use the DNS API to filter services by tags. The
   117  format for tag-based service queries is `TAG.NAME.service.consul`. In
   118  the example below, we ask Consul for all web services with the "rails"
   119  tag. We get a successful response since we registered our service with
   120  that tag:
   121  
   122  ```text
   123  $ dig @127.0.0.1 -p 8600 rails.web.service.consul
   124  ...
   125  
   126  ;; QUESTION SECTION:
   127  ;rails.web.service.consul.		IN	A
   128  
   129  ;; ANSWER SECTION:
   130  rails.web.service.consul.	0	IN	A	172.20.20.11
   131  ```
   132  
   133  ### HTTP API
   134  
   135  In addition to the DNS API, the HTTP API can be used to query services:
   136  
   137  ```text
   138  $ curl http://localhost:8500/v1/catalog/service/web
   139  [{"Node":"Armons-MacBook-Air","Address":"172.20.20.11","ServiceID":"web", \
   140  	"ServiceName":"web","ServiceTags":["rails"],"ServicePort":80}]
   141  ```
   142  
   143  The catalog API gives all nodes hosting a given service. As we will see later
   144  with [health checks](/intro/getting-started/checks.html) you'll typically want
   145  to query just for healthy instances where the checks are passing. This is what
   146  DNS is doing under the hood. Here's a query to look for only healthy instances:
   147  
   148  ```text
   149  $ curl 'http://localhost:8500/v1/health/service/web?passing'
   150  [{"Node":"Armons-MacBook-Air","Address":"172.20.20.11","Service":{ \
   151  	"ID":"web", "Service":"web", "Tags":["rails"],"Port":80}, "Checks": ...}]
   152  ```
   153  
   154  ## Updating Services
   155  
   156  Service definitions can be updated by changing configuration files and
   157  sending a `SIGHUP` to the agent. This lets you update services without
   158  any downtime or unavailability to service queries.
   159  
   160  Alternatively, the HTTP API can be used to add, remove, and modify services
   161  dynamically.
   162  
   163  ## Next Steps
   164  
   165  We've now configured a single agent and registered a service. This is good
   166  progress, but let's explore the full value of Consul by learning how to
   167  [automatically encrypt and authorize service-to service communication](/intro/getting-started/connect.html) with Consul Connect.