expose block in the job specification

The expose block allows configuration of additional listeners for the default Envoy sidecar proxy managed by Nomad for Consul service mesh. 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.

Service check configurations can use their expose parameter to automatically generate expose path configurations for HTTP and gRPC checks.

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.

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
    }
  }
}

Parameters

• path (Path: nil) - A list of Envoy expose path configurations 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 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 (Port: required) - The name of the port to use for the exposed listener. The port should be configured to map inside the task's network namespace.

Examples

The following example exposes 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 of the node on the allocated metrics Port.

service {
  name = "count-dashboard"
  port = "9001"

  connect {
    sidecar_service {
      proxy {
        expose {
          path {
            path            = "/metrics"
            protocol        = "http"
            local_path_port = 9001
            listener_port   = "metrics"
          }
        }
      }
    }
  }
}

The following example exposes a /metrics endpoint using the http2 protocol (typical for gRPC), and an HTTP /v2/health endpoint.

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.

check {
  expose   = true
  type     = "http"
  name     = "dashboard-health"
  path     = "/health"
  interval = "10s"
  timeout  = "3s"
}