2020-03-20 18:22:14 +00:00
|
|
|
---
|
|
|
|
layout: docs
|
2023-01-30 14:48:43 +00:00
|
|
|
page_title: expose Block - Job Specification
|
2020-03-20 18:22:14 +00:00
|
|
|
description: |-
|
2023-01-30 14:48:43 +00:00
|
|
|
The "expose" block allows specifying options for configuring Envoy expose
|
2020-03-20 18:22:14 +00:00
|
|
|
paths used in Consul Connect integration
|
|
|
|
---
|
|
|
|
|
2023-01-30 14:48:43 +00:00
|
|
|
# `expose` Block
|
2020-03-20 18:22:14 +00:00
|
|
|
|
|
|
|
<Placement
|
2020-06-01 21:48:25 +00:00
|
|
|
groups={[
|
|
|
|
'job',
|
|
|
|
'group',
|
|
|
|
'service',
|
|
|
|
'connect',
|
|
|
|
'sidecar_service',
|
|
|
|
'proxy',
|
|
|
|
'expose',
|
|
|
|
]}
|
2020-03-20 18:22:14 +00:00
|
|
|
/>
|
|
|
|
|
2023-01-30 14:48:43 +00:00
|
|
|
The `expose` block allows configuration of additional listeners for the default
|
2020-09-29 16:48:32 +00:00
|
|
|
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.
|
2020-03-20 18:22:14 +00:00
|
|
|
|
2023-01-30 14:48:43 +00:00
|
|
|
The `expose` configuration is valid within the context of a `proxy` block.
|
2020-09-29 16:48:32 +00:00
|
|
|
Additional information about Expose Path configurations for Envoy can be found
|
|
|
|
in Consul's [Expose Paths Configuration Reference][consul-expose-path-config].
|
2020-03-20 18:22:14 +00:00
|
|
|
|
2020-09-29 16:48:32 +00:00
|
|
|
Service [check][] configurations can use their [expose][] parameter to
|
|
|
|
automatically generate expose path configurations for HTTP and gRPC checks.
|
2020-03-20 18:22:14 +00:00
|
|
|
|
2020-05-07 17:03:37 +00:00
|
|
|
```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 {
|
2022-06-08 19:06:00 +00:00
|
|
|
image = "hashicorpdev/counter-api:v3"
|
2020-05-07 17:03:37 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
For uses other than Consul service checks, use the `expose` configuration in the
|
2023-01-30 14:48:43 +00:00
|
|
|
`proxy` block. The example below effectively demonstrates exposing the
|
2020-09-29 16:48:32 +00:00
|
|
|
`/health` endpoint similar to the example above, but using the fully flexible
|
|
|
|
`expose` configuration.
|
2020-05-07 17:03:37 +00:00
|
|
|
|
2020-03-20 18:22:14 +00:00
|
|
|
```hcl
|
|
|
|
job "expose-example" {
|
|
|
|
datacenters = ["dc1"]
|
2020-05-07 17:03:37 +00:00
|
|
|
|
|
|
|
group "api" {
|
2020-03-20 18:22:14 +00:00
|
|
|
network {
|
|
|
|
mode = "bridge"
|
2020-05-07 17:03:37 +00:00
|
|
|
|
|
|
|
port "api_expose_healthcheck" {
|
2020-03-20 18:22:14 +00:00
|
|
|
to = -1
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
service {
|
2020-05-07 17:03:37 +00:00
|
|
|
name = "count-api"
|
2020-03-20 18:22:14 +00:00
|
|
|
port = "9001"
|
|
|
|
|
|
|
|
connect {
|
|
|
|
sidecar_service {
|
|
|
|
proxy {
|
|
|
|
expose {
|
|
|
|
path {
|
2020-05-07 17:03:37 +00:00
|
|
|
path = "/health"
|
2020-03-20 18:22:14 +00:00
|
|
|
protocol = "http"
|
|
|
|
local_path_port = 9001
|
2020-05-07 17:03:37 +00:00
|
|
|
listener_port = "api_expose_healthcheck"
|
2020-03-20 18:22:14 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
2020-04-02 22:42:38 +00:00
|
|
|
|
|
|
|
check {
|
2020-05-07 17:03:37 +00:00
|
|
|
name = "api-health"
|
2020-04-02 22:42:38 +00:00
|
|
|
type = "http"
|
|
|
|
path = "/health"
|
2020-05-07 17:03:37 +00:00
|
|
|
port = "api_expose_healthcheck"
|
2020-04-02 22:42:38 +00:00
|
|
|
interval = "10s"
|
|
|
|
timeout = "3s"
|
|
|
|
}
|
2020-03-20 18:22:14 +00:00
|
|
|
}
|
2020-05-07 17:03:37 +00:00
|
|
|
|
|
|
|
task "web" {
|
|
|
|
driver = "docker"
|
|
|
|
|
|
|
|
config {
|
2022-06-08 19:06:00 +00:00
|
|
|
image = "hashicorpdev/counter-api:v3"
|
2020-05-07 17:03:37 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
# e.g. reference ${NOMAD_PORT_api_expose_healthcheck} for other uses
|
|
|
|
}
|
2020-03-20 18:22:14 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
## `expose` Parameters
|
|
|
|
|
2020-09-29 16:48:32 +00:00
|
|
|
- `path` <code>([Path]: nil)</code> - A list of [Envoy Expose Path Configurations][expose_path]
|
2020-03-20 18:22:14 +00:00
|
|
|
to expose through Envoy.
|
|
|
|
|
|
|
|
### `path` Parameters
|
|
|
|
|
|
|
|
- `path` `(string: required)` - The HTTP or gRPC path to expose. The path must be prefixed
|
|
|
|
with a slash.
|
2020-09-29 16:48:32 +00:00
|
|
|
|
2020-03-20 18:22:14 +00:00
|
|
|
- `protocol` `(string: required)` - Sets the protocol of the listener. Must be
|
|
|
|
`http` or `http2`. For gRPC use `http2`.
|
2020-09-29 16:48:32 +00:00
|
|
|
|
2020-03-20 18:22:14 +00:00
|
|
|
- `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.
|
2020-09-29 16:48:32 +00:00
|
|
|
|
2020-03-20 18:22:14 +00:00
|
|
|
- `listener_port` <code>([Port]: required)</code> - The name of the port to use
|
2020-09-29 16:48:32 +00:00
|
|
|
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.
|
2020-03-20 18:22:14 +00:00
|
|
|
|
|
|
|
## `expose` Examples
|
|
|
|
|
2020-09-29 16:48:32 +00:00
|
|
|
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][].
|
2020-03-20 18:22:14 +00:00
|
|
|
|
|
|
|
```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
|
|
|
|
|
2020-09-29 16:48:32 +00:00
|
|
|
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.
|
2020-03-20 18:22:14 +00:00
|
|
|
|
|
|
|
```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
|
|
|
|
|
2020-09-29 16:48:32 +00:00
|
|
|
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
|
2023-01-30 14:48:43 +00:00
|
|
|
block can be used to automatically generate the expose path configuration.
|
2020-09-29 16:48:32 +00:00
|
|
|
Configuring a port for use by the check is optional, as a dynamic port will be
|
|
|
|
automatically generated if not provided.
|
2020-03-20 18:22:14 +00:00
|
|
|
|
2020-04-02 22:42:38 +00:00
|
|
|
```hcl
|
|
|
|
check {
|
2020-05-07 17:03:37 +00:00
|
|
|
expose = true
|
2020-04-02 22:42:38 +00:00
|
|
|
type = "http"
|
|
|
|
name = "dashboard-health"
|
|
|
|
path = "/health"
|
|
|
|
interval = "10s"
|
|
|
|
timeout = "3s"
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2023-01-25 17:31:14 +00:00
|
|
|
[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
|