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

Added the consul docs

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 = [
+                    # Request for a dynamic port
-                      "http",
+                    port "http" {
-                      "https",
+                    }
-                    ]
+                    # 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.
 

website/source/docs/jobspec/servicediscovery.html.md

@@ -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.

website/source/layouts/docs.erb

@@ -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>