github.com/ryanslade/nomad@v0.2.4-0.20160128061903-fc95782f2089/website/source/docs/jobspec/servicediscovery.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Service Discovery in Nomad"
     4  sidebar_current: "docs-jobspec-service-discovery"
     5  description: |-
     6    Learn how to add service discovery to jobs
     7  ---
     8  
     9  # Service Discovery
    10  
    11  Nomad schedules workloads of various types across a cluster of generic hosts.
    12  Because of this, placement is not known in advance and you will need to use
    13  service discovery to connect tasks to other services deployed across your
    14  cluster. Nomad integrates with [Consul](https://www.consul.io) to provide service
    15  discovery and monitoring.
    16  
    17  Note that in order to use Consul with Nomad, you will need to configure and
    18  install Consul on your nodes alongside Nomad, or schedule it as a system job.
    19  Nomad does not currently run Consul for you.
    20  
    21  ## Configuration
    22  
    23  * `consul.address`: This is a Nomad client configuration which can be used to
    24    override the default Consul Agent HTTP port that Nomad uses to connect to
    25    Consul. The default for this is `127.0.0.1:8500`.
    26  
    27  * `consul.token`: Token is used to provide a per-request ACL token.This options
    28    overrides the agent's default token
    29  
    30  * `consul.auth`: The auth information to use for http access to the Consul
    31    Agent.
    32  
    33  * `consul.ssl`: This boolean option sets the transport scheme to talk to the Consul
    34    Agent as `https`. This option is unset by default and so the default transport
    35    scheme for the consul api client is `http`.
    36  
    37  * `consul.verifyssl`: This option enables SSL verification when the transport
    38   scheme for the Consul API client is `https`. This is set to true by default.
    39  
    40  
    41  ## Service Definition Syntax
    42  
    43  The service block in a Task definition defines a service which Nomad will
    44  register with Consul. Multiple service blocks are allowed in a Task definition,
    45  which allow registering multiple services for a Task that exposes multiple
    46  ports.
    47  
    48  ### Example
    49  
    50  A brief example of a service definition in a Task
    51  
    52  ```
    53  group "database" {
    54      task "mysql" {
    55          driver = "docker"
    56          service {
    57              tags = ["master", "mysql"]
    58              port = "db"
    59              check {
    60                  type = "tcp"
    61                  delay = "10s"
    62                  timeout = "2s"
    63              }
    64          }
    65          resources {
    66              cpu = 500
    67              memory = 1024
    68              network {
    69                  mbits = 10
    70                  port "db" {
    71                  }
    72              }
    73          }
    74      }
    75  }
    76  ```
    77  
    78  * `name`: Nomad automatically determines the name of a Task. By default the
    79    name of a service is $(job-name)-$(task-group)-$(task-name). Users can
    80    explicitly name the service by specifying this option. If multiple services
    81    are defined for a Task then only one task can have the default name, all the
    82    services have to be explicitly named. Users can add the following to the
    83    service names: ```${JOB}```, ```${TASKGROUP}```, ```${TASK}```, ```${BASE}```. 
    84    Nomad will replace them with the appropriate value of the Job, Task Group and 
    85    Task names while registering the Job. ```${BASE}``` expands to ${JOB}-${TASKGROUP}-${TASK}
    86  
    87  * `tags`: A list of tags associated with this Service.
    88  
    89  * `port`: The port indicates the port associated with the service. Users are
    90    required to specify a valid port label here which they have defined in the
    91    resources block. This could be a label to either a dynamic or a static port.
    92    If an incorrect port label is specified, Nomad doesn't register the service
    93    with Consul.
    94  
    95  * `check`: A check block defines a health check associated with the service.
    96    Multiple check blocks are allowed for a service. Nomad currently supports
    97    only the `http` and `tcp` Consul Checks.
    98  
    99  ### Check Syntax
   100  
   101  * `type`: This indicates the check types supported by Nomad. Valid options are
   102    currently `http` and `tcp`. In the future Nomad will add support for more
   103    Consul checks.
   104  
   105  * `delay`: This indicates the frequency of the health checks that Consul will
   106    perform.
   107  
   108  * `timeout`: This indicates how long Consul will wait for a health check query
   109    to succeed.
   110  
   111  * `path`: The path of the http endpoint which Consul will query to query the
   112    health of a service if the type of the check is `http`. Nomad will add the IP
   113    of the service and the port, users are only required to add the relative URL
   114    of the health check endpoint.
   115  
   116  * `protocol`: This indicates the protocol for the http checks. Valid options
   117    are `http` and `https`. We default it to `http`
   118  
   119  ## Assumptions
   120  
   121  * Consul 0.6.0 or later is needed for using the TCP checks.
   122  
   123  * The service discovery feature in Nomad depends on operators making sure that
   124    the Nomad client can reach the Consul agent.
   125  
   126  * Nomad assumes that it controls the life cycle of all the externally
   127    discoverable services running on a host.
   128  
   129  * Tasks running inside Nomad also need to reach out to the Consul agent if
   130    they want to use any of the Consul APIs. Ex: A task running inside a docker
   131    container in the bridge mode won't be able to talk to a Consul Agent running
   132    on the loopback interface of the host since the container in the bridge mode
   133    has it's own network interface and doesn't see interfaces on the global
   134    network namespace of the host. There are a couple of ways to solve this, one
   135    way is to run the container in the host networking mode, or make the Consul
   136    agent listen on an interface in the network namespace of the container.