upstreams.mdx

layout	page_title	description
docs	upstreams Block - Job Specification	The "upstreams" block allows specifying options for configuring upstream services

upstreams Block

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

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

• config (map: nil) - Upstream configuration that is opaque to Nomad and passed directly to Consul. See Consul Connect documentation for details. Keys and values support runtime variable 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 (mesh_gateway: nil) - 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. If left unset, the mode will default to the mode as determined by the Consul service-defaults 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.

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