github.com/iqoqo/nomad@v0.11.3-0.20200911112621-d7021c74d101/website/pages/docs/job-specification/expose.mdx (about)

     1  ---
     2  layout: docs
     3  page_title: expose Stanza - Job Specification
     4  sidebar_title: expose
     5  description: |-
     6    The "expose" stanza allows specifying options for configuring Envoy expose
     7    paths used in Consul Connect integration
     8  ---
     9  
    10  # `expose` Stanza
    11  
    12  <Placement
    13    groups={['job', 'group', 'service', 'connect', 'sidecar_service', 'proxy', 'expose']}
    14  />
    15  
    16  The `expose` stanza allows configuration of additional listeners for the default Envoy sidecar
    17  proxy managed by Nomad for [Consul Connect](/guides/integrations/consul-connect). These
    18  listeners create a bypass of the Connect TLS and network namespace isolation, enabling
    19  non-Connect enabled services to make requests to specific HTTP paths through the sidecar proxy.
    20  
    21  The `expose` configuration is valid within the context of a `proxy` stanza. Additional
    22  information about Expose Path configurations for Envoy can be found in Consul's
    23  [Expose Paths Configuration Reference](https://www.consul.io/docs/connect/registration/service-registration.html#expose-paths-configuration-reference).
    24  
    25  Service [check](https://nomadproject.io/docs/job-specification/service/#check-parameters)
    26  configurations can use their [expose](/docs/job-specification/service#expose)
    27  parameter to automatically generate expose path configurations for HTTP and gRPC checks.
    28  
    29  ```hcl
    30  job "expose-check-example" {
    31    datacenters = ["dc1"]
    32  
    33    group "api" {
    34      network {
    35        mode = "bridge"
    36      }
    37  
    38      service {
    39        name = "count-api"
    40        port = "9001"
    41  
    42        connect {
    43          sidecar_service {}
    44        }
    45  
    46        check {
    47          expose   = true
    48          name     = "api-health"
    49          type     = "http"
    50          path     = "/health"
    51          interval = "10s"
    52          timeout  = "3s"
    53        }
    54      }
    55  
    56      task "web" {
    57        driver = "docker"
    58  
    59        config {
    60          image = "hashicorpnomad/counter-api:v2"
    61        }
    62      }
    63    }
    64  }
    65  ```
    66  
    67  For uses other than Consul service checks, use the `expose` configuration in the
    68  `proxy` stanza. The example below effectively demonstrates exposing the `/health`
    69  endpoint similar to the example above, but using the fully flexible `expose`
    70  configuration.
    71  
    72  ```hcl
    73  job "expose-example" {
    74    datacenters = ["dc1"]
    75  
    76    group "api" {
    77      network {
    78        mode = "bridge"
    79  
    80        port "api_expose_healthcheck" {
    81          to = -1
    82        }
    83      }
    84  
    85      service {
    86        name = "count-api"
    87        port = "9001"
    88  
    89        connect {
    90          sidecar_service {
    91            proxy {
    92              expose {
    93                path {
    94                  path            = "/health"
    95                  protocol        = "http"
    96                  local_path_port = 9001
    97                  listener_port   = "api_expose_healthcheck"
    98                }
    99              }
   100            }
   101          }
   102        }
   103  
   104        check {
   105          name     = "api-health"
   106          type     = "http"
   107          path     = "/health"
   108          port     = "api_expose_healthcheck"
   109          interval = "10s"
   110          timeout  = "3s"
   111        }
   112      }
   113  
   114      task "web" {
   115        driver = "docker"
   116  
   117        config {
   118          image = "hashicorpnomad/counter-api:v2"
   119        }
   120  
   121        # e.g. reference ${NOMAD_PORT_api_expose_healthcheck} for other uses
   122      }
   123    }
   124  }
   125  ```
   126  
   127  ## `expose` Parameters
   128  
   129  - `path` <code>([Path]: nil)</code> - A list of [Envoy Expose Path Configurations](/docs/job-specification/path)
   130    to expose through Envoy.
   131  
   132  ### `path` Parameters
   133  
   134  - `path` `(string: required)` - The HTTP or gRPC path to expose. The path must be prefixed
   135    with a slash.
   136  - `protocol` `(string: required)` - Sets the protocol of the listener. Must be
   137    `http` or `http2`. For gRPC use `http2`.
   138  - `local_path_port` `(int: required)` - The port the service is listening to for connections to
   139     the configured `path`. Typically this will be the same as the `service.port` value, but
   140     could be different if for example the exposed path is intended to resolve to another task
   141     in the task group.
   142  - `listener_port` <code>([Port]: required)</code> - The name of the port to use
   143     for the exposed listener. The port should be configured to [map inside](/docs/job-specification/network#to)
   144     the task's network namespace.
   145  
   146  
   147  ## `expose` Examples
   148  
   149  The following example is configured to expose the `/metrics` endpoint of the Connect-enabled
   150  `count-dashboard` service, using the `HTTP` protocol. `count-dashboard` is expected
   151  to listen inside its namespace to port `9001`, and external services will be able to
   152  reach its `/metrics` endpoint by connecting to the [network interface](https://nomadproject.io/docs/configuration/client/#network_interface)
   153  of the node on the allocated `metrics` [Port](/docs/job-specification/network#port-parameters).
   154  
   155  ```hcl
   156  service {
   157    name = "count-dashboard"
   158    port = "9001"
   159  
   160    connect {
   161      sidecar_service {
   162        proxy {
   163          expose {
   164            path {
   165              path            = "/metrics"
   166              protocol        = "http"
   167              local_path_port = 9001
   168              listener_port   = "metrics"
   169            }
   170          }
   171        }
   172      }
   173    }
   174  }
   175  ```
   176  
   177  ## `path` Examples
   178  
   179  The following example is an expose configuration that exposes a `/metrics` endpoint
   180  using the `http2` protocol (typical for gRPC), and an HTTP `/v2/health` endpoint.
   181  
   182  ```hcl
   183  proxy {
   184    expose {
   185      path {
   186        path            = "/metrics"
   187        protocol        = "http2"
   188        local_path_port = 9001
   189        listener_port   = "expose"
   190      }
   191      path {
   192        path            = "/v2/health"
   193        protocol        = "http"
   194        local_path_port = 9001
   195        listener_port   = "expose"
   196      }
   197    }
   198  }
   199  ```
   200  
   201  ### Exposing Service Checks
   202  
   203  A common use case for `expose` is for exposing endpoints used in Consul service check
   204  definitions. For these cases the [expose](/docs/job-specification/service#expose)
   205  parameter in the service check stanza can be used to automatically generate the
   206  expose path configuration. Configuring a port for use by the check is optional,
   207  as a dynamic port will be automatically generated if not provided.
   208  
   209  ```hcl
   210  check {
   211    expose   = true
   212    type     = "http"
   213    name     = "dashboard-health"
   214    path     = "/health"
   215    interval = "10s"
   216    timeout  = "3s"
   217  }
   218  ```
   219  
   220  [path]: /docs/job-specification/expose#path-parameters 'Nomad Expose Path Parameters'
   221  [port]: /docs/job-specification/network#port-parameters 'Nomad Port Parameters'