github.com/taylorchu/nomad@v0.5.3-rc1.0.20170407200202-db11e7dd7b55/website/source/docs/job-specification/service.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "service Stanza - Job Specification"
     4  sidebar_current: "docs-job-specification-service"
     5  description: |-
     6    The "service" stanza instructs Nomad to register the task as a service using
     7    the service discovery integration.
     8  ---
     9  
    10  # `service` Stanza
    11  
    12  <table class="table table-bordered table-striped">
    13    <tr>
    14      <th width="120">Placement</th>
    15      <td>
    16        <code>job -> group -> task -> **service**</code>
    17      </td>
    18    </tr>
    19  </table>
    20  
    21  The `service` stanza instructs Nomad to register the task as a service using the
    22  service discovery integration. This section of the documentation will discuss the
    23  configuration, but please also read the
    24  [Nomad service discovery documentation][service-discovery] for more detailed
    25  information about the integration.
    26  
    27  ```hcl
    28  job "docs" {
    29    group "example" {
    30      task "server" {
    31        service {
    32          tags = ["leader", "mysql"]
    33  
    34          port = "db"
    35  
    36          check {
    37            type     = "tcp"
    38            port     = "db"
    39            interval = "10s"
    40            timeout  = "2s"
    41          }
    42  
    43          check {
    44            type     = "script"
    45            name     = "check_table"
    46            command  = "/usr/local/bin/check_mysql_table_status"
    47            args     = ["--verbose"]
    48            interval = "60s"
    49            timeout  = "5s"
    50          }
    51        }
    52      }
    53    }
    54  }
    55  ```
    56  
    57  This section of the documentation only covers the job file options for
    58  configuring service discovery. For more information on the setup and
    59  configuration to integrate Nomad with service discovery, please see the
    60  [Nomad service discovery documentation][service-discovery]. There are steps you
    61  must take to configure Nomad. Simply adding this configuration to your job file
    62  does not automatically enable service discovery.
    63  
    64  ## `service` Parameters
    65  
    66  - `check` <code>([Check](#check-parameters): nil)</code> - Specifies a health
    67    check associated with the service. This can be specified multiple times to
    68    define multiple checks for the service. At this time, Nomad supports the
    69    `script`<sup><small>1</small></sup>, `http` and `tcp` checks.
    70  
    71  - `name` `(string: "<job>-<group>-<task>")` - Specifies the name of this
    72    service. If not supplied, this will default to the name of the job, group, and
    73    task concatenated together with a dash, like `"docs-example-server"`. Each
    74    service must have a unique name within the cluster. Names must adhere to
    75    [RFC-1123 ยง2.1](https://tools.ietf.org/html/rfc1123#section-2) and are limited
    76    to alphanumeric and hyphen characters (i.e. `[a-z0-9\-]`), and be less than 64
    77    characters in length.
    78  
    79      In addition to the standard [Nomad interpolation][interpolation], the
    80      following keys are also available:
    81  
    82      - `${JOB}` - the name of the job
    83      - `${GROUP}` - the name of the group
    84      - `${TASK}` - the name of the task
    85      - `${BASE}` - shorthand for `${JOB}-${GROUP}-${TASK}`
    86  
    87  - `port` `(string: <required>)` - Specifies the label of the port on which this
    88    service is running. Note this is the _label_ of the port and not the port
    89    number. The port label must match one defined in the [`network`][network]
    90    stanza.
    91  
    92  - `tags` `(array<string>: [])` - Specifies the list of tags to associate with
    93    this service. If this is not supplied, no tags will be assigned to the service
    94    when it is registered.
    95  
    96  ### `check` Parameters
    97  
    98  - `args` `(array<string>: [])` - Specifies additional arguments to the
    99    `command`. This only applies to script-based health checks.
   100  
   101  - `command` `(string: <varies>)` - Specifies the command to run for performing
   102    the health check. The script must exit: 0 for passing, 1 for warning, or any
   103    other value for a failing health check. This is required for script-based
   104    health checks.
   105  
   106      ~> **Caveat:** The command must be the path to the command on disk, and no
   107      shell exists by default. That means operators like `||` or `&&` are not
   108      available. Additionally, all arguments must be supplied via the `args`
   109      parameter. The achieve the behavior of shell operators, specify the command
   110      as a shell, like `/bin/bash` and then use `args` to run the check.
   111  
   112  - `initial_status` `(string: <enum>)` - Specifies the originating status of the
   113    service. Valid options are the empty string, `passing`, `warning`, and
   114    `critical`.
   115  
   116  - `interval` `(string: <required>)` - Specifies the frequency of the health checks
   117    that Consul will perform. This is specified using a label suffix like "30s"
   118    or "1h". This must be greater than or equal to "1s"
   119  
   120  - `name` `(string: "service: <name> check")` - Specifies the name of the health
   121    check.
   122  
   123  - `path` `(string: <varies>)` - Specifies the path of the HTTP endpoint which
   124    Consul will query to query the health of a service. Nomad will automatically
   125    add the IP of the service and the port, so this is just the relative URL to
   126    the health check endpoint. This is required for http-based health checks.
   127  
   128  - `port` `(string: <required>)` - Specifies the label of the port on which the
   129    check will be performed. Note this is the _label_ of the port and not the port
   130    number. The port label must match one defined in the [`network`][network]
   131    stanza. If a port value was declared on the `service`, this will inherit from
   132    that value if not supplied. If supplied, this value takes precedence over the
   133    `service.port` value. This is useful for services which operate on multiple
   134    ports.
   135  
   136  - `protocol` `(string: "http")` - Specifies the protocol for the http-based
   137    health checks. Valid options are `http` and `https`.
   138  
   139  - `timeout` `(string: <required>)` - Specifies how long Consul will wait for a
   140    health check query to succeed. This is specified using a label suffix like
   141    "30s" or "1h". This must be greater than or equal to "1s"
   142  
   143  - `type` `(string: <required>)` - This indicates the check types supported by
   144    Nomad. Valid options are `script`, `http`, and `tcp`.
   145  
   146  
   147  ## `service` Examples
   148  
   149  The following examples only show the `service` stanzas. Remember that the
   150  `service` stanza is only valid in the placements listed above.
   151  
   152  ### Basic Service
   153  
   154  This example registers a service named "load-balancer" with no health checks.
   155  
   156  ```hcl
   157  service {
   158    name = "load-balancer"
   159    port = "lb"
   160  }
   161  ```
   162  
   163  This example must be accompanied by a [`network`][network] stanza which defines
   164  a static or dynamic port labeled "lb". For example:
   165  
   166  ```hcl
   167  resources {
   168    network {
   169      mbits = 10
   170      port "lb" {}
   171    }
   172  }
   173  ```
   174  
   175  ### Check with Bash-isms
   176  
   177  This example shows a common mistake and correct behavior for custom checks.
   178  Suppose a health check like this:
   179  
   180  ```shell
   181  $ test -f /tmp/file.txt
   182  ```
   183  
   184  In this example `test` is not actually a command (binary) on the system; it is a
   185  built-in shell function to bash. Thus, the following **would not work**:
   186  
   187  ```hcl
   188  service {
   189    check {
   190      type    = "script"
   191      command = "test -f /tmp/file.txt" # THIS IS NOT CORRECT
   192    }
   193  }
   194  ```
   195  
   196  Nomad will attempt to find an executable named `test` on your system, but it
   197  does not exist. It is actually just a function of bash. Additionally, it is not
   198  possible to specify the arguments in a single string. Here is the correct
   199  solution:
   200  
   201  ```hcl
   202  service {
   203    check {
   204      type    = "script"
   205      command = "/bin/bash"
   206      args    = ["-c", "test -f /tmp/file.txt"]
   207    }
   208  }
   209  ```
   210  
   211  The `command` is actually `/bin/bash`, since that is the actual process we are
   212  running. The arguments to that command are the script itself, which each
   213  argument provided as a value to the `args` array.
   214  
   215  ### HTTP Health Check
   216  
   217  This example shows a service with an HTTP health check. This will query the
   218  service on the IP and port registered with Nomad at `/_healthz` every 5 seconds,
   219  giving the service a maximum of 2 seconds to return a response. Any non-2xx code
   220  is considered a failure.
   221  
   222  ```hcl
   223  service {
   224    check {
   225      type     = "http"
   226      port     = "lb"
   227      path     = "/_healthz"
   228      interval = "5s"
   229      timeout  = "2s"
   230    }
   231  }
   232  ```
   233  
   234  ### Multiple Health Checks
   235  
   236  This example shows a service with multiple health checks defined. All health
   237  checks must be passing in order for the service to register as healthy.
   238  
   239  ```hcl
   240  service {
   241    check {
   242      type     = "http"
   243      port     = "lb"
   244      path     = "/_healthz"
   245      interval = "5s"
   246      timeout  = "2s"
   247    }
   248  
   249    check {
   250      type     = "http"
   251      protocol = "https"
   252      port     = "lb"
   253      path     = "/_healthz"
   254      interval = "5s"
   255      timeout  = "2s"
   256    }
   257  
   258    check {
   259      type     = "script"
   260      command  = "/usr/local/bin/pg-tools"
   261      args     = ["verify", "database" "prod", "up"]
   262      interval = "5s"
   263      timeout  = "2s"
   264    }
   265  }
   266  ```
   267  
   268  - - -
   269  
   270  <sup><small>1</small></sup><small> Script checks are not supported for the
   271  [qemu driver][qemu] since the Nomad client does not have access to the file
   272  system of a task for that driver.</small>
   273  
   274  [service-discovery]: /docs/service-discovery/index.html "Nomad Service Discovery"
   275  [interpolation]: /docs/runtime/interpolation.html "Nomad Runtime Interpolation"
   276  [network]: /docs/job-specification/network.html "Nomad network Job Specification"
   277  [qemu]: /docs/drivers/qemu.html "Nomad qemu Driver"