diff --git a/website/source/docs/jobspec/index.html.md b/website/source/docs/jobspec/index.html.md index cffc04ed1..1a3a6b216 100644 --- a/website/source/docs/jobspec/index.html.md +++ b/website/source/docs/jobspec/index.html.md @@ -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,12 @@ 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 rotable 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. See the Service Discovery section + for more details. 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. diff --git a/website/source/docs/jobspec/servicediscovery.html.md b/website/source/docs/jobspec/servicediscovery.html.md new file mode 100644 index 000000000..08297a4dc --- /dev/null +++ b/website/source/docs/jobspec/servicediscovery.html.md @@ -0,0 +1,123 @@ +--- +layout: "docs" +page_title: "Service Discovery in Nomad" +sidebar_current: "docs-service-discovery" +description: |- + Learn how to add service discovery to jobs + --- + +# Service Discovery + +Nomad enables dynamic scheduling on compute resources to run services at scale +on compute nodes. Compute nodes, size of an application cluster varies depending +on volume of traffic etc, thereby the network topology of services constanly +changing. This introduces the challenge of discovery of services, Nomad solves +this problem by integrating with [Consul](https://consul.io) to provide service +discovery and health checks of services. + +Operators have to run Consul agents on a Nomad compute node.Nomad also makes +running an application like Consul agent on every single node in a data centre +simple by providing system jobs. Nomad connects to Consul on it's default http +port but operators can override it. + +## Configuration + +* `consul.address`: This is a Nomad client config 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 Deginition 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 deginition, +which makes it usable for cases when an application listens on multiple ports +each exposing a specific service. + +### 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" + } + } + reources { + 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 explictly + name the service by specifying this option. + +* `tags`: A list of tags associated with this Service. + +* `port`: The port indicated the port associated with the Service. Users are + reruired 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 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. + Mutliple 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 + +* 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 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 + namespaces. 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. + + + + + +