GO — Healthy across the board

• Last commit today
• 14 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 72% of recent commits

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

Linkerd2 is an ultralight, security-first service mesh for Kubernetes that intercepts and manages all inter-service traffic without code changes. It adds mTLS encryption, traffic policy enforcement, observability, and reliability features (retries, timeouts, load balancing) at the Kubernetes network layer via sidecar data plane proxies (written in Rust) and a Go control plane. Monorepo structure: CLI and control plane are primarily Go in the root; policy-controller/ subtree contains Rust controllers (policy-controller/, policy-controller/core, policy-controller/grpc, policy-controller/k8s/*); separate linkerd2-proxy and linkerd2-proxy-api repos handle data plane. Web dashboard is JavaScript. Kubernetes manifests and Helm charts describe deployment.

Platform engineers and SREs running Kubernetes clusters who need to add transparent service-to-service security, traffic management, and observability without modifying application code. Contributors include Go developers (control plane), Rust developers (proxy), and JavaScript developers (dashboard UI).

Highly mature and production-ready. Linkerd is a CNCF project with established governance, comprehensive CI/CD pipelines across Go, Rust, and JavaScript, security audit results published, and multiple version releases. Monolithic Go control plane and Rust proxy indicate significant development investment and stability.

Low risk for stability but moderate operational complexity. The repo depends on external projects (linkerd2-proxy, linkerd2-proxy-api) that must be versioned together; see .proxy-version file. Requires careful coordination between control plane releases and proxy sidecar rollouts. The multi-language codebase (Go, Rust, JavaScript) increases onboarding friction and testing matrix complexity.

Active development on policy-controller (Rust) as indicated by workspace members and Cargo.toml dependencies pinned to recent versions (k8s-openapi 0.25, kube 1.1, kubert 0.25). GitHub workflows show continuous testing across Go, Rust, JavaScript, and integration tests. Recent focus on gateway-api support (version 0.16 in dependencies) and Kubernetes 1.33 compatibility.

Clone: git clone https://github.com/linkerd/linkerd2.git && cd linkerd2. Install per BUILD.md (requires Go 1.21+, Rust, Node.js). For control plane: make build. For policy-controller: cd policy-controller && cargo build. For dashboard: cd web && yarn install && yarn build. Test with make test or workflow scripts in .github/workflows/.

Daily commands: Control Plane: make build produces linkerd CLI binary and controller images; deploy via linkerd install | kubectl apply -f - to a Kubernetes cluster. Policy Controller: cd policy-controller && cargo run after setting up local k8s (minikube/kind). Dashboard: cd web && yarn start runs dev server on localhost:3000 (requires running control plane). Tests: make test for Go, cargo test for Rust, yarn test for JavaScript.

• README.md — Foundation document explaining Linkerd's mission as an ultralight, security-first service mesh and pointing to all major repo references.
• Cargo.toml — Root workspace configuration for all Rust components including policy-controller, the core control plane subsystem.
• .proxy-version — Version pinning file that synchronizes the data plane proxy version across the entire build pipeline.
• CONTRIBUTING.md — Developer contribution guidelines covering DCO requirements, testing, and commit standards essential for all PRs.
• .github/workflows/go.yml — Primary CI/CD pipeline orchestrating Go control plane builds, tests, and artifact publication.
• .github/workflows/rust.yml — Rust component CI pipeline managing policy-controller and workspace member compilation and validation.
• BUILD.md — Comprehensive build instructions detailing local development environment setup, toolchain requirements, and container image generation.

Add a new control plane service (e.g., new API component)

1. Create a new Go service directory following existing patterns (e.g., tap, metrics-api structure) (bin/docker-build-[service-name])
2. Define Dockerfile for the new service following the pattern in Dockerfile.controller (Dockerfile.[service-name])
3. Add build script in bin/ directory to compile and containerize the service (bin/docker-build-[service-name])
4. Update GitHub Actions workflow to build and test the new service on each commit (.github/workflows/go.yml)

Add a new policy or networking rule to the policy controller

1. Define the policy CRD structure in the policy-controller/k8s/api layer (policy-controller/k8s/api)
2. Implement the policy enforcement logic in policy-controller/core (policy-controller/core)
3. Add Kubernetes indexing and status tracking in policy-controller/k8s/index and policy-controller/k8s/status (policy-controller/k8s/index)
4. Update Cargo.toml workspace dependencies if new Rust crates are needed (Cargo.toml)
5. Add integration tests to ensure the policy works end-to-end on Kubernetes (.github/workflows/integration.yml)

Update the data plane proxy version and sync across all builds

1. Update the proxy version reference file (.proxy-version)
2. Verify proxy is fetched and pinned in build scripts (bin/fetch-proxy)
3. Ensure CI pipeline validates the new proxy version builds and passes integration tests (.github/workflows/rust.yml)

Add a new CLI command to the Linkerd CLI

1. Implement the command handler in the CLI Go code (inferred from build structure) (bin/build-cli-bin)
2. Add the new command to the CLI binary build process (bin/docker-build-cli-bin)
3. Update CLI integration tests to verify the new command works end-to-end (.github/workflows/integration.yml)
4. Update CONTRIBUTING.md with any new CLI development patterns (CONTRIBUTING.md)

• Rust + Tokio (Policy Controller, Workspace) — Memory efficiency, safety guarantees, and zero-cost abstractions critical for a lightweight service mesh control plane running in resource-constrained Kubernetes clusters
• Go (Control Plane CLI, Services) — Fast compilation, single binary deployment, excellent Kubernetes client library ecosystem, and operational simplicity for production-grade infrastructure tooling
• Kubernetes-native APIs (CRDs, RBAC, ConfigMaps) — Tight integration with Kubernetes control loop ensures Linkerd becomes a natural extension of cluster networking without external state stores
• gRPC + Protobuf (Service Communication) — Efficient binary protocol for low-latency, high-throughput control plane communication with strong versioning and code generation
• GitHub Actions — Tight GitHub integration for automated testing, artifact building, and release workflows without external CI/CD platform dependencies

• Proxy in separate linkerd2-proxy repo, not bundled in this repo

  • Why: Allows independent release cycles, specialized Rust optimization, and clear separation of data plane from control plane development
  • Consequence: Version synchronization required via .proxy-version file; increased coordination complexity across repos

• Policy controller as separate Rust workspace, not monolithic Go service

  • Why: Type safety and memory efficiency for complex policy logic; enables async networking code with minimal overhead
  • Consequence: Adds polyglot complexity; developers must understand both Go and Rust patterns

• Kubernetes CRDs as source of truth for all configuration

  • Why: Single declarative model, tight Kubernetes integration, no external state store to manage
  • Consequence: Etcd becomes critical dependency; cluster API rate limits may constrain policy update frequency

• Lightweight CLI with no external UI framework (dashboard via separate web service)

  • Why: Minimal dependencies, fast bootstrap, low operational overhead for Kubernetes-first tools
  • Consequence: Web UI requires separate backend service deployment; richer interactions require more backend logic

• Does not handle application-level authentication or authorization (policy-controller enforces network policies, not identity-based access control)
• Does not provide distributed tracing backend (integrates with existing OpenTelemetry/Prometheus ecosystems but does not replace them)
• Does not replace Kubernetes NetworkPolicy (extends and enhances it with mTLS and service-level policies)
• Does not manage external traffic ingress (assumes Kubernetes Ingress or similar for north-south traffic)
• Not a multi-cluster mesh (operates within single Kubernetes cluster; multi-cluster requires external tooling)

Proxy version lock: .proxy-version file must match linkerd2-proxy release; mismatches cause control plane–proxy incompatibility. Multi-repo coordination: Policy features require updates across linkerd2 (control plane) and linkerd2-proxy (data plane); single PRs cannot span both. Kubernetes version skew: Tests run against k8s-openapi 0.25 (Kubernetes 1.33 support); older clusters may fail. DCO enforcement: All commits require 'Signed-off-by' footer (see DCO file); CI blocks unsigned commits. Workspace dependencies: Cargo.toml workspace members share versions; changing one may require rebuilding all policy-controller crates.

• mTLS (mutual TLS) with automatic certificate rotation — Linkerd's primary security feature: transparent encryption of all service-to-service traffic without code changes; requires understanding certificate issuer integration, trust anchors, and workload identity in Kubernetes
• Sidecar proxy pattern — Linkerd injects lightweight Rust proxies as sidecars in each pod to intercept traffic; understanding pod lifecycle, init containers, and iptables interception is essential for debugging deployment issues
• Kubernetes Custom Resource Definitions (CRDs) for policy — Policies (AuthorizationPolicy, NetworkPolicy, ServiceProfile) are defined as Kubernetes CRDs in policy-controller/k8s/api; modifying policy logic requires understanding CRD validation, webhooks, and status subresources
• gRPC for control plane–proxy communication — Control plane and data plane proxies communicate via gRPC streaming APIs (defined in linkerd2-proxy-api) for service discovery and policy updates; understanding proto message flows is critical for troubleshooting policy propagation delays
• Traffic policy enforcement (retries, timeouts, load balancing) — Linkerd applies policies like retries and canary deployments at the proxy layer; control plane compiles high-level policies into low-level proxy configuration; understanding the policy compiler in policy-controller/core is needed for extending policies
• Observability via service mesh metrics and tracing — Linkerd proxies emit Prometheus metrics and tracing telemetry; dashboard consumes these to visualize traffic; modifying observability features requires understanding metric export formats and dashboard query logic
• Kubernetes workload identity and RBAC for service mesh policies — Linkerd policy controller indexes Kubernetes objects (Pods, ServiceAccounts, Namespaces) to enforce policies; understanding workload selectors and Kubernetes RBAC is essential for writing correct authorization policies

• linkerd/linkerd2-proxy — Separate Rust data plane proxy that Linkerd2 control plane instructs; version locked in .proxy-version and must be rebuilt for feature parity
• linkerd/linkerd2-proxy-api — gRPC API definitions (protobuf) shared between control plane and proxy for service discovery and policy enforcement; imported as linkerd2-proxy-api dependency
• linkerd/website — Documentation and website source; Linkerd2 README references getting-started and docs hosted here; contributes to ecosystem learning
• istio/istio — Alternative service mesh using sidecar injection pattern; Linkerd2 differentiates on 'ultralight' footprint and security-first design vs. Istio's broader feature set
• open-service-mesh/osm — Lighter-weight service mesh alternative also written in Go; shares Kubernetes-native deployment model but different policy API and proxy architecture

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for policy-controller Rust workspace modules

The Cargo.toml shows a multi-member Rust workspace (policy-controller, policy-controller/core, policy-controller/grpc, policy-controller/k8s/api, policy-controller/k8s/index, policy-controller/k8s/status, policy-controller/runtime) but there's no visible test workflow in .github/workflows for Rust integration tests beyond the existing rust.yml. The workspace dependencies on kubert, kube, and tonic suggest complex distributed systems code that needs integration testing. Contributing end-to-end tests for policy controller interactions would catch regressions in the control plane.

• [ ] Review existing .github/workflows/rust.yml to understand current test coverage
• [ ] Create integration test suite in policy-controller/tests/ covering k8s API interactions
• [ ] Add test cases for policy-controller/k8s/status updates and policy-controller/k8s/index caching
• [ ] Extend rust.yml workflow to run cargo test --workspace --test '*' if not already present
• [ ] Document test setup in CONTRIBUTING.md for policy-controller development

Add missing GitHub Actions workflow for Cargo.lock validation and dependency auditing

The repo has Cargo.lock committed (workspace resolver v2 with multiple members) but .github/workflows lacks a dedicated Rust dependency security workflow. While dependabot.yml exists, there's no automated cargo audit or cargo deny checks in CI. With dependencies like tonic, hyper, and k8s-openapi that touch security-critical code (proxy API, Kubernetes auth), adding a cargo-audit workflow would catch CVEs early and ensure supply chain security aligns with the CNCF security posture advertised in README.

• [ ] Create .github/workflows/cargo-audit.yml that runs cargo audit on push to main and PRs
• [ ] Add optional cargo deny checks in the same workflow (audit banned/unmaintained crates)
• [ ] Configure workflow to fail on vulnerabilities matching CVSS threshold (if using cargo-deny)
• [ ] Test locally by adding a known-vulnerable dependency and verifying workflow catch
• [ ] Document in CONTRIBUTING.md the vulnerability reporting process for transitive dependencies

Add missing documentation for policy-controller Rust workspace architecture and CRD contracts

The file structure shows policy-controller/k8s/api, policy-controller/k8s/index, policy-controller/k8s/status as separate modules but BUILD.md and other documentation don't explain the architecture of how these interact with Kubernetes CRDs. New contributors need to understand the contract between k8s/api (CRD types), k8s/index (caching/indexing), and k8s/status (status updates). The repo references linkerd2-proxy-api (v0.18.0) but how the policy-controller feeds policies to the proxy is not documented for Rust-side contributors.

• [ ] Create policy-controller/ARCHITECTURE.md documenting the k8s/api → k8s/index → policy-runtime → proxy-api flow
• [ ] Add examples showing how to add a new policy type (CRD definition, indexing logic, proto message)
• [ ] Document the status subresource update pattern used by policy-controller/k8s/status with examples
• [ ] Link to relevant Kubernetes API machinery patterns (e.g., informer caching patterns from kubert)
• [ ] Add a troubleshooting section for common policy controller debugging (indexing failures, status stuck)

• Add integration tests for AuthorizationPolicy CRD validation in policy-controller/k8s/api; currently lacks comprehensive end-to-end test coverage against actual Kubernetes API server
• Document the mTLS certificate rotation flow in control plane code; BUILD.md mentions it but no code comments explain the cert-manager integration or renewal intervals
• Add missing CLI tests for linkerd policy commands in cmd/linkerd/; existing _test.go files show patterns but policy subcommand has low coverage

Linkerd2 demonstrates a strong security posture with established security policies, third-party audits, code review processes, and dependency hygiene via Dependabot. The codebase shows intentional security-first design principles. However, minor improvements are recommended: (1) evaluate full LTO for release builds to maximize compiler-level hardening, (2) ensure aggressive dependency update policies given the security-critical nature of a service mesh, and (3) verify that all security-relevant features are explicitly enabled in dependencies with default features disabled. The presence of security audit reports (2019, 2022, 2024), DCO enforcement, and comprehensive GitHub Actions workflows for code quality and scanning indicates mature security practices. No hardcoded secrets, SQL injection risks, or XSS vulnerabilities are evident from the file structure analysis.

• Medium · Thin LTO Profile in Release Build — Cargo.toml [profile.release]. The Cargo.toml uses 'thin' link-time optimization (LTO) in release builds. While this improves build times, it may reduce some compiler-level security optimizations and code hardening compared to full LTO. For a security-critical service mesh, consider evaluating if full LTO is feasible. Fix: Evaluate switching to lto = "fat" or "full" for maximum security hardening in release builds, or document the decision to use 'thin' LTO for performance reasons.
• Medium · Outdated k8s-openapi Version — Cargo.toml [workspace.dependencies] k8s-openapi. The workspace dependency k8s-openapi is pinned to version 0.25. Older versions may contain known vulnerabilities. Regular dependency updates are critical for a security-first service mesh. Fix: Regularly update k8s-openapi to the latest stable version. Enable automated dependency scanning via Dependabot and review updates promptly.
• Low · Feature Flag Complexity in Hyper and Tower — Cargo.toml [workspace.dependencies] hyper, tower, kube, kubert, linkerd-policy-controller-runtime. Dependencies like hyper, tower, and kube use default-features = false with selective features. While this is good practice for reducing attack surface, ensure all necessary security features are explicitly enabled. Fix: Audit that all security-critical features are explicitly enabled in dependencies that disable default features. Document feature selection rationale.
• Low · Proxy API Dependency Version Pinning — Cargo.toml [workspace.dependencies.linkerd2-proxy-api]. linkerd2-proxy-api is pinned to version 0.18.0. While pinning prevents unexpected changes, it may also delay security patches if a newer version becomes available. Fix: Implement a regular review cycle for proxy-api updates. Use semantic versioning constraints (e.g., ~0.18.0) to allow patch updates while maintaining stability.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/linkerd/linkerd2 shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live linkerd/linkerd2 repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/linkerd/linkerd2.

What it runs against: a local clone of linkerd/linkerd2 — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in linkerd/linkerd2 | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of linkerd/linkerd2. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/linkerd/linkerd2.git
#   cd linkerd2
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of linkerd/linkerd2 and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "linkerd/linkerd2(\\.git)?\\b" \\
  && ok "origin remote is linkerd/linkerd2" \\
  || miss "origin remote is not linkerd/linkerd2 (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f ".proxy-version" \\
  && ok ".proxy-version" \\
  || miss "missing critical file: .proxy-version"
test -f "CONTRIBUTING.md" \\
  && ok "CONTRIBUTING.md" \\
  || miss "missing critical file: CONTRIBUTING.md"
test -f ".github/workflows/go.yml" \\
  && ok ".github/workflows/go.yml" \\
  || miss "missing critical file: .github/workflows/go.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/linkerd/linkerd2"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.