diff --git a/CHANGELOG.md b/CHANGELOG.md
index d2f25f3f65a7..fa8dcfec7907 100644
--- a/CHANGELOG.md
+++ b/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)
diff --git a/website/source/docs/job-specification/service.html.md b/website/source/docs/job-specification/service.html.md
index 2c465ca48b57..f83b30afbcdd 100644
--- a/website/source/docs/job-specification/service.html.md
+++ b/website/source/docs/job-specification/service.html.md
@@ -72,7 +72,7 @@ does not automatically enable service discovery.
- `check` ([Check](#check-parameters): nil)
- 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`1, `http` and `tcp` checks.
+ `grpc`, `http`, `script`1, and `tcp` checks.
- `name` `(string: "--")` - 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: )` - 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: )` - 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: )` - 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.
[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"