kemko/nomad
1
0
Fork 0
mirror of https://github.com/kemko/nomad.git synced 2026-01-03 17:05:43 +03:00
Code Issues Packages Projects Releases Wiki Activity

Give service its own configuration

Browse Source
This commit is contained in:
Seth Vargo
2016-10-31 00:00:35 -04:00
parent fc0d756d24
commit f73a83defa
3 changed files with 292 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files

273
website/source/docs/job-specification/service.html.md Normal file
View File

@@ -0,0 +1,273 @@
---
layout: "docs"
page_title: "service Stanza - Job Specification"
sidebar_current: "docs-job-specification-service"
description: |-
TODO
---
# `service` Stanza
<table class="table table-bordered table-striped">
<tr>
<th width="120">Placement</th>
<td>
<code>job -> group -> task -> **service**</code>
</td>
</tr>
</table>
The `service` stanza instructs Nomad to register the task as a service in the
service discovery integration. This section of the documentation will discus the
configuration, but please also read the
[Nomad service discovery documentation][service-discovery] for more detailed
information about the integration.
```hcl
job "docs" {
group "example" {
task "server" {
service {
tags = ["leader", "mysql"]
check {
type = "tcp"
port = "db"
interval = "10s"
timeout = "2s"
}
check {
type = "script"
name = "check_table"
command = "/usr/local/bin/check_mysql_table_status"
args = ["--verbose"]
interval = "60s"
timeout = "5s"
}
}
}
}
}
```
This section of the documentation only covers the job file options for
configuring service discovery. For more information on the setup and
configuration to integrate Nomad with service discovery, please see the
[Nomad service discovery documentation][service-discovery]. There are steps you
must take to configure Nomad. Simply adding this configuration to your job file
does not automatically enable service discovery.
## `service` Parameters
- `check` <code>([Check](#check-parameters): nil)</code> - Specifies a health check associated with the service. This can be
specified multiple times to define multiple checks for the service. At this
time, Nomad supports the `script`<sup><small>1</small></sup>, `http` and `tcp`
checks.
- `name` `(string: "<job>-<group>-<task>")` - Specifies the name of this
service. If not supplied, this will default to the name of the job, group, and
task concatenated together with a dash, like `"docs-example-server"`. Each
service must have a unique name within the cluster. Names must adhere to
[RFC-1123 §2.1](https://tools.ietf.org/html/rfc1123#section-2) and are limited
to alphanumeric and hyphen characters (i.e. `[a-z0-9\-]`), and be less than 64
characters in length.
In addition to the standard [Nomad interpolation][interpolation], the
following keys are also available:
- `${JOB}` - the name of the job
- `${GROUP}` - the name of the group
- `${TASK}` - the name of the task
- `${BASE}` - shorthand for `${JOB}-${GROUP}-${TASK}`
- `port` `(string: required)` - Specifies the label of the port on which this
service is running. Note this is the _label_ of the port and not the port
number. The port label must match one defined in the [`network`][network]
stanza.
- `tags` `(array<string>: [])` - Specifies the list of tags to associate with
this service. If this is not supplied, no tags will be assigned to the service
when it is registered.
### `check` Parameters
- `args` `(array<string>: [])` - Specifies additional arguments to the
`command`. This only applies to script-based health checks.
- `command` `(string: <varies>)` - Specifies the command to run for performing
the health check. The script must exit: 0 for passing, 1 for warning, or any
other value for a failing health check. This is required for script-based
health checks.
~> **Caveat:** The command must be the path to the command on disk, and no
shell exists by default. That means operators like `||` or `&&` are not
available. Additionally, all arguments must be supplied via the `args`
parameter. The achieve the behavior of shell operators, specify the command
as a shell, like `/bin/bash` and then use `args` to run the check.
- `initial_status` `(string: <enum>)` - Specifies the originating status of the
service. Valid options are the empty string, `passing`, `warning`, and
`critical`.
- `interval` `(string: <required>)` - Specifies the frequency of the health checks
that Consul will perform. This is specified using a label suffix like "30s"
or "1h". This must be greater than or equal to "1s"
- `name` `(string: "service: <name> check")` - Specifies the name of the health
check.
- `path` `(string: <varies>)` - Specifies the path of the http endpoint which
Consul will query to query the health of a service. Nomad will automatically
add the IP of the service and the port, so this is just the relative URL to
the health check endpoint. This is required for http-based health checks.
- `port` `(string: <required>)` - Specifies the label of the port on which the
check will be performed. Note this is the _label_ of the port and not the port
number. The port label must match one defined in the [`network`][network]
stanza. If a port value was declared on the `service`, this will inherit from
that value if not supplied. If supplied, this value takes precedence over the
`service.port` value. This is useful for services which operate on multiple
ports.
- `protocol` `(string: "http")` - Specifies the protocol for the http-based
health checks. Valid options are `http` and `https`.
- `timeout` `(string: <required>)` - Specifies how long Consul will wait for a
health check query to succeed. This is specified using a label suffix like
"30s" or "1h". This must be greater than or equal to "1s"
- `type` `(string: <required>)` - This indicates the check types supported by
Nomad. Valid options are `script`, `http`, and `tcp`.
## `service` Examples
The following examples only show the `service` stanzas. Remember that the
`service` stanza is only valid in the placements listed above.
### Basic Service
This example registers a service named "load-balancer" with no health checks.
```hcl
service {
name = "load-balancer"
port = "lb"
}
```
This example must be accompanied by a [`network`][network] stanza which defines
a static or dynamic port labeled "lb". For example:
```hcl
resources {
network {
mbits = 10
port "lb" {}
}
}
```
### Check with Bash-isms
This example shows a common mistake and correct behavior for custom checks.
Suppose a health check like this:
```shell
$ test -f /tmp/file.txt
```
In this example `test` is not actually a command (binary) on the system; it is a
built-in shell function to bash. Thus, the following **would not work**:
```hcl
service {
check {
type = "script"
command = "test -f /tmp/file.txt" # THIS IS NOT CORRECT
}
}
```
Nomad will attempt to find an executable named `test` on your system, but it
does not exist. It is actually just a function of bash. Additionally, it is not
possible to specify the arguments in a single string. Here is the correct
solution:
```hcl
service {
check {
type = "script"
command = "/bin/bash"
args = ["test", "-f", "/tmp/file.txt"]
}
}
```
The `command` is actually `/bin/bash`, since that is the actual process we are
running. The arguments to that command are the script itself, which each
argument provided as a value to the `args` array.
### HTTP Health Check
This example shows a service with an HTTP health check. This will query the
service on the IP and port registered with Nomad at `/_healthz` every 5 seconds,
giving the service a maximum of 2 seconds to return a response. Any non-2xx code
is considered a failure.
```hcl
service {
check {
type = "http"
port = "lb"
path = "/_healthz"
interval = "5s"
timeout = "2s"
}
}
```
### Multiple Health Checks
This example shows a service with multiple health checks defined. All health
checks must be passing in order for the service to register as healthy.
```hcl
service {
check {
type = "http"
port = "lb"
path = "/_healthz"
interval = "5s"
timeout = "2s"
}
check {
type = "https"
port = "lb"
path = "/_healthz"
interval = "5s"
timeout = "2s"
}
check {
type = "script"
command = "/usr/local/bin/pg-tools"
args = ["verify", "database" "prod", "up"]
interval = "5s"
timeout = "2s"
}
}
```
- - -
<sup><small>1</small></sup><small> Script checks are not supported for the
[qemu driver][qemu] since the Nomad client does not have access to the file
system of a task for that driver.</small>
[service-discovery]: /docs/service-discovery/index.html "Nomad Service Discovery"
[interpolation]: /docs/runtime/interpolation.html "Nomad Runtime Interpolation"
[network]: /docs/job-specification/network.html "Nomad network Job Specification"
[qemu]: /docs/drivers/qemu.html "Nomad qemu Driver"

128
website/source/docs/service-discovery/index.html.md
View File

@@ -11,8 +11,8 @@ description: |-
Nomad schedules workloads of various types across a cluster of generic hosts.
Because of this, placement is not known in advance and you will need to use
service discovery to connect tasks to other services deployed across your
cluster. Nomad integrates with [Consul](https://www.consul.io) to provide
service discovery and monitoring.
cluster. Nomad integrates with [Consul][] to provide service discovery and
monitoring.
Note that in order to use Consul with Nomad, you will need to configure and
install Consul on your nodes alongside Nomad, or schedule it as a system job.
@@ -20,128 +20,29 @@ Nomad does not currently run Consul for you.
## Configuration
To configure Consul integration please see the Agent's configuration
[here](/docs/agent/config.html#consul_options).
To enable Consul integration, please see the
[Nomad agent Consul integration](/docs/agent/config.html#consul_options)
configuration.
## Service Definition Syntax
The service block in a task definition defines a service which Nomad will
register with Consul. Multiple service blocks are allowed in a task definition,
which allow registering multiple services for a task that exposes multiple
ports.
### Example
A brief example of a service definition in a task
```hcl
group "database" {
task "mysql" {
driver = "docker"
service {
tags = ["master", "mysql"]
port = "db"
check {
type = "tcp"
interval = "10s"
timeout = "2s"
}
check {
type = "script"
name = "check_table"
command = "/usr/local/bin/check_mysql_table_status"
args = ["--verbose"]
interval = "60s"
timeout = "5s"
}
}
resources {
cpu = 500
memory = 1024
network {
mbits = 10
port "db" {}
}
}
}
}
```
* `Name`: An explicit name for the Service. Nomad will replace `${JOB}`,
`${TASKGROUP}` and `${TASK}` by the name of the job, task group or task,
respectively. `${BASE}` expands to the equivalent of
`${JOB}-${TASKGROUP}-${TASK}`, and is the default name for a Service.
Each service defined for a given task must have a distinct name, so if
a task has multiple services only one of them can use the default name
and the others must be explicitly named. Names must adhere to
[RFC-1123 §2.1](https://tools.ietf.org/html/rfc1123#section-2) and are
limited to alphanumeric and hyphen characters (i.e. `[a-z0-9\-]`), and be
less than 64 characters in length.
* `tags`: A list of tags associated with this Service. String interpolation is
supported in tags.
* `port`: `port` is optional and is used to associate a port with the service.
If specified, the port label must match one defined in the resources block.
This could be a label of either a dynamic or a static port.
* `check`: A check block defines a health check associated with the service.
Multiple check blocks are allowed for a service. Nomad supports the `script`,
`http` and `tcp` Consul Checks. Script checks are not supported for the qemu
driver since the Nomad client doesn't have access to the file system of a
task using the Qemu driver.
### Check Syntax
* `type`: This indicates the check types supported by Nomad. Valid options are
currently `script`, `http` and `tcp`.
* `name`: The name of the health check.
* `interval`: This indicates the frequency of the health checks that Consul will
perform.
* `timeout`: This indicates how long Consul will wait for a health check query
to succeed.
* `path`: The path of the http endpoint which Consul will query to query the
health of a service if the type of the check is `http`. Nomad will add the IP
of the service and the port, users are only required to add the relative URL
of the health check endpoint.
* `protocol`: This indicates the protocol for the http checks. Valid options
are `http` and `https`. We default it to `http`.
* `port`: The label of the port on which the check will be performed. The label
specified here has to be defined in the resource block of the task.
* `command`: This is the command that the Nomad client runs for doing script based
health check.
* `args`: Additional arguments to the `command` for script based health checks.
* `initial_status`: An optional parameter to set the initial status of the check
Valid options are the empty string, `passing`, `warning`, and `critical`.
To configure a job to register with service discovery, please see the
[`service` job specification documentation][service].
## Assumptions
* Consul 0.6.4 or later is needed for using the Script checks.
- Consul 0.6.4 or later is needed for using the Script checks.
* Consul 0.6.0 or later is needed for using the TCP checks.
- Consul 0.6.0 or later is needed for using the TCP checks.
* The service discovery feature in Nomad depends on operators making sure that
- The service discovery feature in Nomad depends on operators making sure that
the Nomad client can reach the Consul agent.
* Nomad assumes that it controls the life cycle of all the externally
- Nomad assumes that it controls the life cycle of all the externally
discoverable services running on a host.
* Tasks running inside Nomad also need to reach out to the Consul agent if
- Tasks running inside Nomad also need to reach out to the Consul agent if
they want to use any of the Consul APIs. Ex: A task running inside a docker
container in the bridge mode won't be able to talk to a Consul Agent running
on the loopback interface of the host since the container in the bridge mode
@@ -149,3 +50,6 @@ group "database" {
network namespace of the host. There are a couple of ways to solve this, one
way is to run the container in the host networking mode, or make the Consul
agent listen on an interface in the network namespace of the container.
[consul]: https://www.consul.io/ "Consul by HashiCorp"
[service]: /docs/job-specification/service.html "Nomad service Job Specification"

3
website/source/layouts/docs.erb
View File

@@ -75,6 +75,9 @@
<li<%= sidebar_current("docs-job-specification-restart")%>>
<a href="/docs/job-specification/restart.html">restart</a>
</li>
<li<%= sidebar_current("docs-job-specification-service")%>>
<a href="/docs/job-specification/service.html">service</a>
</li>
<li<%= sidebar_current("docs-job-specification-task")%>>
<a href="/docs/job-specification/task.html">task</a>
</li>