---

name: linkerd compatibility: opencode completeness: 95 content-types:

• guidance
• examples
• do-dont
• config description: '"Linkerd in Service Mesh - cloud native architecture, patterns, pitfalls" and best practices' license: MIT maturity: stable metadata: domain: cncf output-format: manifests related-skills: calico, cilium, contour, kuma role: reference scope: infrastructure triggers: cdn, infrastructure as code, k8s service, kubernetes service, linkerd, monitoring, native, service archetypes:
  • educational
  • strategic anti_triggers:
  • brainstorming
  • vague ideation
  • non-containerized architecture response_profile: verbosity: medium directive_strength: low abstraction_level: strategic version: "1.0.0"

---

Linkerd in Cloud-Native Engineering

Purpose and Use Cases

What Problem Does It Solve?

• Zero-trust service communication: Provides secure, observable, and reliable service-to-service communication without code changes
• Operational simplicity: Lightweight service mesh that focuses on observability, reliability, and security with minimal configuration
• Performance overhead reduction: Minimal latency addition (typically <1ms) compared to heavier mesh alternatives
• Security without encryption complexity: Automatic mTLS with certificate rotation, identity-based policies, and audit logging
• Platform abstraction: Works across Kubernetes, bare metal, VMs, and hybrid environments

When to Use

• Kubernetes-first deployments: When Kubernetes is your primary platform and you need service mesh capabilities
• Gradual adoption: When you want to start small and incrementally adopt mesh features
• Observability requirements: When you need distributed tracing, metrics, and service maps out of the box
• Security compliance: When you need mTLS, identity-based access control, and audit trails
• Resource-constrained environments: When you need a lightweight mesh with minimal resource overhead

Key Use Cases

• Service-to-service mTLS: Automatically encrypt all service communication
• Traffic splitting: Canary deployments, A/B testing with traffic policies
• Observability dashboards: Real-time service health, latency, and error rate metrics
• Policy enforcement: Access control between services based on identity
• Resilience patterns: Circuit breaking, retries, and timeouts for service reliability

Architecture Design Patterns

Core Components

Control Plane

control-plane
├── linkerd-controller (identity, web, tap, destination)
├── linkerd-proxy-injector (admission webhook)
└── linkerd-prometheus (metrics collection)

• Controller: Manages mesh configuration and state
• Identity service: Provides mTLS certificates with short-lived TTL
• Web service: UI and API server
• Tap service: Real-time traffic observation endpoint
• Destination service: Service discovery and load balancing
• Proxy injector: Admits pods with sidecar proxy injection

Data Plane (Proxy)

pod
├── application container
└── linkerd-proxy sidecar container
    ├── inbound listener
    ├── outbound listener
    └── metrics collection

• -proxy:Transparent proxy that intercepts all traffic
• Inbound listener: Handles incoming connections with mTLS
• Outbound listener: Routes outgoing traffic with load balancing
• Metrics: Collects latency, success rate, and throughput

Component Interactions

Client Pod
    ↓ (proxy intercepts)
Linkerd Proxy (Outbound)
    ↓ (mTLS)
Service Mesh Network
    ↓ (destination service lookup)
Linkerd Proxy (Inbound)
    ↓ (proxy forwards)
Server Pod

Data Flow Patterns

Request Flow

1. Application sends request to localhost
2. Proxy intercepts and encrypts with mTLS
3. Proxy uses destination service for routing
4. Request forwarded to destination proxy
5. Destination proxy validates certificate and forwards
6. Application receives decrypted response

Certificate Flow

1. Proxy requests certificate from identity service
2. Identity service validates pod identity
3. Certificate issued with short TTL (8 hours default)
4. Certificate rotated automatically before expiration
5. Certificate revocation supported for compromised pods

Design Principles

Transparency

• Zero code changes required: Proxy intercepts all traffic automatically
• No service awareness needed: Works with any application protocol
• Non-invasive: Can be added/removed without application changes

Security First

• Automatic mTLS: All communication encrypted by default
• Short-lived certificates: Automatic rotation every 8 hours
• Identity-based policies: Access control based on service identity
• Audit logging: All policy decisions logged

Observability

