open-nomad/website/content/docs/job-specification/upstreams.mdx
Ashlee M Boyer 57f8ebfa26
docs: Migrate link formats (#15779)
* Adding check-legacy-links-format workflow

* Adding test-link-rewrites workflow

* chore: updates link checker workflow hash

* Migrating links to new format

Co-authored-by: Kendall Strautman <kendallstrautman@gmail.com>
2023-01-25 09:31:14 -08:00

142 lines
4.8 KiB
Plaintext

---
layout: docs
page_title: upstreams Stanza - Job Specification
description: |-
The "upstreams" stanza allows specifying options for configuring
upstream services
---
# `upstreams` Stanza
<Placement
groups={[
'job',
'group',
'service',
'connect',
'sidecar_service',
'proxy',
'upstreams',
]}
/>
The `upstreams` stanza allows configuring various options for managing upstream
services that a [Consul
Connect](/nomad/docs/integrations/consul-connect) proxy routes to. It
is valid only within the context of a `proxy` stanza.
For Consul-specific details see the [Consul Connect
Guide](/consul/tutorials/get-started-vms/virtual-machine-gs-service-discovery).
```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"
}
}
}
}
```
## `upstreams` Parameters
- `destination_name` `(string: <required>)` - Name of the upstream service.
- `destination_namespace` `(string: <required>)` - Name of the upstream Consul namespace.
- `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.
- `mesh_gateway` <code>([mesh_gateway][mesh_gateway_param]: nil)</code> - Configures the mesh gateway
behavior for connecting to this upstream.
- `config` `(map: nil)` - Upstream configuration that is opaque to Nomad and passed
directly to Consul. See [Consul Connect documentation](/consul/docs/connect/registration/service-registration#upstream-configuration-reference)
for details. Keys and values support [runtime variable interpolation][interpolation].
### `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.
## `upstreams` 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
}
```
[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