CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

linkerd-patterns

Implement Linkerd service mesh patterns for lightweight, security-focused service mesh deployments. Use when setting up Linkerd, configuring traffic policies, or implementing zero-trust networking with minimal overhead.

Quality

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Linkerd Patterns

Production patterns for Linkerd service mesh - the lightweight, security-first service mesh for Kubernetes.

Do not use this skill when

  • The task is unrelated to linkerd patterns
  • You need a different domain or tool outside this scope

Instructions

  • Clarify goals, constraints, and required inputs.
  • Apply relevant best practices and validate outcomes.
  • Provide actionable steps and verification.

Use this skill when

  • Setting up a lightweight service mesh
  • Implementing automatic mTLS
  • Configuring traffic splits for canary deployments
  • Setting up service profiles for per-route metrics
  • Implementing retries and timeouts
  • Multi-cluster service mesh

Core Concepts

1. Linkerd Architecture

┌─────────────────────────────────────────────┐
│                Control Plane                 │
│  ┌─────────┐ ┌──────────┐ ┌──────────────┐ │
│  │ destiny │ │ identity │ │ proxy-inject │ │
│  └─────────┘ └──────────┘ └──────────────┘ │
└─────────────────────────────────────────────┘
                      │
┌─────────────────────────────────────────────┐
│                 Data Plane                   │
│  ┌─────┐    ┌─────┐    ┌─────┐             │
│  │proxy│────│proxy│────│proxy│             │
│  └─────┘    └─────┘    └─────┘             │
│     │           │           │               │
│  ┌──┴──┐    ┌──┴──┐    ┌──┴──┐            │
│  │ app │    │ app │    │ app │            │
│  └─────┘    └─────┘    └─────┘            │
└─────────────────────────────────────────────┘

2. Key Resources

ResourcePurpose
ServiceProfilePer-route metrics, retries, timeouts
HTTPRouteCanary deployments, A/B testing, request routing
ServerDefine server-side policies
AuthorizationPolicyAccess control, with MeshTLSAuthentication or NetworkAuthentication

Templates

Template 1: Mesh Installation

# Install CLI: pin a release and install it only if its SHA-256 matches the digest
# shown for that asset on https://github.com/linkerd/linkerd2/releases
# (or use a package manager: brew install linkerd)
LINKERD_VERSION=edge-26.11.1
LINKERD_ASSET="linkerd2-cli-${LINKERD_VERSION}-linux-amd64"  # or -darwin-arm64, -linux-arm64
LINKERD_SHA256=f69701bec37964905d1cb06097e201ddf71e136824c3817f9a94a405fcbb6a07
curl --proto '=https' --tlsv1.2 -sSfLO \
  "https://github.com/linkerd/linkerd2/releases/download/${LINKERD_VERSION}/${LINKERD_ASSET}"
echo "${LINKERD_SHA256}  ${LINKERD_ASSET}" | sha256sum --strict -c - \
  && sudo install -m 0755 "${LINKERD_ASSET}" /usr/local/bin/linkerd

# Validate cluster
linkerd check --pre

# Install CRDs
linkerd install --crds | kubectl apply -f -

# Install control plane
linkerd install | kubectl apply -f -

# Verify installation
linkerd check

# Install viz extension (optional)
linkerd viz install | kubectl apply -f -

Template 2: Inject Namespace

# Automatic injection for namespace
apiVersion: v1
kind: Namespace
metadata:
  name: my-app
  annotations:
    linkerd.io/inject: enabled
---
# Or inject specific deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  annotations:
    linkerd.io/inject: enabled
spec:
  template:
    metadata:
      annotations:
        linkerd.io/inject: enabled

Template 3: Service Profile with Retries

apiVersion: linkerd.io/v1alpha2
kind: ServiceProfile
metadata:
  name: my-service.my-namespace.svc.cluster.local
  namespace: my-namespace
spec:
  routes:
    - name: GET /api/users
      condition:
        method: GET
        pathRegex: /api/users
      responseClasses:
        - condition:
            status:
              min: 500
              max: 599
          isFailure: true
      isRetryable: true
    - name: POST /api/users
      condition:
        method: POST
        pathRegex: /api/users
      # POST not retryable by default
      isRetryable: false
    - name: GET /api/users/{id}
      condition:
        method: GET
        pathRegex: /api/users/[^/]+
      timeout: 5s
      isRetryable: true
  retryBudget:
    retryRatio: 0.2
    minRetriesPerSecond: 10
    ttl: 10s