• Built-in metrics: Latency, success rate, throughput
• Service graphs: Visualize service dependencies
• Tap capability: Real-time request inspection
• Debugging tools: CLI tools for troubleshooting

Integration Approaches

Integration with Other CNCF Projects

Prometheus Integration

apiVersion: v1
kind: ConfigMap
metadata:
  name: linkerd-prometheus-config
data:
  prometheus.yaml: |
    scrape_configs:
      - job_name: 'linkerd-proxy'
        static_configs:
          - targets: ['localhost:4191']

• Metrics scraping: Proxy exposes /metrics endpoint
• Dashboards: Pre-built Grafana dashboards available
• Alerting: Alertmanager integration for SLO violations

Grafana Integration

apiVersion: v1
kind: ConfigMap
metadata:
  name: linkerd-grafana-dashboards
data:
  linkerd-service-dashboard.json: |
    {
      "annotations": {},
      "panels": [
        // Linkerd service panels
      ]
    }

• Service dashboard: Real-time service health visualization
• Mesh dashboard: Complete mesh topology
• Resource dashboard: CPU, memory usage by proxy

OPA Integration

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-policy
spec:
  podSelector:
    matchLabels:
      app: payment-service
  policyTypes:
    - Ingress
  ingress:
    - from:
        - podSelector:
            matchLabels:
              linkerd.io/control-plane-namespace: linkerd
              linkerd.io/proxy-deployment: payment-gateway

• Policy enforcement: Kubernetes NetworkPolicies + Linkerd policies
• Custom policies: OPA Gatekeeper for additional compliance

Jaeger Integration

apiVersion: v1
kind: ConfigMap
metadata:
  name: linkerd-jaeger-config
data:
  jaeger.yaml: |
    endpoint: jaeger-collector:14268
    tags: |
      service.name=linkerd-proxy

• Distributed tracing: Linkerd integrates with existing tracing systems
• Request IDs: Propagates trace context
• Latency tracking: End-to-end latency measurement

API Patterns

Service Profile API

apiVersion: linkerd.io/v1alpha2
kind: ServiceProfile
metadata:
  name: payments-service.default.svc.cluster.local
spec:
  routes:
    - name: GET /payments
      condition:
        method: GET
        pathRegex: /payments
      responseTimeout: 1s
    - name: POST /payments
      condition:
        method: POST
        pathRegex: /payments
      retryBudget:
        retryRatio: 0.2
        minRetriesPerSecond: 10
        ttl: 30s
  decisionTimeout: 100ms

• Route definitions: HTTP route-based policies
• Timeouts and retries: Per-route configuration
• Rate limiting: Request rate control

Authorization Policy API

apiVersion: policy.linkerd.io/v1beta1
kind: ServerPolicy
metadata:
  name: payments-service-policy
spec:
  selector:
    matchLabels:
      app: payments-service
  rules:
    - ports:
        - port: 8080
      authenticationModes:
        - PERMISSIVE
        - STRICT

---

---

## Constraints

### MUST DO
- Cite authoritative primary sources (official documentation, RFCs, standards bodies) — avoid secondary or blog references
- Include version-specific guidance when the reference topic has significant version-dependent behavior
- Structure reference content with clear navigation: overview first, then detailed subsections organized by use case
- Keep examples minimal and self-contained so readers can copy-paste without needing external context

### MUST NOT DO
- Do not present opinionated practices as facts — distinguish between standards, recommendations, and personal preferences
- Avoid outdated API references or deprecated patterns; explicitly note version requirements for each code example
- Never include incomplete or pseudocode examples in reference materials — all examples should be runnable
- Do not conflate different product versions when documenting features that vary across releases


## Live References

> Authoritative documentation links for this skill's domain. The model follows markdown links at load time to resolve external references and inline content.

- [Primary Documentation](https://linkerd.io/2.15/getting-started)
- [API Reference or Getting Started](https://linkerd.io/2.15/reference/cli/install)
- [Configuration Guide](https://linkerd.io/2.15/features/service-profiles)
- [Best Practices](https://linkerd.io/2.15/features/mutual-tls)
- [Common Patterns or Tutorials](https://linkerd.io/2.15/reference/proxy-config)