open-nomad/website/content/docs/job-specification/expose.mdx

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

240 lines
6.1 KiB
Plaintext
Raw Normal View History

---
layout: docs
page_title: expose Block - Job Specification
description: |-
The "expose" block allows specifying options for configuring Envoy expose
paths used in Consul Connect integration
---
# `expose` Block
<Placement
2020-06-01 21:48:25 +00:00
groups={[
'job',
'group',
'service',
'connect',
'sidecar_service',
'proxy',
'expose',
]}
/>
The `expose` block allows configuration of additional listeners for the default
Envoy sidecar proxy managed by Nomad for [Consul Connect][learn-consul-connect].
These listeners create a bypass of the Connect TLS and network namespace
isolation, enabling non-Connect enabled services to make requests to specific
HTTP paths through the sidecar proxy.
The `expose` configuration is valid within the context of a `proxy` block.
Additional information about Expose Path configurations for Envoy can be found
in Consul's [Expose Paths Configuration Reference][consul-expose-path-config].
Service [check][] configurations can use their [expose][] parameter to
automatically generate expose path configurations for HTTP and gRPC checks.
```hcl
job "expose-check-example" {
datacenters = ["dc1"]
group "api" {
network {
mode = "bridge"
}
service {
name = "count-api"
port = "9001"
connect {
sidecar_service {}
}
check {
expose = true
name = "api-health"
type = "http"
path = "/health"
interval = "10s"
timeout = "3s"
}
}
task "web" {
driver = "docker"
config {
image = "hashicorpdev/counter-api:v3"
}
}
}
}
```
For uses other than Consul service checks, use the `expose` configuration in the
`proxy` block. The example below effectively demonstrates exposing the
`/health` endpoint similar to the example above, but using the fully flexible
`expose` configuration.
```hcl
job "expose-example" {
datacenters = ["dc1"]
group "api" {
network {
mode = "bridge"
port "api_expose_healthcheck" {
to = -1
}
}
service {
name = "count-api"
port = "9001"
connect {
sidecar_service {
proxy {
expose {
path {
path = "/health"
protocol = "http"
local_path_port = 9001
listener_port = "api_expose_healthcheck"
}
}
}
}
}
check {
name = "api-health"
type = "http"
path = "/health"
port = "api_expose_healthcheck"
interval = "10s"
timeout = "3s"
}
}
task "web" {
driver = "docker"
config {
image = "hashicorpdev/counter-api:v3"
}
# e.g. reference ${NOMAD_PORT_api_expose_healthcheck} for other uses
}
}
}
```
## `expose` Parameters
- `path` <code>([Path]: nil)</code> - A list of [Envoy Expose Path Configurations][expose_path]
to expose through Envoy.
### `path` Parameters
- `path` `(string: required)` - The HTTP or gRPC path to expose. The path must be prefixed
with a slash.
- `protocol` `(string: required)` - Sets the protocol of the listener. Must be
`http` or `http2`. For gRPC use `http2`.
- `local_path_port` `(int: required)` - The port the service is listening to for connections to
2020-06-01 21:48:25 +00:00
the configured `path`. Typically this will be the same as the `service.port` value, but
could be different if for example the exposed path is intended to resolve to another task
in the task group.
- `listener_port` <code>([Port]: required)</code> - The name of the port to use
for the exposed listener. The port should be configured to [map inside][network-to]
2020-06-01 21:48:25 +00:00
the task's network namespace.
## `expose` Examples
The following example is configured to expose the `/metrics` endpoint of the
Connect-enabled `count-dashboard` service, using the `HTTP` protocol.
`count-dashboard` is expected to listen inside its namespace to port `9001`, and
external services will be able to reach its `/metrics` endpoint by connecting to
the [network interface][network_interface] of the node on the allocated
`metrics` [Port][].
```hcl
service {
name = "count-dashboard"
port = "9001"
connect {
sidecar_service {
proxy {
expose {
path {
path = "/metrics"
protocol = "http"
local_path_port = 9001
listener_port = "metrics"
}
}
}
}
}
}
```
## `path` Examples
The following example is an expose configuration that exposes a `/metrics`
endpoint using the `http2` protocol (typical for gRPC), and an HTTP `/v2/health`
endpoint.
```hcl
proxy {
expose {
path {
path = "/metrics"
protocol = "http2"
local_path_port = 9001
listener_port = "expose"
}
path {
path = "/v2/health"
protocol = "http"
local_path_port = 9001
listener_port = "expose"
}
}
}
```
### Exposing Service Checks
A common use case for `expose` is for exposing endpoints used in Consul service
check definitions. For these cases the [expose][] parameter in the service check
block can be used to automatically generate the expose path configuration.
Configuring a port for use by the check is optional, as a dynamic port will be
automatically generated if not provided.
```hcl
check {
expose = true
type = "http"
name = "dashboard-health"
path = "/health"
interval = "10s"
timeout = "3s"
}
```
[network-to]: /nomad/docs/job-specification/network#to
[consul-expose-path-config]: /consul/docs/connect/registration/service-registration#expose-paths-configuration-reference
[expose-path]: /nomad/docs/job-specification/expose#path-1
[expose]: /nomad/docs/job-specification/service#expose
[path]: /nomad/docs/job-specification/expose#path-parameters 'Nomad Expose Path Parameters'
[port]: /nomad/docs/job-specification/network#port-parameters 'Nomad Port Parameters'
[network_interface]: /nomad/docs/configuration/client#network_interface
[learn-consul-connect]: /nomad/tutorials/integrate-consul/consul-service-mesh
[check]: /nomad/docs/job-specification/service#check-parameters