website: document checks and services

website/source/docs/agent/checks.html.markdown

@@ -0,0 +1,62 @@
+---
+layout: "docs"
+page_title: "Check Definition"
+sidebar_current: "docs-agent-checks"
+---
+
+# Checks
+
+One of the primary roles of the agent is the management of system and
+application level health checks. A health check is considered to be application
+level if it associated with a service. A check is defined in a configuration file,
+or added at runtime over the HTTP interface.
+
+There are two different kinds of checks:
+
+ * Script + Interval - These checks depend on invoking an external application
+ which does the health check and exits with an appropriate exit code, potentially
+ generating some output. A script is paired with an invocation interval (e.g.
+ every 30 seconds). This is similar to the Nagios plugin system.
+
+ * TTL - These checks retain their last known state for a given TTL. The state
+ of the check must be updated periodicadically over the HTTP interface. If an
+ external system fails to update the status within a given TTL, the check is
+ set to the failed state. This mechanism is used to allow an application to
+ directly report it's health. For example, a web app can periodically curl the
+ endpoint, and if the app fails, then the TTL will expire and the health check
+ enters a critical state.
+
+## Check Definition
+
+A check definition that is a script looks like:
+
+    {
+        "check": {
+            "id": "mem-util",
+            "name": "Memory utilization",
+            "script": "/usr/local/bin/check_mem.py",
+            "interval": "10s"
+        }
+    }
+
+A TTL based check is very similar:
+
+    {
+        "check": {
+            "id": "web-app",
+            "name": "Web App Status",
+            "notes": "Web app does a curl internally every 10 seconds",
+            "ttl": "30s"
+        }
+    }
+
+Both types of definitions must include a `name`, and may optionally
+provide an `id` and `notes` field. The `id` is set to the `name` if not
+provided. It is required that all checks have a unique ID, so if names
+might conflict, then unique ID's should be provided.
+
+The `notes` field is opaque to Consul, but may be used for human
+readable descriptions. The field is set to any output that a script
+generates, and similarly the TTL update hooks can update the `notes`
+as well.
+

website/source/docs/agent/options.html.markdown

@@ -127,8 +127,8 @@ at a single JSON object with configuration within it.
 Configuration files are used for more than just setting up the agent,
 they are also used to provide check and service definitions. These are used
 to announce the availability of system servers to the rest of the cluster.
-They are documented seperately under [check configuration](#) and
-[service configuration](#) respectively.
+They are documented seperately under [check configuration](/docs/agent/checks.html) and
+[service configuration](/docs/agent/services.html) respectively.
 
 #### Example Configuration File
 

website/source/docs/agent/services.html.markdown

@@ -0,0 +1,54 @@
+---
+layout: "docs"
+page_title: "Service Definition"
+sidebar_current: "docs-agent-services"
+---
+
+# Services
+
+One of the main goals of service discovery is to provide a catalog of available
+services. To that end, the agent provides a simple service definition format
+to declare the availability of a service, and to potentially associate it with
+a health check. A health check is considered to be application level if it
+associated with a service. A service is defined in a configuration file,
+or added at runtime over the HTTP interface.
+
+## Service Definition
+
+A service definition that is a script looks like:
+
+    {
+        "service": {
+            "name": "redis",
+            "tag": "master",
+            "port": 8000,
+            "check": {
+                "script": "/usr/local/bin/check_redis.py",
+                "interval": "10s"
+            }
+        }
+    }
+
+A service definition must include a `name`, and may optionally provide
+an `id`, `tag`, `port`, and `check`.  The `id` is set to the `name` if not
+provided. It is required that all services have a unique ID, so if names
+might conflict, then unique ID's should be provided.
+
+The `tag` is an opaque value to Consul, but can be used to distinguish
+between "master" or "slave" nodes, or any other service level labels.
+The `port` can be used as well to make a service oriented architecture
+simpler to configure. This way the address and port of a service can
+be discovered.
+
+Lastly, a service can have an associated health check. This is a powerful
+feature as it allows a web balancer to gracefully remove failing nodes, or
+a database to replace a failed slave, etc. The health check is strongly integrated
+in the DNS interface as well. If a service is failing it's health check or
+a node has any failing system-level check, the DNS interface will omit that
+node from any service query.
+
+There is more information about [checks here](/docs/agent/checks.html). The
+check must be of the script or TTL type. If it is a script type, `script` and
+`interval` must be provided. If it is a TTL type, then only `ttl` must be
+provided. The check name is automatically generated as "service:<service-id>".
+

website/source/layouts/docs.erb

@@ -81,6 +81,14 @@
 					<a href="/docs/agent/options.html">Configuration</a>
                     </li>
 
+					<li<%= sidebar_current("docs-agent-services") %>>
+					<a href="/docs/agent/services.html">Service Definitions</a>
+                    </li>
+
+					<li<%= sidebar_current("docs-agent-checks") %>>
+					<a href="/docs/agent/checks.html">Check Definitions</a>
+					</li>
+
 					<li<%= sidebar_current("docs-agent-encryption") %>>
 					<a href="/docs/agent/encryption.html">Encryption</a>
                     </li>