docs: document grpc health check support

CHANGELOG.md

@@ -1,8 +1,9 @@
 ## 0.8.4 (Unreleased)
 
 IMPROVEMENTS:
- * command: add -short option to init command that emits a minimal
+ * command: Add -short option to init command that emits a minimal
    jobspec [[GH-4239](https://github.com/hashicorp/nomad/issues/4239)]
+ * discovery: Support Consul gRPC health checks. [[GH-4251](https://github.com/hashicorp/nomad/issues/4251)]
 
 ## 0.8.3 (April 27, 2018)
 

website/source/docs/job-specification/service.html.md

@@ -72,7 +72,7 @@ does not automatically enable service discovery.
 - `check` <code>([Check](#check-parameters): nil)</code> - Specifies a health
   check associated with the service. This can be specified multiple times to
   define multiple checks for the service. At this time, Nomad supports the
-  `script`<sup><small>1</small></sup>, `http` and `tcp` checks.
+  `grpc`, `http`, `script`<sup><small>1</small></sup>, and `tcp` checks.
 
 - `name` `(string: "<job>-<group>-<task>")` - Specifies the name this service
   will be advertised as in Consul.  If not supplied, this will default to the
@@ -160,6 +160,12 @@ scripts.
     parameter. To achieve the behavior of shell operators, specify the command
     as a shell, like `/bin/bash` and then use `args` to run the check.
 
+- `grpc_service` `(string: <optional>)` - What service, if any, to specify in
+  the gRPC health check. gRPC health checks require Consul 1.0.5 or later.
+
+- `grpc_use_tls` `(bool: false)` - Use TLS to perform a gRPC health check. May
+  be used with `tls_skip_verify` to use TLS but skip certificate verification.
+
 - `initial_status` `(string: <enum>)` - Specifies the originating status of the
   service. Valid options are the empty string, `passing`, `warning`, and
   `critical`.
@@ -186,9 +192,9 @@ scripts.
   in the [`network`][network] stanza. If a port value was declared on the
   `service`, this will inherit from that value if not supplied. If supplied,
   this value takes precedence over the `service.port` value. This is useful for
-  services which operate on multiple ports. `http` and `tcp` checks require a
-  port while `script` checks do not. Checks will use the host IP and ports by
-  default. In Nomad 0.7.1 or later numeric ports may be used if
+  services which operate on multiple ports. `grpc`, `http`, and `tcp` checks
+  require a port while `script` checks do not. Checks will use the host IP and
+  ports by default. In Nomad 0.7.1 or later numeric ports may be used if
   `address_mode="driver"` is set on the check.
 
 - `protocol` `(string: "http")` - Specifies the protocol for the http-based
@@ -199,7 +205,8 @@ scripts.
   "30s" or "1h". This must be greater than or equal to "1s"
 
 - `type` `(string: <required>)` - This indicates the check types supported by
-  Nomad. Valid options are `script`, `http`, and `tcp`.
+  Nomad. Valid options are `grpc`, `http`, `script`, and `tcp`. gRPC health
+  checks require Consul 1.0.5 or later.
 
 - `tls_skip_verify` `(bool: false)` - Skip verifying TLS certificates for HTTPS
   checks. Requires Consul >= 0.7.2.
@@ -355,6 +362,33 @@ service {
 }
 ```
 
+### gRPC Health Check
+
+gRPC health checks use the same host and port behavior as `http` and `tcp`
+checks, but gRPC checks also have an optional gRPC service to health check. Not
+all gRPC applications require a service to health check. gRPC health checks
+require Consul 1.0.5 or later.
+
+```hcl
+service {
+  check {
+    type            = "grpc"
+    port            = "rpc"
+    interval        = "5s"
+    timeout         = "2s"
+    grpc_service    = "grpc.health.v1.Health"
+    grpc_use_tls    = true
+    tls_skip_verify = true
+  }
+}
+```
+
+This check would translate to having a Consul check registration with the
+[GRPC][consul_grpc] parameter similar to `10.0.3.1:4567/grpc.health.v1.Health`.
+Assuming the service's address is `10.0.3.1` and port is `4567`. See [Using
+Driver Address Mode](#using-driver-address-mode) for details on address
+selection.
+
 ### Using Driver Address Mode
 
 The [Docker](/docs/drivers/docker.html#network_mode) and
@@ -582,6 +616,7 @@ advertise and check directly since Nomad isn't managing any port assignments.
 system of a task for that driver.</small>
 
 [check_restart_stanza]: /docs/job-specification/check_restart.html "check_restart stanza"
+[consul_grpc]: https://www.consul.io/api/agent/check.html#grpc
 [service-discovery]: /docs/service-discovery/index.html "Nomad Service Discovery"
 [interpolation]: /docs/runtime/interpolation.html "Nomad Runtime Interpolation"
 [network]: /docs/job-specification/network.html "Nomad network Job Specification"