luxolus
/
open-nomad
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Merge pull request #451 from hashicorp/f-consul-docs 

Added the consul docs
This commit is contained in:
Diptanu Choudhury 2015-11-18 13:36:30 -08:00
parent ad586b0749 5762f0ea01
commit edf98993b1
3 changed files with 144 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
website/source/docs/jobspec/index.html.md
View File

@ -47,6 +47,15 @@ job "my-service" {
config {
image = "hashicorp/web-frontend"
}
service {
port = "http"
check {
type = "http"
path = "/health"
interval = "10s"
timeout = "2s"
}
}
env {
DB_HOST = "db01.example.com"
DB_USER = "web"
@ -57,10 +66,13 @@ job "my-service" {
memory = 128
network {
mbits = 100
dynamic_ports = [
"http",
"https",
]
# Request for a dynamic port
port "http" {
}
# Request for a static port
port "https" {
static = 443
}
}
}
}
@ -178,6 +190,11 @@ The `task` object supports the following keys:
to start the task. The details of configurations are specific to
each driver.
* `service` - Nomad integrates with Consul for Service Discovery. A service
block represents a routable and discoverable service on the network. Nomad
automatically registers when a Task is started and de-registers it when the
Task transitons to the DEAD state. To learn more about Services please visit [here](/docs/jobspec/servicediscovery.html.md)
* `env` - A map of key/value representing environment variables that
will be passed along to the running process.

120
website/source/docs/jobspec/servicediscovery.html.md Normal file
View File

@ -0,0 +1,120 @@
---
layout: "docs"
page_title: "Service Discovery in Nomad"
sidebar_current: "docs-jobspec-service-discovery"
description: |-
Learn how to add service discovery to jobs
---
# Service Discovery
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://consul.io) 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.
Nomad does not currently run Consul for you.
## Configuration
* `consul.address`: This is a Nomad client configuration which can be used to
override the default Consul Agent HTTP port that Nomad uses to connect to
Consul. The default for this is `127.0.0.1:8500`.
## Service Definition Syntax
The service blocks 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
```
group "database" {
task "mysql" {
driver = "docker"
service {
tags = ["master", "mysql"]
port = "db"
check {
type = "tcp"
delay = "10s"
timeout = "2s"
}
}
resources {
cpu = 500
memory = 1024
network {
mbits = 10
port "db" {
}
}
}
}
}
```
* `name`: Nomad automatically determines the name of a Task. By default the
name of a service is $(job-name)-$(task-group)-$(task-name). Users can
explicitly name the service by specifying this option. If multiple services
are defined for a Task then only one task can have the default name, all the
services have to be explicitly named. Nomad will add the prefix ```$(job-name
)-${task-group}-${task-name}``` prefix to each user defined name.
* `tags`: A list of tags associated with this Service.
* `port`: The port indicates the port associated with the Service. Users are
required to specify a valid port label here which they have defined in the
resources block. This could be a label to either a dynamic or a static port.
If an incorrect port label is specified, Nomad doesn't register the service
with Consul.
* `check`: A check block defines a health check associated with the service.
Multiple check blocks are allowed for a service. Nomad currently supports
only the `http` and `tcp` Consul Checks.
### Check Syntax
* `type`: This indicates the check types supported by Nomad. Valid options are
currently `http` and `tcp`. In the future Nomad will add support for more
Consul checks.
* `delay`: This indicates the frequency of the health checks that Consul with
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`.
## Assumptions
* Consul 0.6 is needed for using the TCP checks.
* 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
discoverable services running on a host.
* Tasks running inside Nomad also needs 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
has it's own network interface and doesn't see interfaces on the global
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 on the network namespace of the container.

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

@ -41,6 +41,9 @@
<li<%= sidebar_current("docs-jobspec-schedulers") %>>
<a href="/docs/jobspec/schedulers.html">Scheduler Types</a>
</li>
<li<%= sidebar_current("docs-jobspec-service-discovery") %>>
<a href="/docs/jobspec/servicediscovery.html">Service Discovery</a>
</li>
</ul>
</li>