Template 4: Traffic Split (Canary)

# Weighted HTTPRoute; SMI TrafficSplit and the linkerd-smi extension are deprecated
apiVersion: policy.linkerd.io/v1beta2
kind: HTTPRoute
metadata:
  name: my-service-canary
  namespace: my-namespace
spec:
  parentRefs:
    - name: my-service
      kind: Service
      group: core
      port: 8080
  rules:
    - backendRefs:
        - name: my-service-stable
          port: 8080
          weight: 90
        - name: my-service-canary
          port: 8080
          weight: 10

Template 5: Authorization Policy

# Define the server
apiVersion: policy.linkerd.io/v1beta3
kind: Server
metadata:
  name: my-service-http
  namespace: my-namespace
spec:
  podSelector:
    matchLabels:
      app: my-service
  port: http
  proxyProtocol: HTTP/1
---
# Allow meshed traffic from the frontend service account
apiVersion: policy.linkerd.io/v1alpha1
kind: MeshTLSAuthentication
metadata:
  name: frontend
  namespace: my-namespace
spec:
  identityRefs:
    - kind: ServiceAccount
      name: frontend
---
apiVersion: policy.linkerd.io/v1alpha1
kind: AuthorizationPolicy
metadata:
  name: allow-frontend
  namespace: my-namespace
spec:
  targetRef:
    group: policy.linkerd.io
    kind: Server
    name: my-service-http
  requiredAuthenticationRefs:
    - name: frontend
      kind: MeshTLSAuthentication
      group: policy.linkerd.io
---
# Allow unauthenticated traffic from the cluster network (e.g., from ingress)
apiVersion: policy.linkerd.io/v1alpha1
kind: NetworkAuthentication
metadata:
  name: cluster-network
  namespace: my-namespace
spec:
  networks:
    - cidr: 10.0.0.0/8
---
apiVersion: policy.linkerd.io/v1alpha1
kind: AuthorizationPolicy
metadata:
  name: allow-ingress
  namespace: my-namespace
spec:
  targetRef:
    group: policy.linkerd.io
    kind: Server
    name: my-service-http
  requiredAuthenticationRefs:
    - name: cluster-network
      kind: NetworkAuthentication
      group: policy.linkerd.io

Template 6: HTTPRoute for Advanced Routing

apiVersion: policy.linkerd.io/v1beta2
kind: HTTPRoute
metadata:
  name: my-route
  namespace: my-namespace
spec:
  parentRefs:
    - name: my-service
      kind: Service
      group: core
      port: 8080
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api/v2
        - headers:
            - name: x-api-version
              value: v2
      backendRefs:
        - name: my-service-v2
          port: 8080
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: my-service-v1
          port: 8080

Template 7: Multi-cluster Setup

# On each cluster, install with cluster credentials
linkerd multicluster install | kubectl apply -f -

# Link clusters
linkerd multicluster link --cluster-name west \
  --api-server-address https://west.example.com:6443 \
  | kubectl apply -f -

# Export a service to other clusters
kubectl label svc/my-service mirror.linkerd.io/exported=true

# Verify cross-cluster connectivity
linkerd multicluster check
linkerd multicluster gateways

Monitoring Commands

# Live traffic view
linkerd viz top deploy/my-app

# Per-route metrics
linkerd viz routes deploy/my-app

# Check proxy status
linkerd viz stat deploy -n my-namespace

# View service dependencies
linkerd viz edges deploy -n my-namespace

# Dashboard
linkerd viz dashboard

Debugging

# Check injection status
linkerd check --proxy -n my-namespace

# View proxy logs
kubectl logs deploy/my-app -c linkerd-proxy

# Debug identity/TLS
linkerd identity -n my-namespace

# Tap traffic (live)
linkerd viz tap deploy/my-app --to deploy/my-backend

Best Practices

Do's

  • Enable mTLS everywhere - It's automatic with Linkerd
  • Use ServiceProfiles - Get per-route metrics and retries
  • Set retry budgets - Prevent retry storms
  • Monitor golden metrics - Success rate, latency, throughput

Don'ts

  • Don't skip check - Always run linkerd check after changes
  • Don't over-configure - Linkerd defaults are sensible
  • Don't ignore ServiceProfiles - They unlock advanced features
  • Don't forget timeouts - Set appropriate values per route

Resources

  • Linkerd Documentation
  • Service Profiles
  • Authorization Policy
Repository

rmyndharis/antigravity-skills

Path

skills/linkerd-patterns/SKILL.md

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.