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 = [
-                      "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.
 

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