# linkerd/linkerd2-proxy architecture

> Architecture diagram of the GitHub repository linkerd/linkerd2-proxy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/linkerd/linkerd2-proxy
- Repository: https://github.com/linkerd/linkerd2-proxy

## Overview

##### Project Type & Purpose
- This is a full-featured, micro-modular network proxy implemented in Rust, intended to serve as the Linkerd2 “sidecar” for Kubernetes-style environments.
- It provides transparent proxying for HTTP/1.x, HTTP/2, WebSockets, and raw TCP, with built-in mTLS, load balancing (L4 and L7), Prometheus metrics, and a tap API.
- The README confirms it compiles into a single `linkerd2-proxy` executable backed by many smaller crates (libraries), and integrates tightly with a Linkerd control plane via gRPC (the Destination API) and a SPIFFE-based identity service.

##### File Structure Analysis
- Top-level crates:
- `linkerd2-proxy` (binary entry point)
- `linkerd/app` (app layer with inbound/outbound, gateway, admin, core)
- `linkerd/proxy/*` (core proxy building blocks: HTTP, TCP, transport, balance, client/server policy, tap)
- `linkerd/tls`, `linkerd/identity`, `linkerd/distribute`, `linkerd/mesh­tls`, `linkerd/metrics`, etc.
- `linkerd2-app-integration` (integration tests under `linkerd/app/integration`)
- Patterns:
- “Layered Service” design built atop Tower Service traits: each crate provides layers (retry, timeout, metrics, load-balance) composed into inbound and outbound pipelines.
- Clear separation: inbound pipeline (handling traffic toward the local application), outbound pipeline (application-to-service), plus a control-plane gateway and admin API.
- Fuzzing harnesses and GitHub workflows for CI/security.

##### README Insights
- Confirms the executable is `linkerd2-proxy`, which pulls in `linkerd/app/inbound` and `linkerd/app/outbound`.
- Mentions automatic Prometheus export and transparent mTLS.
- Describes service-discovery via DNS and Destination gRPC API.

## Diagram (Mermaid)

```mermaid
flowchart TB
    Exec["linkerd2-proxy Executable"]:::exec
    subgraph "Data Plane Pipelines"
        subgraph "Inbound Pipeline"
            Inbound["Inbound App"]:::inbound
            LB_in["Load Balancer"]:::core
            TLS_term["TLS Termination"]:::core
            HttpLayers["HTTP Stack & Layers"]:::core
            Tap["Tap API"]:::core
            Inbound --> LB_in --> TLS_term --> HttpLayers
            TLS_term --> Tap
        end
        subgraph "Outbound Pipeline"
            Outbound["Outbound App"]:::outbound
            DNS["Service Discovery & DNS"]:::control
            DestAPI["Destination gRPC API"]:::control
            LB_out["Load Balancer"]:::core
            TLS_orig["TLS Origination"]:::core
            HttpLayers2["HTTP Stack & Layers"]:::core
            Outbound --> DNS
            Outbound --> DestAPI
            Outbound --> LB_out --> TLS_orig --> HttpLayers2
        end
    end
    subgraph "Control & Admin"
        Gateway["Gateway App"]:::control
        Admin["Admin API"]:::control
    end
    IdentityClient["Identity Service"]:::control
    Prometheus["Prometheus Scraper"]:::metrics
    IdentityCore["Identity Core"]:::core
    Tower["Tower Service Layers"]:::core

    Exec --> Inbound
    Exec --> Outbound
    Exec --> Gateway
    Exec --> Admin

    Inbound -->|"mTLS handshake"|IdentityClient
    Outbound -->|"mTLS handshake"|IdentityClient
    Admin -->|"pprof/readiness/tap"|Exec
    Gateway -->|"control-plane ingress"|Exec
    Prometheus -.-> Exec

    classDef inbound fill:#D0E8FF,stroke:#000;
    classDef outbound fill:#DFFFD0,stroke:#000;
    classDef control fill:#FFE8B0,stroke:#000;
    classDef metrics fill:#E8D0FF,stroke:#000;
    classDef core fill:#F0F0F0,stroke:#000;
    classDef exec fill:#CCCCCC,stroke:#000;

    click Exec "https://github.com/linkerd/linkerd2-proxy/blob/main/linkerd2-proxy/src/main.rs"
    click Inbound "https://github.com/linkerd/linkerd2-proxy/blob/main/linkerd/app/inbound/src/lib.rs"
    click Outbound "https://github.com/linkerd/linkerd2-proxy/blob/main/linkerd/app/outbound/src/lib.rs"
    click Gateway "https://github.com/linkerd/linkerd2-proxy/blob/main/linkerd/app/gateway/src/lib.rs"
    click Admin "https://github.com/linkerd/linkerd2-proxy/blob/main/linkerd/app/admin/src/lib.rs"
    click DestAPI "https://github.com/linkerd/linkerd2-proxy/blob/main/linkerd/proxy/api-resolve/src/lib.rs"
    click IdentityClient "https://github.com/linkerd/linkerd2-proxy/blob/main/linkerd/proxy/identity-client/src/lib.rs"
    click DNS "https://github.com/linkerd/linkerd2-proxy/blob/main/linkerd/proxy/dns-resolve/src/lib.rs"
    click LB_in "https://github.com/linkerd/linkerd2-proxy/blob/main/linkerd/proxy/balance/src/lib.rs"
    click LB_out "https://github.com/linkerd/linkerd2-proxy/blob/main/linkerd/proxy/balance/src/lib.rs"
    click Tap "https://github.com/linkerd/linkerd2-proxy/blob/main/linkerd/proxy/tap/src/lib.rs"
    click Prometheus "https://github.com/linkerd/linkerd2-proxy/blob/main/linkerd/metrics/src/lib.rs"
    click TLS_term "https://github.com/linkerd/linkerd2-proxy/blob/main/linkerd/tls/src/lib.rs"
    click TLS_orig "https://github.com/linkerd/linkerd2-proxy/blob/main/linkerd/tls/src/lib.rs"
    click IdentityCore "https://github.com/linkerd/linkerd2-proxy/blob/main/linkerd/identity/src/lib.rs"
    click HttpLayers "https://github.com/linkerd/linkerd2-proxy/tree/main/linkerd/http"
    click HttpLayers2 "https://github.com/linkerd/linkerd2-proxy/tree/main/linkerd/http"
    click Tower "https://github.com/linkerd/linkerd2-proxy/blob/main/linkerd/stack/src/lib.rs"
```
