From 464d5c55971cb74df1feb334e5d77cf8d8f6931c Mon Sep 17 00:00:00 2001 From: Diptanu Choudhury Date: Wed, 18 Nov 2015 12:14:28 -0800 Subject: [PATCH 1/9] Added the consul docs --- website/source/docs/jobspec/index.html.md | 26 +++- .../docs/jobspec/servicediscovery.html.md | 123 ++++++++++++++++++ 2 files changed, 145 insertions(+), 4 deletions(-) create mode 100644 website/source/docs/jobspec/servicediscovery.html.md 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. + + + + + + From 5836f653e31c5ea7ec34f775e9d4a70418bb9115 Mon Sep 17 00:00:00 2001 From: Diptanu Choudhury Date: Wed, 18 Nov 2015 12:16:03 -0800 Subject: [PATCH 2/9] Fixed some typo --- website/source/docs/jobspec/index.html.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/website/source/docs/jobspec/index.html.md b/website/source/docs/jobspec/index.html.md index 1a3a6b216..5a99bf636 100644 --- a/website/source/docs/jobspec/index.html.md +++ b/website/source/docs/jobspec/index.html.md @@ -191,10 +191,9 @@ The `task` object supports the following keys: each driver. * `service` - Nomad integrates with Consul for Service Discovery. A service - block represents a rotable and discoverable service on the network. Nomad + 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. See the Service Discovery section - for more details. To learn more about Services please visit [here](/docs/jobspec/servicediscovery.html.md) + 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. From 5ba786118004782a158e7a2deade9b1eccaf99d7 Mon Sep 17 00:00:00 2001 From: Diptanu Choudhury Date: Wed, 18 Nov 2015 12:19:20 -0800 Subject: [PATCH 3/9] Fixed more typos and changed some sentences --- .../source/docs/jobspec/servicediscovery.html.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/website/source/docs/jobspec/servicediscovery.html.md b/website/source/docs/jobspec/servicediscovery.html.md index 08297a4dc..91a848d22 100644 --- a/website/source/docs/jobspec/servicediscovery.html.md +++ b/website/source/docs/jobspec/servicediscovery.html.md @@ -9,13 +9,13 @@ description: |- # 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 +on compute nodes. Size of an application cluster varies depending +on volume of traffic, health of services, etc thereby the network topology of +services are 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 +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. @@ -29,7 +29,7 @@ port but operators can override it. ## 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, +register with Consul. Multiple Service blocks are allowed in a Task definition, which makes it usable for cases when an application listens on multiple ports each exposing a specific service. @@ -69,7 +69,7 @@ group "database" { * `tags`: A list of tags associated with this Service. -* `port`: The port indicated the port associated with the Service. Users are +* `port`: The port indicates 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 From a3f00b8aa3aafbbac78d8f63a4150cee5a042c08 Mon Sep 17 00:00:00 2001 From: Diptanu Choudhury Date: Wed, 18 Nov 2015 12:22:48 -0800 Subject: [PATCH 4/9] Added more explanation to name --- website/source/docs/jobspec/servicediscovery.html.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/website/source/docs/jobspec/servicediscovery.html.md b/website/source/docs/jobspec/servicediscovery.html.md index 91a848d22..af3d84a59 100644 --- a/website/source/docs/jobspec/servicediscovery.html.md +++ b/website/source/docs/jobspec/servicediscovery.html.md @@ -63,15 +63,18 @@ group "database" { ``` -* `name`: Nomad automatically determines the name of a Task By default the name +* `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. + name the service by specifying this option. If multiple services are defined + for a Task then all the services have to be explictly named. Nomad will add + the prefix $(job-name)-${task-group}-${task-name} prefix to each user defined + names. * `tags`: A list of tags associated with this Service. * `port`: The port indicates 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 + 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. @@ -101,6 +104,8 @@ group "database" { ## 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. From 6b86965e60bfc0b454a3df53b5cd345a55b7a50f Mon Sep 17 00:00:00 2001 From: Diptanu Choudhury Date: Wed, 18 Nov 2015 12:24:25 -0800 Subject: [PATCH 5/9] More grammer fixes --- website/source/docs/jobspec/servicediscovery.html.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/source/docs/jobspec/servicediscovery.html.md b/website/source/docs/jobspec/servicediscovery.html.md index af3d84a59..4c23225f5 100644 --- a/website/source/docs/jobspec/servicediscovery.html.md +++ b/website/source/docs/jobspec/servicediscovery.html.md @@ -113,11 +113,11 @@ group "database" { 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 + 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 - namespaces. There are a couple of ways to solve this, one way is to run the + 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. From 8c5900031d8d64deac701b609fdaf6d969100c32 Mon Sep 17 00:00:00 2001 From: Diptanu Choudhury Date: Wed, 18 Nov 2015 13:15:47 -0800 Subject: [PATCH 6/9] changed the intro --- .../docs/jobspec/servicediscovery.html.md | 39 +++++++++---------- website/source/layouts/docs.erb | 3 ++ 2 files changed, 21 insertions(+), 21 deletions(-) diff --git a/website/source/docs/jobspec/servicediscovery.html.md b/website/source/docs/jobspec/servicediscovery.html.md index 4c23225f5..6a0266587 100644 --- a/website/source/docs/jobspec/servicediscovery.html.md +++ b/website/source/docs/jobspec/servicediscovery.html.md @@ -8,30 +8,27 @@ description: |- # Service Discovery -Nomad enables dynamic scheduling on compute resources to run services at scale -on compute nodes. Size of an application cluster varies depending -on volume of traffic, health of services, etc thereby the network topology of -services are 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. +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. -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. +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 config which can be used to override +* `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 Deginition Syntax +## 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 makes it usable for cases when an application listens on multiple ports -each exposing a specific service. +which allow registering multiple services for a task that exposes multiple ports. ### Example @@ -49,7 +46,7 @@ group "database" { timeout = "2s" } } - reources { + resources { cpu = 500 memory = 1024 network { @@ -64,22 +61,22 @@ group "database" { ``` * `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 + 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 all the services have to be explictly named. Nomad will add - the prefix $(job-name)-${task-group}-${task-name} prefix to each user defined - names. + 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 - reruired to specify a valid port label here which they have defined in the + 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. - Mutliple check blocks are allowed for a service. Nomad currently supports only + Multiple check blocks are allowed for a service. Nomad currently supports only the `http` and `tcp` Consul Checks. ### Check Syntax diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 115623599..37769709f 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -41,6 +41,9 @@ > Scheduler Types + > + Service Discovery + From 71405b9d387478f6cda47d1b8d8e5a7d8102625d Mon Sep 17 00:00:00 2001 From: Chris Bednarski Date: Wed, 18 Nov 2015 13:20:23 -0800 Subject: [PATCH 7/9] Reformat --- .../docs/jobspec/servicediscovery.html.md | 69 +++++++++---------- 1 file changed, 32 insertions(+), 37 deletions(-) diff --git a/website/source/docs/jobspec/servicediscovery.html.md b/website/source/docs/jobspec/servicediscovery.html.md index 6a0266587..c156ec574 100644 --- a/website/source/docs/jobspec/servicediscovery.html.md +++ b/website/source/docs/jobspec/servicediscovery.html.md @@ -20,17 +20,18 @@ 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" +* `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. +which allow registering multiple services for a task that exposes multiple +ports. -### Example +### Example A brief example of a service definition in a Task ``` @@ -60,26 +61,27 @@ group "database" { ``` -* `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. +* `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. + 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. + Multiple check blocks are allowed for a service. Nomad currently supports + only the `http` and `tcp` Consul Checks. + +### Check Syntax -### 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. @@ -95,31 +97,24 @@ group "database" { 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`. +* `protocol`: This indicates the protocol for the http checks. Valid options + are `http` and `https`. - -## Assumptions +## 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. +* 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. - - - - - - +* 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. From 455842f2820528383aecccafded193582cd0d00b Mon Sep 17 00:00:00 2001 From: Diptanu Choudhury Date: Wed, 18 Nov 2015 13:22:43 -0800 Subject: [PATCH 8/9] Removed blank lines --- website/source/docs/jobspec/servicediscovery.html.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/website/source/docs/jobspec/servicediscovery.html.md b/website/source/docs/jobspec/servicediscovery.html.md index 6a0266587..799412ce6 100644 --- a/website/source/docs/jobspec/servicediscovery.html.md +++ b/website/source/docs/jobspec/servicediscovery.html.md @@ -117,9 +117,3 @@ group "database" { 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. - - - - - - From 3aa7a6865d5092c6ef6508cc442051f8da4bd0aa Mon Sep 17 00:00:00 2001 From: Diptanu Choudhury Date: Wed, 18 Nov 2015 13:35:16 -0800 Subject: [PATCH 9/9] Fixed the sidebar-current --- website/source/docs/jobspec/servicediscovery.html.md | 2 +- website/source/layouts/docs.erb | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/website/source/docs/jobspec/servicediscovery.html.md b/website/source/docs/jobspec/servicediscovery.html.md index 799412ce6..212b688a7 100644 --- a/website/source/docs/jobspec/servicediscovery.html.md +++ b/website/source/docs/jobspec/servicediscovery.html.md @@ -1,7 +1,7 @@ --- layout: "docs" page_title: "Service Discovery in Nomad" -sidebar_current: "docs-service-discovery" +sidebar_current: "docs-jobspec-service-discovery" description: |- Learn how to add service discovery to jobs --- diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 37769709f..5d4fe4f36 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -41,7 +41,7 @@ > Scheduler Types - > + > Service Discovery