# linkerd/linkerd2 architecture

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

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

## Overview

##### Project Type and Purpose
- Linkerd is a cloud-native, ultralight service mesh for Kubernetes. It comprises a control plane (set of microservices running in-cluster), a data-plane proxy (injected as sidecars), a CLI, and optional visualization/telemetry integrations (viz, Jaeger, Grafana).

##### High-Level Architecture
- External Clients / Users: CLI (`linkerd`), web UI, Helm.
- Kubernetes Control Plane (API server & etcd).
- Linkerd Control Plane: Destination, Identity, Proxy-Injector, Heartbeat, SP-Validator, Policy-Controller (Rust), Multicluster components, Webhook services (tap, jaeger injector).
- Data Plane: per-pod proxies (injected sidecars).
- Observability / Telemetry: Prometheus, Grafana dashboards, Jaeger.

##### Main Components & Interactions
a. CLI & Installation
- `linkerd` CLI invokes Kubernetes APIs (CRDs, Helm charts under `charts/`) to install control-plane services as pods. It uses the `pkg/k8s` package to talk to the API server.
b. Kubernetes API & CRDs
- Control-plane services watch CRDs (serviceprofiles, destination profiles) via client-go informers under `controller/gen/*` and `pkg/k8s`.
c. Control Plane Microservices
- Destination Service (gRPC API): looks up service endpoints & profiles.
- Identity Service: issues TLS identities to proxies.
- Proxy-Injector Webhook: mutates pod specs to inject the sidecar proxy.
- Heartbeat: liveness for multicluster.
- SP-Validator: validates ServiceProfile CRDs.
- Policy-Controller (Rust): admission webhook enforcing policy CRDs.
- Multicluster Link & Service-Mirror: cross-cluster link controller & CRDs.
- Viz components: metrics-api gRPC/HTTP server, tap gRPC server, web server for UI.
d. Data Plane Proxies
- Injected as init containers + sidecars into each application pod.
- Intercept inbound/outbound traffic, perform mTLS to other proxies, consult Identity & Destination services.
e. Telemetry Integrations
- Proxies emit metrics to Prometheus (via HTTP/metrics endpoint).
- Viz metrics-api reads metrics & policy state for the UI.
- Tap service streams live request/response data to CLI / UI.
- Jaeger injector webhook adds tracing headers; Jaeger collector collects spans.
f. Helm & Charts
- Installation artifacts under `charts/`, `jaeger/charts/`, `viz/charts/`, `multicluster/charts/`.

##### Architectural Patterns & Principles
- Control-Plane/Data-Plane separation: Control services (state, config) vs sidecar proxies (fast-path traffic).
- Kubernetes-native: CRDs + admission webhooks for injection & policy.
- Microservices: each function (destination, identity, injector) is its own service.
- RPC-driven: gRPC for control-plane APIs.
- Language Diversity: Go for control-plane & CLI; Rust for policy-controller core logic.
- Declarative config via Helm and CRDs.
- Observability: metrics, tracing, dashboards are first-class.

##### Key Details to Capture
- Injection & admission flow (webhooks → sidecar injection/policy validation).
- Discovery & identity issuance (proxies contacting control-plane).
- Metrics/tracing pipeline (proxy → metrics-api/Prometheus → Grafana/Jaeger).
- Multicluster linking (gateway & mirroring).
- CLI => cluster (charts, CRDs, commands).

## Diagram (Mermaid)

