Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 37 ยท Service Mesh

Sidecar Proxies and Upstreams in Consul

Register a service with a sidecar proxy, declare upstreams with local bind ports, understand the sidecar port range and run Envoy with consul connect envoy.

A sidecar proxy is the doorway a service uses to enter the mesh. Outbound calls leave through it, inbound calls arrive through it. The piece that makes this work for your code is the upstream: a local port on localhost that the proxy forwards to another service. This lesson shows how to declare upstreams, how Consul chooses sidecar ports and how to start Envoy.

The real Consul and Envoy cannot run on this site. Configuration is shown read-only; the runnable blocks are labelled stand-ins that model port allocation and upstream routing.

Two services in the catalog

When you register connect { sidecar_service {} }, the agent creates two catalog entries:

Service Purpose
web Your application, listening on its own port
web-sidecar-proxy The proxy, listening on a dynamically chosen port for inbound mesh traffic

Other sidecars reach your service by connecting to the proxy's port with mTLS. Your own app should listen on 127.0.0.1 only, so the sidecar is the only way in. If the app listened on all interfaces, callers could skip the proxy and its checks.

Declaring upstreams

An upstream names a destination service and a local port. Here web wants to call api and cache:

HCL
service {
  name = "web"
  port = 8080

  connect {
    sidecar_service {
      proxy {
        upstreams = [
          {
            destination_name = "api"
            local_bind_port  = 9191
          },
          {
            destination_name = "cache"
            local_bind_port  = 9192
          }
        ]
      }
    }
  }
}

Inside web, the code now calls http://localhost:9191 to reach api. The sidecar:

  1. Accepts the plain connection on 9191.
  2. Asks Consul for healthy api instances (the same catalog you used for service discovery).
  3. Opens an mTLS connection to one of their sidecars.
  4. Relays the bytes.

The app needs no service discovery library, no TLS settings and no knowledge of where api runs. If api scales from 2 to 20 instances, nothing changes in web.

Useful upstream fields:

  • destination_name: the service to reach.
  • datacenter: reach the service in another datacenter.
  • local_bind_address / local_bind_port: where to listen. The address defaults to 127.0.0.1.
  • destination_peer: reach a service exported by a peered cluster.
  • config: protocol and timeout overrides per upstream.
Python Stand-in: resolve an upstream port to a destination

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Sidecar ports

Each sidecar needs a unique TCP port on its node for inbound traffic. If you do not set one, Consul picks the first free port from the sidecar port range, 21000 to 21255 by default. The range is set on the agent:

HCL
ports {
  sidecar_min_port = 21000
  sidecar_max_port = 21255
}

That means one agent can host at most 256 sidecars with default settings. A busy Kubernetes node or a large VM could run into that limit, in which case you widen the range. You can also pick a port by hand with port = 21050 inside sidecar_service, but then you are responsible for avoiding collisions.

Python Stand-in: allocate sidecar ports from the range

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Running the proxy

With Envoy installed on the node, one command starts the sidecar for a registered service:

Terminal
consul connect envoy -sidecar-for web

Behind the scenes consul connect envoy asks the local agent for the proxy registration, writes an Envoy bootstrap configuration and launches envoy. Envoy then connects to the agent's gRPC port and receives its listeners, clusters and certificates over the xDS protocol. If ACLs are on, pass a token that can write the service: -token-file=/etc/consul.d/web.token or the CONSUL_HTTP_TOKEN environment variable.

Handy flags:

  • -admin-bind 127.0.0.1:19000 to expose Envoy's admin interface locally for debugging.
  • -bootstrap to print the bootstrap JSON instead of starting Envoy.
  • -proxy-id web-sidecar-proxy to select a proxy by ID instead of -sidecar-for.

In containers, each application container usually has a sibling sidecar container in the same pod or Compose project, sharing the network namespace so localhost reaches the app.

Proxy defaults

Settings that should apply to every proxy go in a proxy-defaults config entry, which has the fixed name global:

HCL
Kind = "proxy-defaults"
Name = "global"

Config {
  protocol = "http"
}

AccessLogs {
  Enabled = true
}

Write it with consul config write proxy-defaults.hcl. Per-service overrides use service-defaults:

HCL
Kind     = "service-defaults"
Name     = "api"
Protocol = "http"

Declaring http (or grpc) lets the mesh understand requests, which is required for path-based routing, request-level metrics and L7 intentions. Plain tcp is the default and treats traffic as opaque bytes. Changing the protocol of a service that has live traffic can briefly disrupt connections, so set it before routing rules depend on it.

Troubleshooting upstreams

Symptom Likely cause
connection refused on the local bind port Sidecar not running, or the upstream is not declared
503 / no healthy upstream No healthy instances, or an intention denies the call
upstream connect error with TLS failure CA or certificate problem, or the destination has no sidecar
App works locally but not remotely App listens on 0.0.0.0 and peers bypass the proxy, or the proxy port is firewalled

Check the catalog first with consul catalog services, then the sidecar's health on api-sidecar-proxy, then intentions.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. How does the web code reach the api service through its sidecar?

    The sidecar listens on the local bind port and handles discovery, mTLS and load balancing for you.
  2. 2. What is the default sidecar port range?

    Consul allocates inbound proxy ports from 21000-21255 unless sidecar_min_port and sidecar_max_port are changed.
  3. 3. Which command starts an Envoy sidecar for the registered service web?

    The command generates the Envoy bootstrap from the agent's registration and launches Envoy.
  4. 4. Why should the application bind to 127.0.0.1 only?

    If the app listens on every interface, callers can skip the proxy and its intentions.
  5. 5. What does setting protocol to http in service-defaults enable?

    With a known protocol the proxy understands requests, which routers, splitters and L7 intentions need.

Summary

  • A mesh service has a sidecar registration (name-sidecar-proxy) in addition to the service itself.
  • Upstreams map local ports to destination services; the app only talks to localhost.
  • Sidecars take ports from 21000-21255 by default, a range you can widen.
  • consul connect envoy -sidecar-for NAME runs Envoy; proxy-defaults and service-defaults set protocol and shared behavior.

Next: Intentions: Controlling Service Access