---
layout: docs
page_title: upstreams block in the job specification
description: |-
  The `upstreams` block allows specifying options for configuring
  upstream services
---

# `upstreams` block in the job specification

<Placement
  groups={[
    'job',
    'group',
    'service',
    'connect',
    'sidecar_service',
    'proxy',
    'upstreams',
  ]}
/>

The `upstreams` block allows configuring various options for managing upstream
services that a [Consul Connect][] proxy routes to. It is valid only within the
context of a `proxy` block.

For Consul-specific details see the [Consul Connect Guide][]. Note that using
`upstream` may not be necessary if you have configured the proxy with the
[`transparent_proxy`][] block.

```hcl
job "countdash" {
  datacenters = ["dc1"]

  group "dashboard" {
    network {
      mode = "bridge"

      port "http" {
        static = 9002
        to     = 9002
      }
    }

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

      connect {
        sidecar_service {
          proxy {
            upstreams {
              destination_name = "count-api"
              local_bind_port  = 8080
              datacenter = "dc2"
              local_bind_address = "127.0.0.1"
              mesh_gateway {
                mode = "local"
              }
            }
          }
        }
      }
    }

    task "dashboard" {
      driver = "docker"

      env {
        COUNTING_SERVICE_URL = "http://${NOMAD_UPSTREAM_ADDR_count_api}"
      }

      config {
        image = "hashicorpdev/counter-dashboard:v3"
      }
    }
  }
}

```

## Parameters

- `config` `(map: nil)` - Upstream configuration that is opaque to Nomad and passed
  directly to Consul. See [Consul Connect documentation][consul_expose_path_ref]
  for details. Keys and values support [runtime variable interpolation][interpolation].
- `destination_name` `(string: <required>)` - Name of the upstream service.
- `destination_namespace` `(string: <required>)` - Name of the upstream Consul namespace.
- `destination_partition` `(string: "")` - Name of the Cluster admin partition containing the upstream service.
- `destination_peer` `(string: "")` - Name of the peer cluster containing the upstream service.
- `destination_type` - `(string: "service")` - The type of discovery query the proxy should use for finding service mesh instances.
- `local_bind_port` - `(int: <required>)` - The port the proxy will receive
  connections for the upstream on.
- `datacenter` `(string: "")` - The Consul datacenter in which to issue the
  discovery query. Defaults to the empty string, which Consul interprets as the
  local Consul datacenter.
- `local_bind_address` - `(string: "")` - The address the proxy will receive
  connections for the upstream on.
- `local_bind_socket_mode` - `(string: "")` - Unix octal that configures file permissions for the socket.
- `local_bind_socket_path` - `(string: "")` - The path at which to bind a Unix domain socket listener.
- `mesh_gateway` <code>([mesh_gateway][mesh_gateway_param]: nil)</code> - Configures the mesh gateway
  behavior for connecting to this upstream.

### `mesh_gateway` Parameters

- `mode` `(string: "")` - The mode of operation in which to use [Connect Mesh Gateways][mesh_gateways].
  If left unset, the mode will default to the mode as determined by the Consul [service-defaults][service_defaults_mode]
  configuration for the service. Can be configured with the following modes:
  - `local` - In this mode the Connect proxy makes its outbound connection to a
  gateway running in the same datacenter. That gateway is then responsible for
  ensuring the data gets forwarded along to gateways in the destination datacenter.
  - `remote` - In this mode the Connect proxy makes its outbound connection to a
  gateway running in the destination datacenter. That gateway will then forward
  the data to the final destination service.
  - `none` - In this mode, no gateway is used and a Connect proxy makes its
  outbound connections directly to the destination services.

The `NOMAD_UPSTREAM_ADDR_<destination_name>` environment variables may be used
to interpolate the upstream's `host:port` address.

Applications are encouraged to connect to `127.0.0.1` and a well defined port
(eg 6379 for Redis) by default. Then when using Consul Connect the application
can be deployed with the Redis upstream's `local_bind_port = 6379` and require
no explicit configuration.

## Examples

The following example is an upstream config with the name of the destination service
and a local bind port.

```hcl
    upstreams {
      destination_name = "count-api"
      local_bind_port = 8080
    }
```

[Consul Connect]: /nomad/docs/integrations/consul-connect
[Consul Connect Guide]: /consul/tutorials/get-started-vms/virtual-machine-gs-service-discovery
[`transparent_proxy`]: /nomad/docs/job-specification/transparent_proxy
[job]: /nomad/docs/job-specification/job 'Nomad job Job Specification'
[group]: /nomad/docs/job-specification/group 'Nomad group Job Specification'
[task]: /nomad/docs/job-specification/task 'Nomad task Job Specification'
[interpolation]: /nomad/docs/runtime/interpolation 'Nomad interpolation'
[sidecar_service]: /nomad/docs/job-specification/sidecar_service 'Nomad sidecar service Specification'
[upstreams]: /nomad/docs/job-specification/upstreams 'Nomad upstream config Specification'
[service_defaults_mode]: /consul/docs/connect/config-entries/service-defaults#meshgateway
[mesh_gateway_param]: /nomad/docs/job-specification/upstreams#mesh_gateway-parameters
[mesh_gateways]: /consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-datacenters#mesh-gateways
[consul_expose_path_ref]: /consul/docs/connect/proxies/proxy-config-reference#expose-paths-configuration-reference