```mermaid
flowchart TB
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef control fill:#bbf,stroke:#333,stroke-width:1px
    classDef data fill:#bfb,stroke:#333,stroke-width:1px
    classDef telemetry fill:#fbf,stroke:#333,stroke-width:1px
    classDef storage fill:#ffd,stroke:#333,stroke-width:1px

    subgraph "External Clients & Tools"
        CLI["linkerd CLI"]:::external
        Helm["Helm Charts"]:::external
        User["External Clients/Users"]:::external
    end

    subgraph "Kubernetes Cluster"
        subgraph "Storage & API"
            APIServer["Kubernetes API Server"]:::storage
            Etcd["etcd"]:::storage
            CRDs["CRDs (ServiceProfile, Destination)"]:::storage
        end

        subgraph "Linkerd Control Plane"
            DestSvc["Destination Service"]:::control
            IdentitySvc["Identity Service"]:::control
            Injector["Proxy-Injector Webhook"]:::control
            Heartbeat["Heartbeat Service"]:::control
            SPValidator["SP-Validator"]:::control
            PolicyCtrl["Policy-Controller"]:::control
            subgraph "Multicluster Controllers"
                LinkCtrl["Link Controller"]:::control
                Mirror["Service-Mirror Controller"]:::control
            end
        end

        subgraph "Data Plane"
            AppPod["Application Pod"]:::data
            Proxy["linkerd-proxy sidecar"]:::data
        end

        subgraph "Viz Components"
            VizCLI["Viz CLI"]:::external
            MetricsAPI["Metrics-API Server"]:::control
            TapSvc["Tap gRPC Server"]:::control
            WebUI["Web UI Server"]:::control
        end
    end

    subgraph "Telemetry & Observability"
        Prom["Prometheus"]:::telemetry
        Graf["Grafana UI"]:::telemetry
        JaegerCol["Jaeger Collector"]:::telemetry
        JaegerUI["Jaeger UI"]:::telemetry
    end

    %% Connections
    CLI -->|uses Kubernetes API| APIServer
    Helm -->|deploys charts & CRDs| APIServer
    APIServer --> Etcd
    APIServer --> CRDs

    Injector -->|MutatingWebhook| APIServer
    SPValidator -->|ValidatingWebhook| APIServer
    PolicyCtrl -->|AdmissionWebhook| APIServer

    Proxy <-->|mTLS| IdentitySvc
    Proxy <-->|gRPC| DestSvc
    Proxy -->|HTTP/metrics| Prom
    MetricsAPI -->|gRPC/HTTP| Proxy
    TapSvc -->|gRPC| Proxy

    Prom -->|data| Graf
    JaegerCol -->|spans| JaegerUI

    VizCLI -->|queries MetricsAPI/Tap| MetricsAPI
    User -->|access UI| WebUI
    WebUI -->|api| MetricsAPI

    LinkCtrl -->|sync| Mirror

    %% Click Events
    click CLI "https://github.com/linkerd/linkerd2/tree/main/cli/"
    click APIServer "https://github.com/linkerd/linkerd2/tree/main/pkg/k8s/"
    click DestSvc "https://github.com/linkerd/linkerd2/tree/main/controller/api/destination/"
    click IdentitySvc "https://github.com/linkerd/linkerd2/tree/main/controller/identity/"
    click Injector "https://github.com/linkerd/linkerd2/blob/main/controller/proxy-injector/webhook.go"
    click Heartbeat "https://github.com/linkerd/linkerd2/blob/main/controller/heartbeat/heartbeat.go"
    click SPValidator "https://github.com/linkerd/linkerd2/blob/main/controller/sp-validator/webhook.go"
    click PolicyCtrl "https://github.com/linkerd/linkerd2/blob/main/policy-controller/src/main.rs"
    click LinkCtrl "https://github.com/linkerd/linkerd2/tree/main/multicluster/cmd/"
    click Mirror "https://github.com/linkerd/linkerd2/tree/main/multicluster/service-mirror/"
    click VizCLI "https://github.com/linkerd/linkerd2/tree/main/viz/"
    click MetricsAPI "https://github.com/linkerd/linkerd2/tree/main/viz/metrics-api/"
    click TapSvc "https://github.com/linkerd/linkerd2/tree/main/viz/tap/api/"
    click WebUI "https://github.com/linkerd/linkerd2/tree/main/web/srv/"
    click Helm "https://github.com/linkerd/linkerd2/tree/main/charts/linkerd-control-plane"
    click Proxy "https://github.com/linkerd/linkerd2/tree/main/Dockerfile-proxy"
    class CLI,Helm,User external
    class APIServer,Etcd,CRDs storage
    class DestSvc,IdentitySvc,Injector,Heartbeat,SPValidator,PolicyCtrl,LinkCtrl,Mirror,MetricsAPI,TapSvc,WebUI control
    class AppPod,Proxy data
    class Prom,Graf,JaegerCol,JaegerUI telemetry
```
