Skip to content
Switch branches/tags

Latest commit

Load balanced clients can get stuck continually trying to reconnect to
defunct endpoints in situations like the following:

1. A balancer has an existing endpoint but it is pending;
2. A new ready endpoint is added to the balancer;
3. Requests are sent to the new endpoint and the balancer ends up with
   the new endpoint being ready.
4. Service discovery issues an update indicating that we should no
   longer use the old endpoint, which has now shutdown.

This discovery update won't be processed by the balancer until we
attempt to issue a request on the balancer. But, because each endpoint
uses `SpawnReady` to attempt reconnection on a background task, we
continually attempt to reconnect to the defunct endpoint even though
we'll never actually issue requests to it (because it will be removed as
soon as the balancer is polled again).

There's a simple fix to this: we shouldn't put reconnection inside of
`SpawnReady`. Instead, we use a `SpawnReady` to drive each individual
connection attempt to readiness, but we don't drive reconnect to drive a
failed connection to be retried until the balancer has a chance to be

This may address linkerd/linkerd2#6842 and should fix another issue
reported in Slack where controller pods would continually log connection
failures after the destination controller was rescheduled.

Git stats


Failed to load latest commit information.
Latest commit message
Commit time


GitHub license Slack Status

This repo contains the transparent proxy component of Linkerd2. While the Linkerd2 proxy is heavily influenced by the Linkerd 1.X proxy, it comprises an entirely new codebase implemented in the Rust programming language.

This proxy's features include:

  • Transparent, zero-config proxying for HTTP, HTTP/2, and arbitrary TCP protocols.
  • Automatic Prometheus metrics export for HTTP and TCP traffic;
  • Transparent, zero-config WebSocket proxying;
  • Automatic, latency-aware, layer-7 load balancing;
  • Automatic layer-4 load balancing for non-HTTP traffic;
  • Automatic TLS (experimental);
  • An on-demand diagnostic tap API.

This proxy is primarily intended to run on Linux in containerized environments like Kubernetes, though it may also work on other Unix-like systems (like macOS).

The proxy supports service discovery via DNS and the linkerd2 Destination gRPC API.

The Linkerd project is hosted by the Cloud Native Computing Foundation (CNCF).

Building the project

A Makefile is provided to automate most build tasks. It provides the following targets:

  • make build -- Compiles the proxy on your local system using cargo
  • make clean -- Cleans the build target on the local system using cargo clean
  • make test -- Runs unit and integration tests on your local system using cargo
  • make test-flakey -- Runs all tests, including those that may fail spuriously
  • make package -- Builds a tarball at target/release/linkerd2-proxy-${PACKAGE_VERSION}.tar.gz. If PACKAGE_VERSION is not set in the environment, the local git SHA is used.
  • make docker -- Builds a Docker container image that can be used for testing. If the DOCKER_TAG environment variable is set, the image is given this name. Otherwise, the image is not named.


Usually, Cargo, Rust's package manager, is used to build and test this project. If you don't have Cargo installed, we suggest getting it via

Repository Structure

This project is broken into many small libraries, or crates, so that components may be compiled & tested independently. The following crate targets are especially important:

Code of conduct

This project is for everyone. We ask that our users and contributors take a few minutes to review our code of conduct.


We test our code by way of fuzzing and this is described in

A third party security audit focused on fuzzing Linkerd2-proxy was performed by Ada Logics in 2021. The full report is available here.


linkerd2-proxy is copyright 2018 the linkerd2-proxy authors. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use these files except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.