github.com/dkerwin/nomad@v0.3.3-0.20160525181927-74554135514b/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  * `consul.tls_ca_file`: The path to the CA certificate used for Consul communication.
    41    Set accordingly to the
    42    [ca_file](https://www.consul.io/docs/agent/options.html#ca_file) setting in
    43    Consul.
    44  
    45  * `consul.tls_cert_file`: The path to the certificate for Consul communication. Set
    46    accordingly
    47    [cert_file](https://www.consul.io/docs/agent/options.html#cert_file) in
    48    Consul.
    49  
    50  * `consul.tls_key_file`: The path to the private key for Consul communication.
    51    Set accordingly to the
    52    [key_file](https://www.consul.io/docs/agent/options.html#key_file) setting in
    53    Consul.
    54  
    55  ## Service Definition Syntax
    56  
    57  The service block in a Task definition defines a service which Nomad will
    58  register with Consul. Multiple service blocks are allowed in a Task definition,
    59  which allow registering multiple services for a Task that exposes multiple
    60  ports.
    61  
    62  ### Example
    63  
    64  A brief example of a service definition in a Task
    65  
    66  ```
    67  group "database" {
    68      task "mysql" {
    69          driver = "docker"
    70          service {
    71              tags = ["master", "mysql"]
    72              port = "db"
    73              check {
    74                  type = "tcp"
    75                  interval = "10s"
    76                  timeout = "2s"
    77              }
    78              check {
    79                  type = "script"
    80                  name = "check_table"
    81                  command = "/usr/local/bin/check_mysql_table_status"
    82                  args = ["--verbose"]
    83                  interval = "60s"
    84                  timeout = "5s"
    85              }
    86          }
    87          resources {
    88              cpu = 500
    89              memory = 1024
    90              network {
    91                  mbits = 10
    92                  port "db" {
    93                  }
    94              }
    95          }
    96      }
    97  }
    98  ```
    99  
   100  * `name`: Nomad automatically determines the name of a Task. By default the
   101    name of a service is `$(job-name)-$(task-group)-$(task-name)`. Users can
   102    explicitly name the service by specifying this option. If multiple services
   103    are defined for a Task then only one task can have the default name, all
   104    the services have to be explicitly named.  Users can add the following to
   105    the service names: `${JOB}`, `${TASKGROUP}`, `${TASK}`, `${BASE}`.  Nomad
   106    will replace them with the appropriate value of the Job, Task Group, and
   107    Task names while registering the Job. `${BASE}` expands to
   108    `${JOB}-${TASKGROUP}-${TASK}`.  Names must be adhere to
   109    [RFC-1123 ยง2.1](https://tools.ietf.org/html/rfc1123#section-2) and are
   110    limited to alphanumeric and hyphen characters (i.e. `[a-z0-9\-]`), and be
   111    less than 64 characters in length.
   112  
   113  * `tags`: A list of tags associated with this Service. String interpolation is
   114    supported in tags.
   115  
   116  * `port`: `port` is optional and is used to associate the port with the service.
   117    If specified, the port label must match one defined in the resources block.
   118    This could be a label to either a dynamic or a static port. If an incorrect
   119    port label is specified, Nomad doesn't register the IP:Port with Consul.
   120  
   121  * `check`: A check block defines a health check associated with the service.
   122    Multiple check blocks are allowed for a service. Nomad supports the `script`,
   123    `http` and `tcp` Consul Checks. Script checks are not supported for the qemu
   124    driver since the Nomad client doesn't have access to the file system of a
   125    tasks using the Qemu driver.
   126  
   127  ### Check Syntax
   128  
   129  * `type`: This indicates the check types supported by Nomad. Valid options are
   130    currently `script`, `http` and `tcp`.
   131  
   132  * `name`: The name of the health check.
   133  
   134  * `interval`: This indicates the frequency of the health checks that Consul will
   135    perform.
   136  
   137  * `timeout`: This indicates how long Consul will wait for a health check query
   138    to succeed.
   139  
   140  * `path`: The path of the http endpoint which Consul will query to query the
   141    health of a service if the type of the check is `http`. Nomad will add the IP
   142    of the service and the port, users are only required to add the relative URL
   143    of the health check endpoint.
   144  
   145  * `protocol`: This indicates the protocol for the http checks. Valid options
   146    are `http` and `https`. We default it to `http`
   147  
   148  * `command`: This is the command that the Nomad client runs for doing script based
   149    health check.
   150  
   151  * `args`: Additional arguments to the `command` for script based health checks.
   152  
   153  ## Assumptions
   154  
   155  * Consul 0.6.4 or later is needed for using the Script checks.
   156  
   157  * Consul 0.6.0 or later is needed for using the TCP checks.
   158  
   159  * The service discovery feature in Nomad depends on operators making sure that
   160    the Nomad client can reach the Consul agent.
   161  
   162  * Nomad assumes that it controls the life cycle of all the externally
   163    discoverable services running on a host.
   164  
   165  * Tasks running inside Nomad also need to reach out to the Consul agent if
   166    they want to use any of the Consul APIs. Ex: A task running inside a docker
   167    container in the bridge mode won't be able to talk to a Consul Agent running
   168    on the loopback interface of the host since the container in the bridge mode
   169    has it's own network interface and doesn't see interfaces on the global
   170    network namespace of the host. There are a couple of ways to solve this, one
   171    way is to run the container in the host networking mode, or make the Consul
   172    agent listen on an interface in the network namespace of the container.