Understanding Linkerd Service Profiles: Spec, Routes, and Retry Budget Explained

Overview

Service profiles are a custom Kubernetes resource (CRD) used by Linkerd to provide additional service‑level information, most notably a list of routes that define how traffic is matched and handled.

Specification

The ServiceProfile spec must contain the following top‑level fields: routes: a list of route objects. retryBudget: an object that defines the maximum retry rate for the service.

Route Object

Each route object must include: name: the route name, displayed in the route tag. condition: a request match object that determines whether a request matches this route. responseClasses (optional): a list of response class objects. isRetryable: a boolean indicating that requests to this route can be safely retried, allowing the proxy to retry failed requests. timeout: the maximum time to wait for a response (including retries) after sending a request.

Request Match

A request match object must contain exactly one of the following fields: pathRegex: a regular expression that matches the request path. method: one of GET, POST, PUT, DELETE, OPTION, HEAD, TRACE. all: a list of request match objects that must all match. any: a list of request match objects where at least one must match. not: a list of request match objects that must not match.

Request Match Examples

pathRegex: '/authors/\d+'

Matches request paths like /authors/123. method: POST Matches only POST requests.

all:
- pathRegex: '/authors/\d+'
- method: POST

Both conditions must be satisfied (equivalent to using all).

any:
- all:
  - method: POST
  - pathRegex: '/authors/\d+'
- all:
  - not:
      method: DELETE
  - pathRegex: /info.txt

Combines any, all, and not to create complex matching logic.

Response Class

A response class object must contain: condition: a response match object that defines whether a response belongs to this class. isFailure: a boolean indicating whether responses of this class should be considered failures.

Response Match

A response match object must contain exactly one of the following fields: status: a status range object that matches response status codes. all: a list of response match objects that must all match. any: a list of response match objects where at least one must match. not: a list of response match objects that must not match.

Status Range

The status range object must include at least one of: min: the status code must be greater than or equal to this value. max: the status code must be less than or equal to this value.

Retry Budget

The retryBudget object controls retry behavior for the service: retryRatio: the maximum ratio of retry requests to original requests. minRetriesPerSecond: the minimum number of retries allowed per second beyond the ratio. ttl: the time‑to‑live considered when calculating the retryRatio.

Practical Resources

Setting up service profiles: https://linkerd.hacker-linner.com/2.11/tasks/setting-up-service-profiles/

Full demo walkthrough: https://linkerd.hacker-linner.com/2.11/tasks/books/#service-profiles/