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"