github.com/mattyr/nomad@v0.3.3-0.20160919021406-3485a065154a/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  To configure Consul integration please see the Agent's configuration
    24  [here](/docs/agent/config.html#consul_options).
    25  
    26  ## Service Definition Syntax
    27  
    28  The service block in a Task definition defines a service which Nomad will
    29  register with Consul. Multiple service blocks are allowed in a Task definition,
    30  which allow registering multiple services for a Task that exposes multiple
    31  ports.
    32  
    33  ### Example
    34  
    35  A brief example of a service definition in a Task
    36  
    37  ```
    38  group "database" {
    39      task "mysql" {
    40          driver = "docker"
    41          service {
    42              tags = ["master", "mysql"]
    43              port = "db"
    44              check {
    45                  type = "tcp"
    46                  interval = "10s"
    47                  timeout = "2s"
    48              }
    49              check {
    50                  type = "script"
    51                  name = "check_table"
    52                  command = "/usr/local/bin/check_mysql_table_status"
    53                  args = ["--verbose"]
    54                  interval = "60s"
    55                  timeout = "5s"
    56              }
    57          }
    58          resources {
    59              cpu = 500
    60              memory = 1024
    61              network {
    62                  mbits = 10
    63                  port "db" {
    64                  }
    65              }
    66          }
    67      }
    68  }
    69  ```
    70  
    71  * `name`: Nomad automatically determines the name of a Task. By default the
    72    name of a service is `$(job-name)-$(task-group)-$(task-name)`. Users can
    73    explicitly name the service by specifying this option. If multiple services
    74    are defined for a Task then only one task can have the default name, all
    75    the services have to be explicitly named.  Users can add the following to
    76    the service names: `${JOB}`, `${TASKGROUP}`, `${TASK}`, `${BASE}`.  Nomad
    77    will replace them with the appropriate value of the Job, Task Group, and
    78    Task names while registering the Job. `${BASE}` expands to
    79    `${JOB}-${TASKGROUP}-${TASK}`.  Names must be adhere to
    80    [RFC-1123 ยง2.1](https://tools.ietf.org/html/rfc1123#section-2) and are
    81    limited to alphanumeric and hyphen characters (i.e. `[a-z0-9\-]`), and be
    82    less than 64 characters in length.
    83  
    84  * `tags`: A list of tags associated with this Service. String interpolation is
    85    supported in tags.
    86  
    87  * `port`: `port` is optional and is used to associate the port with the service.
    88    If specified, the port label must match one defined in the resources block.
    89    This could be a label to either a dynamic or a static port. If an incorrect
    90    port label is specified, Nomad doesn't register the IP:Port with Consul.
    91  
    92  * `check`: A check block defines a health check associated with the service.
    93    Multiple check blocks are allowed for a service. Nomad supports the `script`,
    94    `http` and `tcp` Consul Checks. Script checks are not supported for the qemu
    95    driver since the Nomad client doesn't have access to the file system of a
    96    tasks using the Qemu driver.
    97  
    98  ### Check Syntax
    99  
   100  * `type`: This indicates the check types supported by Nomad. Valid options are
   101    currently `script`, `http` and `tcp`.
   102  
   103  * `name`: The name of the health check.
   104  
   105  * `interval`: 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  * `command`: This is the command that the Nomad client runs for doing script based
   120    health check.
   121  
   122  * `args`: Additional arguments to the `command` for script based health checks.
   123  
   124  ## Assumptions
   125  
   126  * Consul 0.6.4 or later is needed for using the Script checks.
   127  
   128  * Consul 0.6.0 or later is needed for using the TCP checks.
   129  
   130  * The service discovery feature in Nomad depends on operators making sure that
   131    the Nomad client can reach the Consul agent.
   132  
   133  * Nomad assumes that it controls the life cycle of all the externally
   134    discoverable services running on a host.
   135  
   136  * Tasks running inside Nomad also need to reach out to the Consul agent if
   137    they want to use any of the Consul APIs. Ex: A task running inside a docker
   138    container in the bridge mode won't be able to talk to a Consul Agent running
   139    on the loopback interface of the host since the container in the bridge mode
   140    has it's own network interface and doesn't see interfaces on the global
   141    network namespace of the host. There are a couple of ways to solve this, one
   142    way is to run the container in the host networking mode, or make the Consul
   143    agent listen on an interface in the network namespace of the container.