NAV
This is an archived version
of the documentation
View the latest version

Introduction

A Linkerd config example

admin:
  port: 9990

routers:
- protocol: http
  label: int-http
  dtab: |
    /svc       => /#/io.l5d.fs;
  servers:
  - port: 4140
    ip: 0.0.0.0

- protocol: thrift
  servers:
  - port: 8081
    ip: 0.0.0.0
    thriftFramed: true
  client:
    thriftFramed: true
  thriftMethodInDst: false
  dtab: |
    /svc => /#/io.l5d.fs/thrift;

namers:
- kind: io.l5d.fs
  rootDir: disco

telemetry:
- kind: io.l5d.statsd
  experimental: true
  prefix: linkerd
  hostname: 127.0.0.1
  port: 8125
  gaugeIntervalMs: 10000
  sampleRate: 0.01
- kind: io.l5d.tracelog
  sampleRate: 0.2
  level: TRACE

Welcome to the Configuration Reference for Linkerd!

Linkerd’s configuration is controlled via a configuration file, which must be provided as a command-line argument. It may be a local file path or - to indicate that the configuration should be read from the standard input. For convenience, the release package includes a default linkerd.yaml file in the config/ directory.

File Format

The configuration may be specified as a JSON or YAML object. There are no requirements on field ordering, though it’s generally good style to start a router with the protocol. Five top level keys are supported:

Key Required Description
admin no Configures Linkerd’s administrative interface.
routers yes Configures Linkerd’s RPC support for various protocols.
namers no Configures Linkerd’s integration with various service discovery backends.
telemetry no Configures Linkerd’s metrics instrumentation.
usage no Configures Linkerd usage reporting.

Administrative interface

admin:
  ip: 127.0.0.1
  port: 9990
  tls:
    certPath: /foo/cert.pem
    keyPath: /foo/key.pem

Linkerd supports an administrative interface, both as a web ui and a collection of json endpoints. The exposed admin port and ip to listen on are configurable via a top-level admin section.

Key Default Value Description
ip loopback address IP for the admin interface. A value like 0.0.0.0 configures admin to listen on all local IPv4 interfaces.
port 9990 Port for the admin interface.
socketOptions none Socket options to set for the admin interface.
httpIdentifierPort none Port for the http identifier debug endpoint.
shutdownGraceMs 10000 maximum grace period before the Linkerd process exits
tls no tls The admin interface will serve over TLS if this parameter is provided. See TLS.
security no restrictions The admin interface can block sensitive endpoints if configured. See Admin Security
workerThreads 2 The number of worker threads used to serve the admin interface.

Administrative endpoints

Example admin requests

curl :9990/admin
curl :9990/admin/tracing?enable=true
curl -H "Accept: application/json" :9990/admin/lint
curl -H "Accept: application/json" :9990/admin/threads
curl ":9990/admin/pprof/profile?seconds=10&hz=100"
curl ":9990/delegator.json?path=/http/1.1/GET/foo&dtab=/http/*=>/$/inet/127.1/9990"

Default admin endpoints available in both Linkerd and Namerd:

Endpoint Description
/admin retrieve a list of all available admin endpoints
/admin/announcer set of announcement chains that have run through the announcers
/admin/contention call stacks of blocked and waiting threads
/admin/lint results for all registered linters, set Accept: application/json to force json
/admin/lint.json identical to admin/lint
/admin/ping simple health check endpoint, returns pong
/admin/pprof/contention CPU contention profile which identifies blocked threads (Thread.State.BLOCKED), in pprof format. The process will be profiled for 10 seconds at a frequency of 100 hz. These values can be controlled via HTTP request parameters seconds and hz respectively.
/admin/pprof/heap heap profile computed by the heapster agent, output is in pprof format
/admin/pprof/profile CPU usage profile in pprof format. The process will be profiled for 10 seconds at a frequency of 100 hz. These values can be controlled via HTTP request parameters seconds and hz respectively.
/admin/registry.json displays how Linkerd is currently configured across a variety of dimensions including the client stack, server stack, flags, service loader values, system properties, environment variables, build properties and more
/admin/server_info build information about this Linkerd
/admin/shutdown initiate a graceful shutdown
/admin/threads capture the current stacktraces, set Accept: application/json to force json
/admin/threads.json identical to admin/threads
/admin/tracing enable (/admin/tracing?enable=true) or disable tracing (/admin/tracing?disable=true)
/config.json current Linkerd configuration, this should match your config file

Endpoints only available in Linkerd:

Endpoint Description
/bound-names.json list of all known bound names from configured namers. namers must support the EnumeratingNamer trait to make this available, currently only supported by the io.l5d.k8s and io.l5d.fs namers.
/delegator.json given path, dtab, and an optional namespace param, return the delegation tree
/logging.json currently configured loggers and log levels

Note that in addition to a default set of admin endpoints, Linkerd plugins may dynamically add their own endpoints.

HTTP Identifier Endpoints (running on httpIdentifierPort):

Endpoint Description
/ identifies the request and returns a json map of identified results

This administrative interface was originally based on TwitterServer, more information may be found at TwitterServer HTTP Admin interface.

Admin security

Example to disable the endpoint /admin/shutdown exclusively

admin:
  ip: 127.0.0.1
  port: 9990
  security:
    pathBlacklist:
    - ^/admin/shutdown$

By default all administrative endpoints are accessible. This might not always be desired as this allows for example everybody to shutdown the process if the administrative port is not closed because metrics should be polled from Linkerd. The admin security configuration allows to whitelist or blacklist dedicated administrative endpoints.

admin:
  ip: 127.0.0.1
  port: 9990
  security:
    uiEnabled: true
    controlEnabled: false
    pathWhitelist:
    - ^/logging[.]json$

The security configuration supports these parameters allowing fine grained control over the administrative endpoints that are available.

Key Default Value Description
uiEnabled true Configures if all endpoints that belong to the category required to run the administrative ui are available
controlEnabled  true Configures if the endpoints that belong to the category to control Linkerd are available, i.e. /admin/shutdown and /logging.json
diagnosticsEnabled  true Configures if all other endpoints are available.
pathWhitelist empty list Configures paths via regular expressions that should be available for disabled endpoint categories
pathBlacklist  empty list Configures additional paths via regular expressions that should not be available for enabled categories

An administrative endpoint is available if its category is enabled and it is not on the blacklist or if its category is disabled and it is on the whitelist.

Routers Intro

A minimal Linkerd configuration example, which forwards all requests on localhost:8080 to localhost:8888

routers:
- protocol: http
  dtab: /svc/* => /$/inet/127.1/8888
  servers:
  - port: 8080

All configurations must define a routers key, the value of which must be an array of router configurations. Each router implements RPC for a supported protocol. Linkerd doesn’t need to understand the payload in an RPC call, but it does need to know enough about the protocol to determine the logical name of the destination.

See routers.

Namers and Service Discovery

namers:
- kind: io.l5d.fs
  rootDir: disco

Linkerd supports a variety of common service discovery backends, including ZooKeeper and Consul. Linkerd provides abstractions on top of service discovery lookups that allow the use of arbitrary numbers of service discovery backends, and for precedence and failover rules to be expressed between them. This logic is governed by the routing configuration.

Naming and service discovery are configured via the namers section of the configuration file. A namer acts on paths that start with /# followed by the namer’s prefix. See namers.

Telemetry Intro

telemetry:
- kind: io.l5d.statsd
  experimental: true
  prefix: linkerd
  hostname: 127.0.0.1
  port: 8125
  gaugeIntervalMs: 10000
  sampleRate: 0.01
- kind: io.l5d.tracelog
  sampleRate: 0.2
  level: TRACE

A telemeter may receive stats and trace annotations, i.e. to send to a collector or export. Telemetry data can be collected and exported from a Linkerd process by configuring telemeters via a top-level telemetry section. See telemetry.

Usage

Example usage config

usage:
 orgId: my-org

In order to make improvements and prioritize features, we’d like to gain a broader picture of how users run Linkerd. Linkerd gathers anonymized usage data, and sends it to Buoyant once an hour. This behavior can be configured or disabled in the usage config.

The kind of data captured is as follows:

  1. How Linkerd is configured (The kinds of namers, initializers, identifiers, transformers, protocols, & interpreters used)
  2. What environments Linkerd is running in (Operating System, Container orchestration solution),
  3. How Linkerd performs in those contexts (JVM performance, Number of requests served)

We do not collect the labels of namers/routers, designated service addresses or directories, dtabs, request/response data, or any other possibly identifying information.

To see the exact payload that is sent query localhost:9990/admin/metrics/usage

Key Default Value Description
orgId empty by default Optional string of your choosing that identifies your organization
enabled true If set to true, data is sent to Buoyant once per hour

Socket Options

Linkerd supports configuring socket level options for any given interface. i.e. the admin and router interfaces. These configurations are only available on Linux 3.9 distributions and newer.

Key Default Value Description
noDelay true If set to true, enables the use of TCP_NODELAY on a socket interface
reuseAddr true If set to true, enables the SO_REUSEADDR option
reusePort false If set to true, enables the SO_REUSEPORT option, which can be used to bind another Linkerd process to the same interface port.
readTimeoutMs unbounded Configures this client or server with given transport-level socket read timeout in milliseconds.
writeTimeoutMs unbounded Configures this client or server with given transport-level socket write timeout in milliseconds.
keepAlive false If set to true, enables the SO_KEEPALIVE option, which will enable keep alive on the socket.
backlog None If set will adjust the backlog queue size of the socket, a default of None falls back to the OS defined value of SOMAXCONN

Routers

All configurations must define a routers key, the value of which must be an array of router configurations. Routers also include servers, which define their entry points, client, which configures how clients are built, and service, which configures service level policy.

Router Parameters

routers:
- protocol: http
  servers: ...
  service: ...
  client: ...
  announcers: ...
  bindingCache: ...
  label: myPackIce
  dstPrefix: /walruses/http
  dtab: |
    /host                => /#/io.l5d.fs;
    /walruses/http => /host;
  originator: true
  bindingTimeoutMs: 5000
Key Default Value Description
protocol required Either http, h2, thrift, or mux.
servers required A list of server objects.
announcers an empty list A list of service discovery announcers that servers can announce to.
dtab an empty dtab Sets the base delegation table. See dtabs for more.
bindingTimeoutMs 10 seconds The maximum amount of time in milliseconds to spend binding a path.
bindingCache see binding cache Binding cache size configuration.
client an empty object A client configuration object.
dstPrefix protocol dependent A path prefix to be used on request destinations.
originator false If true, indicates that this router is the first hop for linker-to-linker requests, and reflects that in the router’s stats. Useful for deduping linker-to-linker stats.
interpreter default interpreter An interpreter object determining what module will be used to process destinations.
label the value of protocol The name of the router (in stats and the admin ui)

Binding Cache

- protocol: http
  servers:
  - port: 9000
  bindingCache:
    paths: 100
    trees: 100
    bounds: 100
    clients: 10
    idleTtlSecs: 3600
Key Default Value Description
paths 1000 Max number of paths in the path cache.
trees 1000 Max number of trees in the tree cache.
bounds 1000 Max number of bounds in the bounds cache.
clients 1000 Max number of clients in the clients cache.
idleTtlSecs 10 minutes The amount of time, in seconds, to cache idle services and clients before expiring them.

Server Parameters

servers:
- port: 8080
  ip: 0.0.0.0
  tls:
    certPath: /foo/cert.pem
    keyPath: /foo/key.pem
  maxConcurrentRequests: 1000
  announce:
    - /#/io.l5d.serversets/discovery/prod/web
Key Default Value Description
port protocol dependent The TCP port number. Protocols may provide default values. If no default is provided, the port parameter is required.
ip loopback address The local IP address. A value like 0.0.0.0 configures the server to listen on all local IPv4 interfaces.
socketOptions none Socket options to set for the router interface. See Socket Options
tls no tls The server will serve over TLS if this parameter is provided. see TLS.
maxConcurrentRequests unlimited The maximum number of concurrent requests the server will accept.
announce an empty list A list of concrete names to announce using the router’s announcers.
clearContext false If true, all headers that set Linkerd contexts are removed from inbound requests. Useful for servers exposed on untrusted networks.

Service Configuration

This section defines the policy that Linkerd will use when talking to services. The structure of this section depends on its kind.

Key Default Value Description
kind io.l5d.global Either io.l5d.global or io.l5d.static

Global Service Config

- protocol: http
  service:
    kind: io.l5d.global
    totalTimeoutMs: 500
    retries:
      budget:
        minRetriesPerSec: 5
        percentCanRetry: 0.5
        ttlSecs: 15
      backoff:
        kind: jittered
        minMs: 10
        maxMs: 10000

This service configuration allows you to specify service parameters which will be applied to all services.

Static Service Config

- protocol: http
  service:
    kind: io.l5d.static
    configs:
    - prefix: /svc
      retries:
        budget:
          minRetriesPerSec: 5
          percentCanRetry: 0.5
          ttlSecs: 15
        backoff:
          kind: jittered
          minMs: 10
          maxMs: 10000
    - prefix: /svc/foo
      totalTimeoutMs: 500
    - prefix: /svc/bar
      totalTimeoutMs: 200

This service configuration allows you to specify service parameters which will be applied to all services that match a specified prefix. The service configuration must contain a property called configs which contains a list of config objects. Each config object must specify a prefix and the service parameters to apply to services that match that prefix. If a service matches more than one prefix, all parameters from the matching configs will be applied, with parameters defined later in the configuration file taking precedence over those defined earlier.

Service Parameters

Key Default Value Description
retries see retries A retry policy for application-level retries.
totalTimeoutMs no timeout The timeout for an entire request, including all retries, in milliseconds.
responseClassifier io.l5d.http.nonRetryable5XX A (sometimes protocol-specific) response classifier that determines which responses should be considered failures and, of those, which should be considered retryable.

Client Configuration

This section defines how the clients that Linkerd creates will be configured. The structure of this section depends on its kind.

Key Default Value Description
kind io.l5d.global Either io.l5d.global or io.l5d.static

Global Client Config

- protocol: http
  client:
    kind: io.l5d.global
    loadBalancer:
      kind: ewma
    failureAccrual:
      kind: io.l5d.consecutiveFailures
      failures: 10

This client configuration allows you to specify client parameters which will be applied to all clients.

Static Client Config

- protocol: http
  client:
    kind: io.l5d.static
    configs:
    - prefix: /#/io.l5d.fs
      loadBalancer:
        kind: ewma
    - prefix: /#/io.l5d.fs/{service}
      tls:
        commonName: "{service}.linkerd.io"
    - prefix: /$/inet/*/80
      failureAccrual:
        kind: io.l5d.consecutiveFailures
        failures: 10

This client configuration allows you to specify client parameters which will be applied to all clients that match a specified prefix. The client configuration must contain a property called configs which contains a list of config objects. Each config object must specify a prefix and the client parameters to apply to clients that match that prefix. A prefix may contain wildcards (*) and capture variables ({foo}) which can be referenced in some client parameters. If a client matches more than one config’s prefix, all parameters from the matching configs will be applied, with parameters defined later in the configuration file taking precedence over those defined earlier.

Note: Capture variables use greedy pattern matching. For example ({foo}{bar}) is ambiguous. The capture variable ({foo}) would capture the whole segement and ({bar}) would empty. Similary, the pattern ({foo}-{bar}) on the segement a-b-c would capture a-b into ({foo}) and c in ({bar}).

Client Parameters

client:
  tls:
    kind: io.l5d.noValidation
    commonName: foo
    caCertPath: /foo/caCert.pem
  requestAttemptTimeoutMs: 100
  loadBalancer:
    kind: ewma
    enableProbation: false
  requeueBudget:
    percentCanRetry: 0.25
  failureAccrual:
    kind: io.l5d.consecutiveFailures
    failures: 10
Key Default Value Description
hostConnectionPool An empty object see hostConnectionPool.
tls no tls The router will make requests using TLS if this parameter is provided. It must be a client TLS object.
loadBalancer p2c A load balancer object.
failFast false If true, connection failures are punished more aggressively. Should not be used with small destination pools.
requeueBudget see retry budget A requeue budget for connection-level retries.
failureAccrual 5 consecutive failures a failure accrual policy for all clients created by this router.
requestAttemptTimeoutMs no timeout The timeout, in milliseconds, for each attempt (original or retry) of the request made by this client.
clientSession An empty object see clientSession
requestAuthorizers none A list of request authorizers. See Http/1.1-specific request authorizers or HTTP/2-specific request authorizers.

Host Connection Pool

This section defines the behavior of watermark connection pools on which most of the protocols are relying. Note that Http2 protocol uses SingletonPool that maintains a single connection per endpoint and will not be affected by the settings in this section.

client:
  hostConnectionPool:
    minSize: 0
    maxSize: 1000
    idleTimeMs: 10000
    maxWaiters: 5000
Key Default Value Description
minSize 0 The minimum number of connections to maintain to each host.
maxSize Int.MaxValue The maximum number of connections to maintain to each host.
idleTimeMs forever The amount of idle time for which a connection is cached in milliseconds. Only applied to connections that number greater than minSize, but fewer than maxSize.
maxWaiters Int.MaxValue The maximum number of connection requests that are queued when the connection concurrency exceeds maxSize.

Client Session

Configures the behavior of established client sessions.

Key Default Value Description
idleTimeMs forever The max amount of time for which a connection is allowed to be idle. When this time exceeded the connection will close itself.
lifeTimeMs forever Max lifetime of a connection.

HTTP/1.1 protocol

Below: http-specific configuration options

routers:
- protocol: http
  httpAccessLog: access.log
  httpAccessLogRollPolicy: daily
  httpAccessLogAppend: true
  httpAccessLogRotateCount: -1
  identifier:
    kind: io.l5d.methodAndHost
  maxHeadersKB: 8
  maxInitialLineKB: 4
  maxRequestKB: 5120
  maxResponseKB: 5120
  servers:
  - port: 5000
    addForwardedHeader:
      by: {kind: "ip:port"}
      for: {kind: ip}

protocol: http

The HTTP/1.1 protocol is used when the protocol option of the routers configuration block is set to http. This protocol has additional configuration options on the routers block.

Key Default Value Description
dstPrefix /svc A path prefix used by Http-specific identifiers.
httpAccessLog none Sets the access log path. If not specified, no access log is written.
httpAccessLogRollPolicy never When to roll the logfile. Possible values: Never, Hourly, Daily, Weekly(n) (where n is a day of the week), util-style data size strings (e.g. 3.megabytes, 1.gigabyte).
httpAccessLogAppend true Append to an existing logfile, or truncate it?
httpAccessLogRotateCount -1 How many rotated logfiles to keep around, maximum. -1 means to keep them all.
identifier The io.l5d.header.token identifier An identifier or list of identifiers. See Http-specific identifiers.
streamAfterContentLengthKB 5 The threshold at which HTTP messages will be streamed if exceeded.
maxHeadersKB 8 The maximum size of all headers in an HTTP message.
maxInitialLineKB 4 The maximum size of an initial HTTP message line.
maxRequestKB 5120 The maximum size of a non-chunked HTTP request payload.
maxResponseKB 5120 The maximum size of a non-chunked HTTP response payload.
compressionLevel -1, automatically compresses textual content types with compression level 6 The compression level to use (on 0-9).
streamingEnabled true Streaming allows Linkerd to work with HTTP messages that have large (or infinite) content bodies using chunked encoding. Disabling this is highly discouraged.
tracePropagator io.l5d.default A trace propagator. See Http-specific trace propagator.

HTTP Servers

HTTP servers accept additional configuration parameters.

Example: default

addForwardedHeader: {}
timestampHeader: {}
Key Default Value Description
addForwardedHeader null If set, a Forwarded header is added to all requests. See below.
timestampHeader null If set, the specified header will be added to outbound requests with a timestamp. See below.

Adding Timestamp Headers

Example:

timestampHeader: X-Request-Start

Some systems, such as New Relic, use a header with a timestamp to measure performance. The optional timestampHeader: configuration instructs the HTTP server to add a (millisecond-resolution) timestamp on all outbound requests with the specified header.

Adding the Forwarded header

RFC 7239 describes how a Forwarded header may be added to requests by proxies. This RFC requests that this header not be added unless explicitly configured and that proxies obfuscate IP addresses unless explicitly configured to transmit them.

Key Default Value Description
by {kind: requestRandom} The labeler to use with the router’s server address
for {kind: requestRandom} The labeler to use with the upstream client’s address

Endpoint labelers

The Forwarded header includes labels describing the endpoints of the upstream connection. Because this is sensitive information, it is typically randomized.

addForwardedHeader:
  for: {kind: ip}
  by:
    kind: static
    label: linkerd
Kind Description
ip A textual IP address like 192.168.1.1 or "[2001:db8:cafe::17]".
ip:port A textual IP:PORT address like "192.168.1.1:80" or "[2001:db8:cafe::17]:80".
connectionRandom An obfuscated random label like _6Oq8jJ generated for all requests on a connection.
requestRandom An obfuscated random label like _6Oq8jJ generated for each request.
router Uses the router’s label as an obfuscated static label.
static Accepts a label parameter. Produces obfuscated static labels like _linkerd.

HTTP Client Parameters

Key Default Value Description
forwardClientCert false Determines if client certificates are forwarded through the x-forwarded-client-cert header of a request.

HTTP/1.1 Identifiers

Identifiers are responsible for creating logical names from an incoming request; these names are then matched against the dtab. (See the Linkerd routing overview for more details on this.) All HTTP/1.1 identifiers have a kind. If a list of identifiers is provided, each identifier is tried in turn until one successfully assigns a logical name to the request.

If no identifier is specified the io.l5d.header.token identifier is used.

Key Default Value Description
kind required Either io.l5d.methodAndHost, io.l5d.path, io.l5d.header, io.l5d.header.token, or io.l5d.static.

Method and Host Identifier

kind: io.l5d.methodAndHost.

With this identifier, HTTP requests are turned into logical names using a combination of Host header, method, and (optionally) URI. Host header value is lower-cased as per RFC 2616.

Identifier Configuration:

Configuration example

identifier:
  kind: io.l5d.methodAndHost
  httpUriInDst: true
Key Default Value Description
httpUriInDst false If true http paths are appended to destinations. This allows a form of path-prefix routing. This option is not recommended as performance implications may be severe; Use the path identifier instead.

Identifier Path Parameters:

Dtab Path Format for HTTP/1.1

  / dstPrefix / "1.1" / method / host [/ uri* ]

Dtab Path Format for HTTP/1.0

  / dstPrefix / "1.0" / method [/ uri* ]
Key Default Value Description
dstPrefix /svc The dstPrefix as set in the routers block.
method N/A The HTTP method of the current request, ie OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, or CONNECT.
host N/A The value of the current request’s Host header. Case sensitive!. Not used in HTTP/1.0.
uri Not used Only considered a part of the logical name if the config option httpUriInDst is true.

Path Identifier

kind: io.l5d.path

With this identifier, HTTP requests are turned into names based only on the path component of the URL, using a configurable number of “/” separated segments from the start of their HTTP path.

Identifier Configuration:

With this configuration, a request to :5000/true/love/waits.php will be mapped to /svc/true/love and will be routed based on this name by the corresponding dtab. Additionally, because consume is true, after routing, requests will be proxied to the destination service with /waits.php as the path component of the URL.

routers:
- protocol: http
  identifier:
    kind: io.l5d.path
    segments: 2
    consume: true
  servers:
  - port: 5000
Key Default Value Description
segments 1 Number of segments from the path that are appended to destinations.
consume false Whether to additionally strip the consumed segments from the HTTP request proxied to the final destination service. This only affects the request sent to the destination service; it does not affect identification or routing.

Identifier Path Parameters:

Dtab Path Format

  / dstPrefix [/ *urlPath ]
Key Default Value Description
dstPrefix /svc The dstPrefix as set in the routers block.
urlPath N/A A path from the URL whose number of segments is set in the identifier block.

Header Identifier

kind: io.l5d.header

With this identifier, HTTP requests are turned into names based only on the value of an HTTP header. The value of the HTTP header is interpreted as a path and therefore must start with a /.

Identifier Configuration:

With this configuration, the value of the my-header HTTP header will be used as the logical name.

routers:
- protocol: http
  identifier:
    kind: io.l5d.header
    header: my-header
  servers:
  - port: 5000
Key Default Value Description
header l5d-name The name of the HTTP header to use

Identifier Path Parameters:

Dtab Path Format

  / dstPrefix [*headerValue ]
Key Default Value Description
dstPrefix /svc The dstPrefix as set in the routers block.
headerValue N/A The value of the HTTP header as a path.

Header Token Identifier

kind: io.l5d.header.token

With this identifier, HTTP requests are turned into names based only on the value of an HTTP header. The name is a path with one segment and the value of that segment is taken from the HTTP header.

Identifier Configuration:

With this configuration, the value of the my-header HTTP header will be used as the logical name.

routers:
- protocol: http
  identifier:
    kind: io.l5d.header.token
    header: my-header
  servers:
  - port: 5000
Key Default Value Description
header Host The name of the HTTP header to use

Identifier Path Parameters:

Dtab Path Format

  / dstPrefix / [headerValue]
Key Default Value Description
dstPrefix /svc The dstPrefix as set in the routers block.
headerValue N/A The value of the HTTP header as a path segment.

Ingress Identifier

kind: io.l5d.ingress

Using this identifier enables Linkerd to function as a Kubernetes ingress controller. The ingress identifier compares HTTP requests to ingress resource rules, and assigns a name based on those rules.

Identifier Configuration:

This example watches all ingress resources in the default namespace:

routers:
- protocol: http
  identifier:
    kind: io.l5d.ingress
    namespace: default
  servers:
  - port: 4140
  dtab: /svc => /#/io.l5d.k8s

namers:
- kind: io.l5d.k8s

An example ingress resource watched by the Linkerd ingress controller:

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: my-first-ingress
  namespace: default
annotations:
  kubernetes.io/ingress.class: "linkerd"
spec:
  rules:
  - http:
      paths:
      - path: /testpath
        backend:
          serviceName: test
          servicePort: 80

So an HTTP request like http://localhost:4140/testpath would have an identified name of /svc/default/80/test

Key Default Value Description
namespace (all) The Kubernetes namespace where the ingress resources are deployed. If not specified, Linkerd will watch all namespaces.
ingressClassAnnotation linkerd When using multiple ingress controllers, Linkerd will only use the ingress resource annotated with this class.
ignoreDefaultBackends false Identify requests only when they match an explicit ingress rule specifying a host and/or path.
host localhost The Kubernetes master host.
port 8001 The Kubernetes master port.

Identifier Path Parameters

Dtab Path Format

  / dstPrefix / namespace / port / service
Key Default Value Description
dstPrefix /svc The dstPrefix as set in the routers block.
namespace N/A The Kubernetes namespace.
port N/A The port name.
svc N/A The name of the service.

Istio Identifier (Deprecated)

kind: io.l5d.k8s.istio

This identifier compares HTTP requests to istio route-rules and assigns a name based on those rules.

#### Identifier Configuration:

routers:
- protocol: http
  identifier:
    kind: io.l5d.k8s.istio
Key Default Value Description
discoveryHost istio-pilot The host of the Istio-Pilot.
discoveryPort 8080 The port of the Istio-Pilot’s discovery service.
apiserverHost istio-pilot The host of the Istio-Pilot.
apiserverPort 8081 The port of the Istio-Pilot’s apiserver.

Identifier Path Parameters

Dtab Path Format if the request does not point to a valid k8s cluster

  / dstPrefix / "ext" / host / port

Dtab Path Format if the request has a valid cluster but DOES NOT match a route-rule

  / dstPrefix / "dest" / cluster / "::" / port

Dtab Path Format if the request matches a route-rule

  / dstPrefix / "route" / routeRule
Key Default Value Description
dstPrefix /svc The dstPrefix as set in the routers block.
routeRule N/A The name of the route-rule that matches the incoming request.
host N/A The host to send the request to.
cluster N/A The cluster to send the request to.
port N/A The port to send the request to.

Static Identifier

kind: io.l5d.static

This identifier always assigns the same static name to all requests.

Identifier Configuration:

routers:
- protocol: http
  identifier:
    kind: io.l5d.static
    path: /foo/bar
Key Default Value Description
path required The name to assign to all requests

Identifier Path Parameters

Dtab Path Format

  / dstPrefix / *path
Key Default Value Description
dstPrefix /svc The dstPrefix as set in the routers block.
path N/A The path given in the configuration.

HTTP/1.1 Request Authorizers

Request authorizers allow arbitrary rejection or modification of requests and responses. Behavior is specific to each request authorizer. All HTTP/1.1 request authorizers have a kind. If a list of request authorizers is provided, they each apply in the order they are defined.

Key Default Value Description
kind required Only io.l5d.k8s.istio is currently supported.

Istio Request Authorizer (Deprecated)

kind: io.l5d.k8s.istio.

With this request authorizer, all HTTP requests are sent to an Istio Mixer for telemetry recording and aggregation.

Request Authorizer Configuration:

Configuration example

requestAuthorizers:
- kind: io.l5d.k8s.istio
  mixerHost: istio-mixer
  mixerPort: 9091
Key Default Value Description
mixerHost istio-mixer Hostname of the Istio Mixer server.
mixerPort 9091 Port of the Mixer server.

HTTP/1.1 Trace Propagators

Trace propagators are responsible for propagating distributed tracing data from requests that Linkerd receives to requests that Linkerd sends. The trace propagator reads trace context from a received request (usually from request headers) and stores it in a request local context. The trace propagator is also responsible for writing this trace context into requests that Linkerd sends (usually into request headers).

Key Default Value Description
kind required One of io.l5d.default, io.l5d.zipkin.

Default Trace Propagator

kind: io.l5d.default.

The default trace propagator stores the trace id in the l5d-ctx-trace request header. It also reads the l5d-sample and, if present, uses this value as the sample rate for this request.

Zipkin Trace Propagator

kind: io.l5d.zipkin.

A trace propagator that writes Zipkin B3 trace headers to outgoing requests. Processes B3 Headers received from upstream as well.

Header Content
x-b3-traceid 128 or 64 lower-hex encoded bits (required)
x-b3-spanid 64 lower-hex encoded bits (required)
x-b3-parentspanid 64 lower-hex encoded bits (absent on root span)
x-b3-sampled Boolean (either “1” or “0”, can be absent)
x-b3-flags ‘1’ means debug (can be absent)

Configuration example

tracePropagator:
  kind: io.l5d.zipkin

HTTP Headers

Linkerd reads and sets several headers prefixed by l5d-.

Context Headers

Context headers (l5d-ctx-*) are generated and read by Linkerd instances. Applications should forward all context headers in order for all Linkerd features to work.

Header Description
dtab-local Deprecated. Use l5d-ctx-dtab and l5d-dtab.
l5d-ctx-deadline Describes time bounds within which a request is expected to be satisfied. Currently deadlines are only advisory and do not factor into request cancellation.
l5d-ctx-trace Encodes Zipkin-style trace IDs and flags so that trace annotations emitted by Linkerd may be correlated.

User Headers

Append a dtab override to the dtab for this request

curl -H 'l5d-dtab: /host/web => /host/web-v2' "localhost:5000"

User headers enable user-overrides.

Header Description
l5d-dtab A client-specified delegation override.
l5d-sample A client-specified trace sample rate override.

Informational Request Headers

The informational headers Linkerd emits on outgoing requests.

Header Description
l5d-dst-service The logical service name of the request as identified by Linkerd.
l5d-dst-client The concrete client name after delegation.
l5d-dst-residual An optional residual path remaining after delegation.
l5d-reqid A token that may be used to correlate requests in a callgraph across services and Linkerd instances.

Applications are not required to forward these headers on downstream requests.

Informational Response Headers

The informational headers Linkerd emits on outgoing responses.

Header Description
l5d-err Indicates a Linkerd-generated error. Error responses that do not have this header are application errors.
l5d-retryable Indicates that the request for this response is known to be safe to retry (for example, because it was not delivered to its destination).

Applications should not forward these headers on upstream responses.

HTTP/2 protocol

Below: Authority (Host) based routing for HTTP/2 over TLS

routers:
- protocol: h2
  h2AccessLog: access.log
  h2AccessLogRollPolicy: daily
  h2AccessLogAppend: true
  h2AccessLogRotateCount: -1
  servers:
  - port: 4143
    tls:
      certPath: .../public/linkerd.pem
      keyPath: .../private/linkerd.pem
      caCertPath: .../ca.pem
  identifier:
    kind: io.l5d.header.token
    header: ":authority"
  dtab: |
    /svc => /#/io.l5d.fs ;
  client:
    prefix: "/#/io.l5d.fs/{service}"
    tls:
      kind: io.l5d.boundPath
      caCertPath: .../ca.pem
      commonName: "{service}"

Below: plaintext gRPC

routers:
- protocol: h2
  label: grpc
  servers:
  - port: 4142
  identifier:
    kind: io.l5d.header.path
    segments: 2
  dtab: |
    /svc => /#/io.l5d.fs ;

because gRPC encodes URLs as /serviceName/methodName, we can simply register service names into a discovery system and route accordingly. Note that gRPC may be configured over TLS as well.

protocol: h2

The HTTP/2 protocol is used when the protocol option of the routers configuration block is set to h2. This protocol has additional configuration options on the routers block.

Key Default Value Description
dstPrefix /svc A path prefix used by H2-specific identifiers.
h2AccessLog none Sets the access log path. If not specified, no access log is written.
h2AccessLogRollPolicy never When to roll the logfile. Possible values: Never, Hourly, Daily, Weekly(n) (where n is a day of the week), util-style data size strings (e.g. 3.megabytes, 1.gigabyte).
h2AccessLogAppend true Append to an existing logfile, or truncate it?
h2AccessLogRotateCount -1 How many rotated logfiles to keep around, maximum. -1 means to keep them all.
identifier The io.l5d.header.token identifier An identifier or list of identifiers. See H2-specific identifiers.
tracePropagator io.l5d.default A trace propagator. See H2-specific trace propagator.

When TLS is configured, h2 routers negotiate to communicate over HTTP/2 via ALPN.

When TLS is not configured, h2 servers accept both prior knowledge and HTTP Upgrade requests. Plaintext clients are currently only capable of issuing prior-knowledge requests.

HTTP/2 Server Parameters

Key Default Value Description
windowUpdateRatio 0.99 A number between 0 and 1, exclusive, indicating the ratio at which window updates should be sent. With a value of 0.75, updates will be sent when the available window size is 75% of its capacity.
headerTableBytes none Configures SETTINGS_HEADER_TABLE_SIZE on new streams.
initialStreamWindowBytes 64KB Configures SETTINGS_INITIAL_WINDOW_SIZE on streams.
maxConcurrentStreamsPerConnection 1000 Configures SETTINGS_MAX_CONCURRENT_STREAMS on new streams.
maxFrameBytes 16KB Configures SETTINGS_MAX_FRAME_SIZE on new streams.
maxHeaderListByts none Configures SETTINGS_MAX_HEADER_LIST_SIZE on new streams.

HTTP/2 Service Parameters

Key Default Value Description
classificationTimeoutMs 100ms The amount of time to wait for a response stream to complete before determining if it should be retried.
retryBufferSize see below A RetryBufferSize object describing the size of the buffers for request and response streams used for retries.

RetryBufferSize

Key Default Value Description
requestBytes 16383 If the request stream exceeds this value, the request cannot be retried.
responseBytes 16383 If the response stream exceeds this value, the request cannot be retried.

HTTP/2 Client Parameters

Key Default Value Description
windowUpdateRatio: 0.99 A number between 0 and 1, exclusive, indicating the ratio at which window updates should be sent. With a value of 0.75, updates will be sent when the available window size is 75% of its capacity.
headerTableBytes none Configures SETTINGS_HEADER_TABLE_SIZE on new streams.
initialStreamWindowBytes 64KB Configures SETTINGS_INITIAL_WINDOW_SIZE on streams.
maxFrameBytes 16KB Configures SETTINGS_MAX_FRAME_SIZE on new streams.
maxHeaderListByts none Configures SETTINGS_MAX_HEADER_LIST_SIZE on new streams.
forwardClientCert false Determines if client certificates are forwarded through the x-forwarded-client-cert header of a request.
requestAuthorizers none A list of request authorizers. See H2-specific request authorizers.

HTTP/2 Identifiers

Identifiers are responsible for creating logical names from an incoming request; these names are then matched against the dtab. (See the Linkerd routing overview for more details on this.) All h2 identifiers have a kind. If a list of identifiers is provided, each identifier is tried in turn until one successfully assigns a logical name to the request.

Key Default Value Description
kind required Either io.l5d.header.token, io.l5d.header.path, or io.l5d.ingress.

HTTP/2 Header Token identifier

kind: io.l5d.header.token.

With this identifier, requests are turned into logical names using the value of the named header. By default, the :authority pseudo-header is used to provide host-based routing.

Namer Configuration:

With this configuration, the value of the my-header header will be used as the logical name.

routers:
- protocol: h2
  identifier:
    kind: io.l5d.header.token
    header: my-header
  servers:
  - port: 5000
Key Default Value Description
header :authority The name of the header to extract a token from. If there are multiple headers with this name, the last one is used.

Namer Path Parameters:

Dtab Path Format

  / dstPrefix / headerValue
Key Default Value Description
dstPrefix /svc The dstPrefix as set in the routers block.
headerValue N/A The value of the header.

HTTP/2 Header Path Identifier

kind: io.l5d.header.path

With this identifier, requests are identified using a path read from a header. This is useful for routing gRPC requests. By default, the :path pseudo-header is used.

Namer Configuration:

With this configuration, a request to :5000/true/love/waits.php?thing=1 will be mapped to /svc/true/love and will be routed based on this name by the corresponding Dtab.

routers:
- protocol: h2
  identifier:
    kind: io.l5d.header.path
    segments: 2
  servers:
  - port: 5000
Key Default Value Description
header :path The name of the header to extract a Path from. If there are multiple headers with this name, the last one is used.
segments None If specified, the number of path segments that are required extracted from each request.

Namer Path Parameters:

Dtab Path Format

  / dstPrefix / *urlPath
Key Default Value Description
dstPrefix /svc The dstPrefix as set in the routers block.
urlPath N/A The first segments elements of the path from the URL

HTTP/2 Ingress Identifier

kind: io.l5d.ingress

Using this identifier enables Linkerd to function as a Kubernetes ingress controller. The ingress identifier compares HTTP/2 requests to ingress resource rules, and assigns a name based on those rules.

Identifier Configuration:

This example watches all ingress resources in the default namespace:

routers:
- protocol: h2
  identifier:
    kind: io.l5d.ingress
    namespace: default
  servers:
  - port: 4140
  dtab: /svc => /#/io.l5d.k8s

namers:
- kind: io.l5d.k8s

An example ingress resource watched by the Linkerd ingress controller:

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: my-first-ingress
  namespace: default
annotations:
  kubernetes.io/ingress.class: "linkerd"
spec:
  rules:
  - http:
      paths:
      - path: /testpath
        backend:
          serviceName: test
          servicePort: 80

So an HTTP/2 request like https://localhost:4140/testpath would have an identified name of /svc/default/80/test

Key Default Value Description
namespace (all) The Kubernetes namespace where the ingress resources are deployed. If not specified, Linkerd will watch all namespaces.
ingressClassAnnotation linkerd When using multiple ingress controllers, Linkerd will only use the ingress resource annotated with this class.
ignoreDefaultBackends false Identify requests only when they match an explicit ingress rule specifying a host and/or path.
host localhost The Kubernetes master host.
port 8001 The Kubernetes master port.

Identifier Path Parameters

Dtab Path Format

  / dstPrefix / namespace / port / service
Key Default Value Description
dstPrefix /svc The dstPrefix as set in the routers block.
namespace N/A The Kubernetes namespace.
port N/A The port name.
svc N/A The name of the service.

HTTP/2 Istio Identifier (Deprecated)

kind: io.l5d.k8s.istio

This identifier compares H2 requests to istio route-rules and assigns a name based on those rules.

Identifier Configuration:

routers:
- protocol: h2
  identifier:
    kind: io.l5d.k8s.istio
Key Default Value Description
discoveryHost istio-pilot The host of the Istio-Pilot.
discoveryPort 8080 The port of the Istio-Pilot’s discovery service.
apiserverHost istio-pilot The host of the Istio-Pilot.
apiserverPort 8081 The port of the Istio-Pilot’s apiserver.

Identifier Path Parameters

Dtab Path Format if the request does not point to a valid k8s cluster

  / dstPrefix / "ext" / host / port

Dtab Path Format if the request has a valid cluster but DOES NOT match a route-rule

  / dstPrefix / "dest" / cluster / "::" / port

Dtab Path Format if the request matches a route-rule

  / dstPrefix / "route" / routeRule
Key Default Value Description
dstPrefix /svc The dstPrefix as set in the routers block.
routeRule N/A The name of the route-rule that matches the incoming request.
host N/A The host to send the request to.
cluster N/A The cluster to send the request to.
port N/A The port to send the request to.

HTTP/2 Request Authorizers

Request authorizers allow arbitrary rejection or modification of requests and responses. Behavior is specific to each request authorizer. All HTTP/2 request authorizers have a kind. If a list of request authorizers is provided, they each apply in the order they are defined.

Key Default Value Description
kind required Only io.l5d.k8s.istio is currently supported.

HTTP/2 Istio Request Authorizer (Deprecated)

kind: io.l5d.k8s.istio.

With this request authorizer, all H2 requests are sent to an Istio Mixer for telemetry recording and aggregation.

Request Authorizer Configuration:

Configuration example

requestAuthorizers:
- kind: io.l5d.k8s.istio
  mixerHost: istio-mixer
  mixerPort: 9091
Key Default Value Description
mixerHost istio-mixer Hostname of the Istio Mixer server.
mixerPort 9091 Port of the Mixer server.

HTTP/2 Trace Propagators

Trace propagators are responsible for propagating distributed tracing data from requests that Linkerd receives to requests that Linkerd sends. The trace propagator reads trace context from a received request (usually from request headers) and stores it in a request local context. The trace propagator is also responsible for writing this trace context into requests that Linkerd sends (usually into request headers).

Key Default Value Description
kind required One of io.l5d.default, io.l5d.zipkin.

Default Trace Propagator

kind: io.l5d.default.

The default trace propagator stores the trace id in the l5d-ctx-trace request header. It also reads the l5d-sample and, if present, uses this value as the sample rate for this request.

Zipkin Trace Propagator

kind: io.l5d.zipkin.

A trace propagator that writes Zipkin B3 trace headers to outgoing requests. Processes B3 Headers received from upstream as well.

Header Content
x-b3-traceid 128 or 64 lower-hex encoded bits (required)
x-b3-spanid 64 lower-hex encoded bits (required)
x-b3-parentspanid 64 lower-hex encoded bits (absent on root span)
x-b3-sampled Boolean (either “1” or “0”, can be absent)
x-b3-flags ‘1’ means debug (can be absent)

Configuration example

tracePropagator:
  kind: io.l5d.zipkin

HTTP/2 Headers

Linkerd reads and sets several headers prefixed by l5d-, as is done by the http protocol.

HTTP/2 Context Headers

Context headers (l5d-ctx-*) are generated and read by Linkerd instances. Applications should forward all context headers in order for all Linkerd features to work.

Header Description
dtab-local Deprecated. Use l5d-ctx-dtab and l5d-dtab.
l5d-ctx-deadline Describes time bounds within which a request is expected to be satisfied. Currently deadlines are only advisory and do not factor into request cancellation.
l5d-ctx-trace Encodes Zipkin-style trace IDs and flags so that trace annotations emitted by Linkerd may be correlated.

HTTP/2 User Headers

Append a dtab override to the dtab for this request

curl -H 'l5d-dtab: /host/web => /host/web-v2' "localhost:5000"

User headers enable user-overrides.

Header Description
l5d-dtab A client-specified delegation override.
l5d-sample A client-specified trace sample rate override.

HTTP/2 Informational Request Headers

The informational headers Linkerd emits on outgoing requests.

Header Description
l5d-dst-service The logical service name of the request as identified by Linkerd.
l5d-dst-client The concrete client name after delegation.
l5d-dst-residual An optional residual path remaining after delegation.
l5d-reqid A token that may be used to correlate requests in a callgraph across services and Linkerd instances.

Applications are not required to forward these headers on downstream requests.

HTTP/2 Informational Response Headers

The informational headers Linkerd emits on outgoing responses.

Header Description
l5d-err Indicates a Linkerd-generated error. Error responses that do not have this header are application errors.

Applications are not required to forward these headers on upstream responses.

Thrift Protocol

This config routes thrift (via buffered transport using the TCompactProtocol) from port 4004 to port 5005

routers:
- protocol: thrift
  label: port-shifter
  dtab: |
    /svc => /$/inet/127.1/5005;
  thriftProtocol: compact
  servers:
  - port: 4004
    ip: 0.0.0.0
    thriftFramed: false
  client:
    thriftFramed: false

protocol: thrift

If the TTwitter thrift protocol is used, the value from the dest request header will be used for routing:

Dtab Path Format For Thrift / dstPrefix [/ dest] [/ thriftMethod ]

Otherwise, the Thrift protocol does not encode a destination name in the message itself and the dest part of the path will be absent.

Thrift Router Parameters

Key Default Value Description
dstPrefix /svc A path prefix used in dtab.
thriftMethodInDst false If true, thrift method names are appended to destinations for outgoing requests.
thriftProtocol binary Either binary (TBinaryProtocol) or compact (TCompactProtocol). Applies to both clients and servers.

Thrift Server Parameters

Key Default Value Description
port 4114 The TCP port number.
thriftFramed true If true, a framed thrift transport is used for incoming requests; otherwise, a buffered transport is used. Typically this setting matches the router’s thriftFramed param.

Thrift Client Parameters

Key Default Value Description
thriftFramed true If true, a framed thrift transport is used for outgoing requests; otherwise, a buffered transport is used. Typically this setting matches the router’s servers’ thriftFramed param.
attemptTTwitterUpgrade false Controls whether thrift protocol upgrade should be attempted.

ThriftMux Protocol (experimental)

This config routes thriftmux from port 4400 to port 5005.

routers:
- protocol: thriftmux
  experimental: true
  label: port-shifter
  dtab: |
    /svc => /$/inet/127.1/5005;
  servers:
  - port: 4400
    ip: 0.0.0.0

protocol: thriftmux

Linkerd experimentally supports the thriftmux protocol.

Thriftmux protocol is capable of routing traffic to pure thrift service and will use Thrift protocol on the client.

Protocol configuration uses the same parameters as Thrift protocol.

ThriftMux Router Parameters

See Thrift Router Parameters

ThriftMux Server Parameters

See Thrift Server Parameters

ThriftMux Client Parameters

See Thrift Client Parameters

Mux Protocol (experimental)

A mux router configuration that routes requests to port 9001


routers:
- protocol: mux
  label: power-level-router
  dstPrefix: /overNineThousand
  dtab: |
    /overNineThousand => /$/inet/127.0.1/9001;

protocol: mux

Linkerd experimentally supports the mux protocol.

Mux Router Parameters

Key Default Value Description
dstPrefix /svc A path prefix used in dtab.

Mux Server Parameters

Key Default Value Description
port 4141 The TCP port number.

Interpreter

Example Interpreter Configuration

routers:
- ...
  interpreter:
    kind: io.l5d.namerd
    dst: /$/inet/1.2.3.4/4180

An interpreter determines how names are resolved.

Key Default Value Description
kind default Either default, io.l5d.namerd, io.l5d.namerd.http, io.l5d.mesh, io.l5d.fs, io.l5d.consul.interpreter or io.l5d.k8s.configMap.
transformers No transformers A list of transformers to apply to the resolved addresses.

Default

kind: default

The default interpreter resolves names via the configured namers, with a fallback to the default Finagle Namer.Global that handles paths of the form /$/.

Namerd thrift

kind: io.l5d.namerd

The Namerd thrift interpreter offloads the responsibilities of name resolution to the Namerd service. Any namers configured in this Linkerd are not used. The interpreter uses Namerd’s long-poll thrift interface (io.l5d.thriftNameInterpreter). Note that the protocol that the interpreter uses to talk to Namerd is unrelated to the protocols of Linkerd’s routers.

The internal state of the Namerd interpreter can be viewed at the admin endpoint: /<router>/interpreter_state/io.l5d.namerd/<namespace>.json.

Key Default Value Description
dst required A Finagle path locating the Namerd service.
namespace default The name of the Namerd dtab to use.
retry see Namerd retry An object configuring retry backoffs for requests to Namerd.
tls no tls Requests to Namerd will be made using TLS if this parameter is provided. It must be a Namerd client TLS object.
failureThreshold no failureThreshold Sets the failure threshold used by Linkerd’s threshold failure detector to gauge a Namerd instance’s health

Failure Threshold

Linkerd uses a Threshold Failure Detector to determine the health of the connection to a Namerd instance. Linkerd sends pings to Namerd periodically and evaluates the health of Namerd based on a set number of ping latencies

Key Default Value Description
minPeriodMs 5000 The period between session pings to Namerd
closeTimeoutMs 4000 Timeout for a session ping’s response before Linkerd terminates a session

Namerd retry

Key Default Value Description
baseSeconds 5 seconds The base number of seconds to wait before retrying.
maxSeconds 10 minutes The maximum number of seconds to wait before retrying.

Namerd client tls

Key Default Value Description
commonName required The common name to use for Namerd requests.
caCert N/A The path to the CA cert used for common name validation.

Namerd http

kind: io.l5d.namerd.http

The Namerd http interpreter offloads the responsibilities of name resolution to the Namerd service. Any namers configured in this Linkerd are not used. The interpreter uses Namerd’s HTTP streaming interface (io.l5d.httpController). Note that the protocol that the interpreter uses to talk to Namerd is unrelated to the protocols of Linkerd’s routers.

Key Default Value Description
experimental required Because the http interpreter is still considered experimental, you must set this to true to use it.
dst required A Finagle path locating the Namerd service.
namespace default The name of the Namerd dtab to use.
retry see Namerd retry An object configuring retry backoffs for requests to Namerd.
tls no tls Requests to Namerd will be made using TLS if this parameter is provided. It must be a client TLS object.

Namerd mesh

kind: io.l5d.mesh

The Namerd mesh interpreter offloads the responsibilities of name resolution to the Namerd service. Any namers configured in this Linkerd are not used. The interpreter uses Namerd’s gRPC mesh interface (io.l5d.mesh). Note that the protocol that the interpreter uses to talk to Namerd is unrelated to the protocols of Linkerd’s routers.

The internal state of the Namerd interpreter can be viewed at the admin endpoint: /<router>/interpreter_state/io.l5d.mesh/<root>.json.

Key Default Value Description
dst required A Finagle path locating the Namerd service.
root /default A single-element Finagle path representing the Namerd namespace.
retry see Namerd retry An object configuring retry backoffs for requests to Namerd.
tls no tls Requests to Namerd will be made using TLS if this parameter is provided. It must be a client TLS object.

File-System

kind: io.l5d.fs

The file-system interpreter resolves names via the configured namers, just like the default interpreter, but also uses a dtab read from a file on the local file-system. The specified file is watched for changes so that the dtab may be edited live.

Key Default Value Description
dtabFile required The file-system path to a file containing a dtab.

Kubernetes ConfigMap

kind: io.l5d.k8s.configMap

The Kubernetes ConfigMap interpreter resolves names via the configured namers, just like the default interpreter, but also uses a dtab read from a ConfigMap using the Kubernetes API. The specified ConfigMap is watched for changes, as in the file-system interpreter.

Example configuration

routers:
- ...
  interpreter:
    kind: io.l5d.k8s.configMap
    experimental: true
    name: dtabs
    filename: my-dtab
Key Default Value Description
experimental required Because the ConfigMap interpreter is still considered experimental, you must set this to true to use it.
name required The name of the ConfigMap object containing the dtab
filename required The ConfigMap key corresponding to the desired dtab
host localhost The Kubernetes master host.
port 8001 The Kubernetes master port.
namespace default The Kubernetes namespace containing the ConfigMap

Consul Interpreter

The Consul Interpreter uses dtabs read from a Consul KV store. The interpreter watches for changes to dtabs stored at the specified pathPrefix.

The current state of Consul stored dtabs can be viewed at the admin endpoint: /interpreter_state/io.l5d.consul.interpreter.json.

Example configuration

routers:
- ...
  interpreter:
    kind: io.l5d.consul.interpreter
    host: localhost
    port: 8500
    namespace: default

Key Default value Description
host localhost The location of the consul API.
port 8500 The port used to connect to the consul API.
pathPrefix /namerd/dtabs The key path under which dtabs should be stored.
token no auth The auth token to use when making API calls.
datacenter uses agent’s datacenter The datacenter to forward requests to.
readConsistencyMode default Select between Consul API consistency modes such as default, stale and consistent for reads.
writeConsistencyMode default Select between Consul API consistency modes such as default, stale and consistent for writes.
failFast false If false, disable fail fast and failure accrual for Consul client. Keep it false when using a local agent but change it to true when talking directly to an HA Consul API.
backoff exponential backoff from 1ms to 1min Object that determines which backoff algorithm should be used. See retry backoff
tls no tls Use TLS during connection with Consul. see Consul Encryption and Namer TLS.

Transformer

Example Transformer Configuration

routers:
- ...
  interpreter:
    ...
    transformers:
    - kind: io.l5d.localhost

Transformers perform a transformation on the addresses resolved by the interpreter. Transformations are applied sequentially in the order they appear.

Key Default Value Description
kind required Either io.l5d.localhost, io.l5d.specificHost, io.l5d.port, io.l5d.k8s.daemonset, io.l5d.k8s.localnode, io.l5d.replace, or io.l5d.const.

Localhost

kind: io.l5d.localhost

The localhost transformer filters the list of addresses down to only addresses that have the same IP address as localhost. The IP of localhost is determined by doing a one-time DNS lookup of the local hostname. This transformer can be used by an incoming router to route traffic only to local destinations.

Specific Host

kind: io.l5d.specificHost

The specific host transformer filters the list of addresses down to only addresses that have the same IP address as the specified host. This transformer can be used by an incoming router to only route traffic to specific destinations. This is useful when Linkerd is running inside a Docker container and the traffic is to be sent to another Docker container on the same host.

Key Default Value Description
host required The host to use.

Port

kind: io.l5d.port

The port transformer replaces the port number in every address with a configured value. This can be used if there is an incoming Linkerd router (or other reverse-proxy) running on a fixed port on each host and you wish to send traffic to that port instead of directly to the destination address.

Key Default Value Description
port required The port number to use.

DaemonSet (Kubernetes)

kind: io.l5d.k8s.daemonset

The DaemonSetTransformer maps each address in the destination NameTree to a member of a given daemonset that is on the same /24 subnet. Since each Kubernetes node is its own /24 subnet, the result is that each destination address is mapped to the member of the daemonset that is running on the same node. This can be used to redirect traffic to a reverse-proxy that runs as a daemonset.

This transformer assumes that there is a Kubernetes service for the daemonset which can be used to find all pods in the daemonset.

Key Default Value Description
k8sHost localhost The Kubernetes master host.
k8sPort 8001 The Kubernetes master port.
namespace required The Kubernetes namespace of the daemonset.
service required The Kubernetes service name for the daemonset.
port required The name of the daemonset port to use.
hostNetwork false If true, use nodeName instead of /24 subnet to determine which daemonset pod is on the destination node. Set this to true if the daemonset is running with hostNetwork: true.

Localnode (Kubernetes)

kind: io.l5d.k8s.localnode

The localnode transformer filters the list of addresses down to only addresses that are on the same /24 subnet as localhost. Since each Kubernetes node is its own /24 subnet, the result is that only addresses on the local node are used.

This transformer does not have any configuration properties but it does require the POD_IP environment variable be set with the localhost IP address. This is most easily done with the Kubernetes downward API.

In your container spec:

env:
- name: POD_IP
    valueFrom:
      fieldRef:
        fieldPath: status.podIP
Key Default Value Description
hostNetwork false If true, use nodeName to determine which pods are on the local node. This adds the requirement that the NODE_NAME environment variable be set with the node name. Set this to true if the pod is running with hostNetwork: true.

Replace

kind: io.l5d.replace

The replace transformer replaces all bound names with a configurable path. This differs from the const transformer in that if the original NameTree is Neg then the result will be Neg as well. This is useful if you want to use a namer to check the validity of a name but then actually route to a different name.

Key Default Value Description
path required Bound names will be replaced with this path.

Const

kind: io.l5d.const

The const transformer ignores the input and always returns a constant configurable path. This differs from the replace transformer in that it always returns the configured path, even when the original NameTree is Neg.

Key Default Value Description
path required Ignore the input and return this path.

HTTP Response Classifiers

Example response classifier config

routers:
- protocol: http
  service:
    responseClassifier:
      kind: io.l5d.http.retryableRead5XX

Response classifiers determine which HTTP responses are considered to be failures (for the purposes of success rate calculation) and which of these responses may be retried.

Key Default Value Description
kind io.l5d.http.nonRetryable5XX Either io.l5d.http.nonRetryable5XX, io.l5d.h2.nonRetryable5XX, io.l5d.http.retryableRead5XX, io.l5d.h2.retryableRead5XX, io.l5d.http.retryableIdempotent5XX, io.l5d.h2.retryableIdempotent5XX, io.l5d.http.retryableAll5XX, or io.l5d.h2.retryableAll5XX.

Non-Retryable 5XX

kind: io.l5d.http.nonRetryable5XX

kind: io.l5d.h2.nonRetryable5XX

All 5XX responses are considered to be failures and none of these requests are considered to be retryable.

Retryable Read 5XX

kind: io.l5d.http.retryableRead5XX

kind: io.l5d.h2.retryableRead5XX

All 5XX responses are considered to be failures. However, GET, HEAD, OPTIONS, and TRACE requests may be retried automatically.

Retryable Idempotent 5XX

kind: io.l5d.http.retryableIdempotent5XX

kind: io.l5d.h2.retryableIdempotent5XX

Like io.l5d.http.retryableRead5XX/io.l5d.h2.retryableRead5XX, but PUT and DELETE requests may also be retried.

Retryable All 5XX

kind: io.l5d.http.retryableAll5XX

kind: io.l5d.h2.retryableAll5XX

Like io.l5d.http.retryableIdempotent5XX/io.l5d.h2.retryableIdempotent5XX, but POST and PATCH requests may also be retried.

All Successful

kind: io.l5d.http.allSuccessful

kind: io.l5d.h2.allSuccessful

All responses are considered to be successful, regardless of status code.

gRPC Response Classifiers

For HTTP/2 routers that handle gRPC traffic, one optional parameter and four additional response classifiers are available to categorize responses based on gRPC status codes in the stream’s trailers frame.

By default, status code 0 (OK) is always classified as Success, while all other gRPC status codes are classified as Failure. There exists an optional parameter successStatusCodes that accepts a user-defined list of gRPC status codes that should always be classified as Success.

routers:
- protocol: h2
  experimental: true
  service:
    responseClassifier:
      kind: io.l5d.h2.grpc.default
      successStatusCodes:
      - 0
      - 3
      - 5

Status code 0 (Ok), 3 (InvalidArgument), and 5 (NotFound) will be classified as Success.

gRPC Default

kind: io.l5d.h2.grpc.default

Only status code 14 (Unavailable) is considered retryable, all other errors are non-retryable.

gRPC Compliant

kind: io.l5d.h2.grpc.compliant

Strictly complies with gRPC specifications for retryability.

gRPC Always Retryable

kind: io.l5d.h2.grpc.alwaysRetryable

All gRPC error codes are considered retryable.

gRPC Never Retryable

kind: io.l5d.h2.grpc.neverRetryable

No gRPC error codes are considered retryable.

gRPC User-Defined Retryable Status Codes

Example config

routers:
- protocol: h2
  experimental: true
  service:
    responseClassifier:
      kind: io.l5d.h2.grpc.retryableStatusCodes
      retryableStatusCodes:
      - 2
      - 5
      - 14
      - 100

This classifier accepts a user-defined list of error status codes to mark as retryable. Failures with status codes in the provided list will be classified as retryable, while all other failures will be non-retryable.

Failure Accrual

routers:
- ...
  client:
    failureAccrual:
      kind: io.l5d.successRate
      successRate: 0.9
      requests: 1000
      backoff:
        kind: jittered
        minMs: 5000
        maxMs: 300000

Linkerd uses failure accrual to track the number of requests that have failed to a given node, and it will back off sending requests to any nodes whose failures have exceeded a given threshold. Both the failure threshold and the backoff behavior are configurable. By default, if Linkerd observes 5 consecutive failures from a node, it will mark the node as dead and only attempt to resend it traffic in increasing intervals between 5 seconds and 5 minutes.

Key Default Value Description
kind required Either io.l5d.consecutiveFailures, io.l5d.successRate, io.l5d.successRateWindowed, or none.
backoff jittered backoff from 5s to 300s A backoff policy that determines how long to wait before resending traffic.

Consecutive Failures

kind: io.l5d.consecutiveFailures

Observes the number of consecutive failures to each node, and backs off sending requests to nodes that have exceeded the specified number of failures.

Key Default Value Description
failures required Number of consecutive failures.

Success Rate

kind: io.l5d.successRate

Computes an exponentially-weighted moving average success rate for each node, and backs off sending requests to nodes that have fallen below the specified success rate. The window size for computing success rate is constrained to a fixed number of requests.

Key Default Value Description
successRate required Target success rate.
requests required Number of requests over which success rate is computed.

Success Rate (windowed)

kind: io.l5d.successRateWindowed

Computes an exponentially-weighted moving average success rate for each node, and backs off sending requests to nodes that have fallen below the specified success rate. The window size for computing success rate is constrained to a fixed time window.

Key Default Value Description
successRate required Target success rate.
window required Number of seconds over which success rate is computed.

None

kind: none

Disables failure accrual altogether. This policy does not accept any additional parameters.

TLS

Server TLS

routers:
- protocol: http
  servers:
  - port: 4140
    # accept incoming TLS traffic from remote Linkerd
    tls:
      certPath: /certificates/certificate.pem
      keyPath: /certificates/key.pem
  dtab: |
    /http => /$/inet/127.1/8080;

In order to accept incoming TLS traffic, the tls parameter must be defined on the server.

Key Default Value Description
enabled true Enable TLS on outgoing connections.
certPath required File path to the TLS certificate file.
intermediateCertsPath none Path to a file containing a CA certificate chain to support the server certificate.
keyPath required File path to the TLS key file.
requireClientAuth false If true, only accept requests with valid client certificates.
caCertPath none File path to the CA cert to validate the client certificates.
protocols unspecified The list of TLS protocols to enable (TLSv1.2)

See Transparent TLS with Linkerd for more on how to generate certificate and key files.

Client TLS

Client TLS is defined in the client section of routers:

routers:
- protocol: http
  client:
    tls:
      commonName: linkerd.io
      trustCertsBundle: /certificates/cacert.pem
      clientAuth:
        certPath: /certificates/cert.pem
        keyPath: /certificates/key.pem
      protocols:
      - TLSv1.2

In order to send outgoing tls traffic, the tls parameter must be defined as a client parameter.

A client TLS object describes how Linkerd should use TLS when sending requests to destination services.

Key Default Value Description
disableValidation false Enable this to skip hostname validation (unsafe). Setting disableValidation: true is incompatible with clientAuth.
commonName required unless disableValidation is set The common name to use for all TLS requests.
trustCerts empty list A list of file paths of CA certs to use for common name validation (deprecated, please use trustCertsBundle).
trustCertsBundle empty A file path of CA certs bundle to use for common name validation
clientAuth none A client auth object used to sign requests.
protocols unspecified The list of TLS protocols to enable

If present, a client auth object must contain two properties:

Key Default Value Description
certPath required File path to the TLS certificate file.
intermediateCertsPath none Path to a file containing a CA certificate chain to support the client certificate.
keyPath required File path to the TLS key file. Must be in PKCS#8 format.

Any variables captured from the client prefix may be used in the common name.

routers:
- protocol: http
  client:
    kind: io.l5d.static
    configs:
    - prefix: /#/io.l5d.fs/{service}
      tls:
        commonName: "{service}.linkerd.io"
        trustCerts:
        - /certificates/cacert.pem
        clientAuth:
          certPath: /certificates/cert.pem
          keyPath: /certificates/key.pem
        protocols:
        - TLSv1.2

Client TLS and transformers

If you use transformers, each transformer will prepend a transformer prefix to the client name to indicate that it has been transformed. Transformer prefixes always start with /%. When using any kind of transformer with client TLS using io.l5d.static, ensure that the client TLS’s prefix field starts with at least the first transformer that is applied to a client name in the dtab. This will ensure that TLS is initiated between the Linkerd client and any downstream service receiving the intended TLS traffic. For example given a configuration:

routers:
- protocol: http
  interpreter:
      kind: default
      transformers:
      - kind: io.l5d.port
        port: 4141
  dtab: |
    /svc => /#/io.l5d.fs;
  client:
    kind: io.l5d.static
    configs:
    - prefix: /%/io.l5d.port/4141/#/io.l5d.fs/
      tls:
        commonName: "linkerd.io"
        trustCerts:
        - /certificates/cacert.pem
        clientAuth:
          certPath: /certificates/cert.pem
          keyPath: /certificates/key.pem

Since the base client name is /#/io.l5d.fs/hello and the port transformer applies /%/io.l5d.port/4141 as a transformer prefix, the transformed client name becomes /%/io.l5d.port/4141/#/io.l5d.fs/<client name>. The full client name generated by Linkerd for service hello would look like /%/io.l5d.port/#/io.l5d.fs/4141/hello.

A quick way to find out this information is to look through Linkerd’s admin dashboard UI. On the initial dashboard page, the client section displays active clients used to connect to downstream services. Clicking on any of the client names in that section will reveal the full client name. The text that appears can be used to assign a prefix to the client TLS section.

Load Balancer

Example load balancer configuration

routers:
- ...
  client:
    loadBalancer:
      kind: ewma
      maxEffort: 10
      decayTimeMs: 15000
Key Default Value Description
kind p2c Either p2c, ewma, aperture, heap, or roundRobin.
enableProbation false If true, removals from service discovery are treated as advisory and the removed endpoints will remain in the load balancer pool as long as they remain healthy. See Finagle’s LoadBalancerFactory.EnableProbation.

Power of Two Choices: Least Loaded

kind: p2c

Key Default Value Description
maxEffort 5 The number of times a load balancer can retry if the previously picked node was marked unavailable.

Power of Two Choices: Peak EWMA

kind: ewma

Key Default Value Description
maxEffort 5 The number of times a load balancer can retry if the previously picked node was marked unavailable.
decayTimeMs 10 seconds The window of latency observations.

Aperture: Least Loaded

kind: aperture

Key Default Value Description
maxEffort 5 The number of times a load balancer can retry if the previously picked node was marked unavailable.
smoothWindowMs 5 seconds The window of concurrent load observation.
lowLoad 0.5 The lower bound of the load band used to adjust an aperture.
highLoad 2 The upper bound of the load band used to adjust an aperture.
minAperture 1 The minimum size of the aperture.

Heap: Least Loaded

kind: heap

Round Robin

kind: roundRobin

Key Default Value Description
maxEffort 5 The number of times a load balancer can retry if the previously picked node was marked unavailable.

Retries

routers:
- ...
  service:
    retries:
      budget:
        minRetriesPerSec: 5
        percentCanRetry: 0.5
        ttlSecs: 15
      backoff:
        kind: jittered
        minMs: 10
        maxMs: 10000

Linkerd can automatically retry requests on certain failures and can be configured via the retries block. Retries fall into two categories: retries and requeues.

Key Default Value Description
budget See retry budget Object that determins how many failed requests are eligible to be retried.
backoff See retry backoff Object that determines which backoff algorithm should be used.

Retries

Retries are for application-level failures (such as 5XX responses in the case of HTTP) as determined by the response classifier. If the response classifier determines that a request is a retryable failure, and the retry budget is not empty, then the request will be retried. Retries are configured by the retries parameter on the service object. On the retries object you may specify the retry budget and retry backoff schedule. Each service has its own retry budget that is not shared with other services or clients.

Requeues

Requeues are for connection-level failures that are guaranteed to be idempotent. If a connection-level failure is encountered and there is requeue budget available, then the request will be retried. Requeue budgets are configured by the requeueBudget parameter on the client object. Requeues happen immediately with no backoff. Each client has its own requeue budget that is not shared with other clients or services.

Retry Budget Parameters

For every 10 non-retry calls, allow 1 retry

service:
  retries:
    budget:
      percentCanRetry: 0.1

For every non-retry call, allow 2 retries

service:
  retries:
    budget:
      percentCanRetry: 2.0
Key Default Value Description
minRetriesPerSec 10 The minimum rate of retries allowed in order to accommodate clients that have just started issuing requests, as well as clients that do not issue many requests per window. Must be non-negative. If 0, no reserve is given.
percentCanRetry 0.2 The percentage of calls that can be retried. This is in addition to any retries allowed via minRetriesPerSec. Must be >= 0 and <= 1000.
ttlSecs 10 The amount of time in seconds that successful calls are considered when calculating retry budgets.

Retry Backoff Parameters

Key Default Value Description
kind required Either constant or jittered.

Constant Backoff

kind: constant

Key Default Value Description
ms 0 The number of milliseconds to wait before each retry.

Jittered Backoff

kind: jittered

Uses a decorrelated jitter backoff algorithm.

Key Default Value Description
minMs required The minimum number of milliseconds to wait before each retry.
maxMs required The maximum number of milliseconds to wait before each retry.

Namers

namers:
- kind: io.l5d.fs
  prefix: /disco
  rootDir: disco

A namer binds a concrete name to a physical address.

Key Default Value Description
kind required Either io.l5d.fs, io.l5d.serversets, io.l5d.consul, io.l5d.k8s, io.l5d.marathon, io.l5d.zkLeader, io.l5d.curator, io.l5d.rancher, or io.l5d.rewrite.
prefix namer dependent Resolves names with /#/<prefix>.
experimental false Set this to true to enable the namer if it is experimental.
transformers No transformers A list of transformers to apply to the resolved addresses.

File-based service discovery

kind: io.l5d.fs

File-based Configuration

Example fs configuration:

namers:
- kind: io.l5d.fs
  rootDir: disco

Then reference the namer in the dtab to use it:

dtab: |
  /svc => /#/io.l5d.fs

With the filesystem directory:

$ ls disco/
apps    users   web

The contents of the files look similar to this:

$ cat config/web
192.0.2.220 8080
192.0.2.105 8080
192.0.2.210 8080 * 2.0

Linkerd ships with a simple file-based service discovery mechanism called the file-based namer. This system is intended to act as a structured form of basic host lists.

While simple, the file-based namer is a full-fledged service discovery system, and can be useful in production systems where host configurations are largely static. It can act as an upgrade path for the introduction of an external service discovery system, since application code will be isolated from these changes. Finally, when chained with precedence rules, the file-based namer can be a convenient way to add local service discovery overrides for debugging or experimentation.

This service discovery mechanism is tied to the directory set by the namers/rootDir key in config.yaml. This directory must be on the local filesystem and relative to Linkerd’s start path. Every file in this directory corresponds to a service, where the name of the file is the service’s concrete name, and the contents of the file must be a newline-delimited set of addresses.

Linkerd watches all files in this directory, so files can be added, removed, or updated, and Linkerd will pick up the changes automatically.

Key Default Value Description
prefix io.l5d.fs Resolves names with /#/<prefix>.
rootDir required the directory containing name files as described above.

File-based Path Parameters

Dtab Path Format:

/#/<prefix>/<fileName>
Key Required Description
prefix yes Tells Linkerd to resolve the request path using the fs namer.
fileName yes The file in rootDir to use when resolving this request.

ZooKeeper ServerSets service discovery

kind: io.l5d.serversets

ServerSets Configuration

Example ServerSets configuration:

namers:
- kind: io.l5d.serversets
  zkAddrs:
  - host: 127.0.0.1
    port: 2181

Then reference the namer in the dtab to use it:

dtab: |
  /svc => /#/io.l5d.serversets/discovery/prod;

Linkerd provides support for ZooKeeper ServerSets.

Key Default Value Description
prefix io.l5d.serversets Resolves names with /#/<prefix>.
zkAddrs required A list of ZooKeeper addresses, each of which have host and port parameters.

ServerSets Path Parameters

Dtab Path Format:

/#/<prefix>/<zkHosts>/<zkPath>[:<endpoint>]
Key Required Description
prefix yes Tells Linkerd to resolve the request path using the serversets namer.
zkHosts yes The ZooKeeper host to use for this request.
zkPath yes The ZooKeeper path to use for this request.
endpoint no The ZooKeeper endpoint to use for this request.

Consul service discovery

kind: io.l5d.consul

Consul Configuration

Configure a consul namer:

namers:
- kind: io.l5d.consul
  host: 127.0.0.1
  port: 2181
  includeTag: true
  useHealthCheck: false
  healthStatuses:
    - "passing"
    - "warning"
  setHost: true
  consistencyMode: stale

Then reference the namer in the dtab to use it:

dtab: |
  /svc => /#/io.l5d.consul/dc1/prod;

Optionally, define node weight using tags:

namers:
- kind: io.l5d.consul
  weights:
   - tag: experimental
     weight: 0.1
   - tag: primary
     weight: 5.0

Linkerd provides support for service discovery via Consul.

The internal state of the Consul namer can be viewed at the admin endpoint: /namer_state/<prefix>.json.

Key Default Value Description
prefix io.l5d.consul Resolves names with /#/<prefix>.
host localhost The Consul host.
port 8500 The Consul port.
includeTag false If true, read a Consul tag from the path.
useHealthCheck false If true, exclude app instances that do not match one of the provided healthStatuses. Even if false, Linkerd’s built-in resiliency algorithms will still apply.
healthStatuses passing List of statuses to used to filter Consul app instances by. Possible values are passing, warning, critical, maintenance. Note that if a service defines more than one health check per app instance then the most representative statuses is used (maintenance > critical > warning > passing). If useHealthCheck is false then this parameter has no effect. Regardless of the statuses used to filter, Linkerd’s built-in resiliency algorithms will still apply.
token no authentication The auth token to use when making API calls.
setHost false If true, HTTP requests resolved by Consul will have their Host header overwritten to ${serviceName}.service.${datacenter}.${domain}. $domain is fetched from Consul.
consistencyMode default Select between Consul API consistency modes such as default, stale and consistent.
failFast false If false, disable fail fast and failure accrual for Consul client. Keep it false when using a local agent but change it to true when talking directly to an HA Consul API.
preferServiceAddress true If true use the service address if defined and default to the node address. If false always use the node address.
weights none List of tag-weight configurations, for adjusting the weights of node addresses. When a node matches more than one tag, it gets the highest matching weight. In the absence of match or configuration, nodes get a default weight of 1.0.
tls no tls Use TLS during connection with Consul. see Consul Encryption and TLS.

Consul Path Parameters

Dtab Path Format when includeTag is false

/#/<prefix>/<datacenter>/<serviceName>

Dtab Path Format when includeTag is true

/#/<prefix>/<datacenter>/<tag>/<serviceName>
Key Required Description
prefix yes Tells Linkerd to resolve the request path using the consul namer.
datacenter yes The Consul datacenter to use for this request. It can have a value .local (otherwise invalid datacenter name from Consul’s perspective) in order to reference a datacenter of the agent namer is connected to.
tag yes if includeTag is true The Consul tag to use for this request.
serviceName yes The Consul service name to use for this request.

Consul TLS

Linkerd supports encrypted communication via TLS to Consul.

namers:
- kind: io.l5d.consul
  host: localhost
  port: 8500
  tls:
    disableValidation: false
    commonName: consul.io
    trustCertsBundle: /certificates/cacert.pem
    clientAuth:
      certPath: /certificates/cert.pem
      keyPath: /certificates/key.pem

A TLS object describes how Linkerd should use TLS when sending requests to Consul agent.

Key Default Value Description
disableValidation false Enable this to skip hostname validation (unsafe). Setting disableValidation: true is incompatible with clientAuth.
commonName required unless disableValidation is set The common name to use for all TLS requests.
trustCerts empty list A list of file paths of CA certs to use for common name validation (deprecated, please use trustCertsBundle).
trustCertsBundle empty A file path of CA certs bundle to use for common name validation.
clientAuth none A client auth object used to sign requests.

If present, a clientAuth object must contain two properties:

Key Default Value Description
certPath required File path to the TLS certificate file.
keyPath required File path to the TLS key file. Must be in PKCS#8 format.

Kubernetes service discovery

kind : io.l5d.k8s

K8s Configuration

Configure a K8s namer

namers:
- kind: io.l5d.k8s
  host: localhost
  port: 8001
  labelSelector: version

Then reference the namer in the dtab to use it:

dtab: |
  /svc => /#/io.l5d.k8s/prod/http;

Linkerd provides support for service discovery via Kubernetes. The internal state of the Kubernetes namer can be viewed at the admin endpoint: /namer_state/<prefix>.json.

Key Default Value Description
prefix io.l5d.k8s Resolves names with /#/<prefix>.
host localhost The Kubernetes master host.
port 8001 The Kubernetes master port.
labelSelector none The key of the label to filter services.

K8s Path Parameters

Dtab Path Format

/#/<prefix>/<namespace>/<port-name>/<svc-name>[/<label-value>]
Key Required Description
prefix yes Tells Linkerd to resolve the request path using the k8s namer.
namespace yes The Kubernetes namespace.
port-name yes The port name or port number.
svc-name yes The name of the service.
label-value yes if labelSelector is defined The value used to filter services.

K8s External Configuration

Configure a K8s External namer

namers:
- kind: io.l5d.k8s.external
  experimental: true
  host: localhost
  port: 8001
  labelSelector: version

Then reference the namer in the dtab to use it:

dtab: |
  /svc => /#/io.l5d.k8s.external/prod/http;

The Kubernetes External namer looks up the IP of the external load balancer for the given service on the given port. This can be used by Linkerd instances running outside of k8s to route to services running in k8s.

Key Default Value Description
prefix io.l5d.k8s.external Resolves names with /#/<prefix>.
experimental required Because this namer is still considered experimental, you must set this to true to use it.
host localhost The Kubernetes master host.
port 8001 The Kubernetes master port.
labelSelector none The key of the label to filter services.

K8s External Path Parameters

Dtab Path Format

/#/<prefix>/<namespace>/<port-name>/<svc-name>[/<label-value>]
Key Required Description
prefix yes Tells Linkerd to resolve the request path using the k8s external namer.
namespace yes The Kubernetes namespace.
port-name yes The port name.
svc-name yes The name of the service.
label-value yes if labelSelector is defined The label value used to filter services.

K8s Namespaced Configuration

Example usage of the namespaced namer that routes traffic to services within the current namespace

apiVersion: v1
kind: ConfigMap
metadata:
  name: l5d-config
data:
  config.yaml: |-
    namers:
    - kind: io.l5d.k8s.ns
      host: localhost
      port: 8001
      envVar: MY_POD_NAMESPACE

    routers:
    - protocol: http
      dtab: |
        /svc => /#/io.l5d.k8s.ns/admin;
      servers:
      - port: 4140
        ip: 0.0.0.0

---
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  labels:
    app: l5d
  name: l5d
spec:
  template:
    metadata:
      labels:
        app: l5d
    spec:
      volumes:
      - name: l5d-config
        configMap:
          name: "l5d-config"
      containers:
      - name: l5d
        image: buoyantio/linkerd:latest
        # Use the downward api to populate an environment variable
        env:
        - name: MY_POD_NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
        args:
        - /io.buoyant/linkerd/config/config.yaml
        ports:
        - name: http
          containerPort: 4140
        - name: admin
          containerPort: 9990
        volumeMounts:
        - name: "l5d-config"
          mountPath: "/io.buoyant/linkerd/config"
          readOnly: true

      - name: kubectl
        image: buoyantio/kubectl:v1.6.2
        args: ["proxy", "-p", "8001"]
---
apiVersion: v1
kind: Service
metadata:
  name: l5d
spec:
  selector:
    app: l5d
  type: LoadBalancer
  ports:
  - name: http
    port: 4140
  - name: admin
    port: 9990

The Kubernetes Namespaced namer scopes service discovery to the current namespace, as provided by the Kubernetes downward api.

Key Default Value Description
prefix io.l5d.k8s.ns Resolves names with /#/<prefix>.
envVar POD_NAMESPACE Environment variable that contains the namespace name.
host localhost The Kubernetes master host.
port 8001 The Kubernetes master port.
labelSelector none The key of the label to filter services.

K8s Namespaced Path Parameters

Dtab Path Format

/#/<prefix>/<port-name>/<svc-name>[/<label-value>]
Key Required Description
prefix yes Tells Linkerd to resolve the request path using the k8s external namer.
port-name yes The port name.
svc-name yes The name of the service.
label-value yes if labelSelector is defined The label value used to filter services.

Istio Configuration (Deprecated)

Configure an Istio namer

namers:
- kind: io.l5d.k8s.istio
  experimental: true
  host: istio-manager.default.svc.cluster.local
  port: 8080

Then reference the namer in the dtab to use it:

dtab: |
  /svc/reviews => /#/io.l5d.k8s.istio/version:v1/http/reviews;

The Istio namer uses the Istio-Manager’s Service Discovery Service to lookup the endpoints for a given namespace, port, service, and list of label selectors.

Key Default Value Description
prefix io.l5d.k8s.istio Resolves names with /#/<prefix>.
experimental required Because this namer is still considered experimental, you must set this to true to use it.
host istio-manager.default.svc.cluster.local The host of the Istio-Manager.
port 8080 The port of the Istio-Manager.

Istio Path Parameters (Deprecated)

Dtab Path Format

/#/<prefix>/<cluster>/<labels>/<port-name>
Key Required Description
prefix yes Tells Linkerd to resolve the request path using the Istio namer.
port-name yes The port name.
cluster yes The fully qualified name of the service.
labels yes A :: delimited list of label:value pairs. Only endpoints that match all of these label selectors will be returned.

Marathon service discovery

kind: io.l5d.marathon

Marathon Configuration

Configure a marathon namer

namers:
- kind:           io.l5d.marathon
  prefix:         /io.l5d.marathon
  host:           marathon.mesos
  port:           80
  uriPrefix:      /marathon
  ttlMs:          5000
  useHealthCheck: false

Then reference the namer in the dtab to use it:

dtab: |
  /marathonId => /#/io.l5d.marathon;
  /host       => /$/io.buoyant.http.domainToPathPfx/marathonId;
  /svc => /host;

Linkerd provides support for service discovery via Marathon.

Key Default Value Description
prefix io.l5d.marathon Resolves names with /#/<prefix>.
host marathon.mesos The Marathon master host.
port 80 The Marathon master port.
uriPrefix none The Marathon API prefix. This prefix depends on your Marathon configuration. For example, running Marathon locally, the API is available at localhost:8080/v2/, while the default setup on AWS/DCOS is $(dcos config show core.dcos_url)/marathon/v2/apps.
ttlMs 5000 The polling interval in milliseconds against the Marathon API.
useHealthCheck false If true, exclude app instances that are failing Marathon health checks. Even if false, Linkerd’s built-in resiliency algorithms will still apply.
tls no tls The Marathon namer will make requests to Marathon/DCOS using TLS if this parameter is provided. This is useful when DC/OS is run in strict security mode. It must be a client TLS object. Note that the clientAuth config value will be unused, as DC/OS does not use mutual TLS.

Marathon Path Parameters

Dtab Path Format

/#/<prefix>/<appId>
Key Required Description
prefix yes Tells Linkerd to resolve the request path using the marathon namer.
appId yes The app id of a marathon application. This id can be multiple path segments long. For example, the app with id “/users” can be reached with /#/io.l5d.marathon/users. Likewise, the app with id “/appgroup/usergroup/users” can be reached with /#/io.l5d.marathon/appgroup/usergroup/users.

Marathon Authentication

Example DCOS environment variable

{
  "login_endpoint": "https://leader.mesos/acs/api/v1/auth/login",
  "private_key": "<private-key-value>",
  "scheme": "RS256",
  "uid": "service-acct"
}

Example basic HTTP authentication variable

dXNlcm5hbWU6cGFzc3dvcmQ=

The Marathon namer supports loading authentication data from an environment variable for DCOS private key in the DCOS_SERVICE_ACCOUNT_CREDENTIAL variable and standalone Marathon basic HTTP authentication in the MARATHON_HTTP_AUTH_CREDENTIAL environment variable. If both are provided the DCOS_SERVICE_ACCOUNT_CREDENTIAL takes precedence.

Basic authentication token is base64 encoded and should not include the Basic prefix, only in the format username:password.

Further reading:

DNS SRV Records

kind: io.l5d.dnssrv

DNS-SRV Configuration

Configure a DNS-SRV namer:

namers:
- kind: io.l5d.dnssrv
  experimental: true
  refreshIntervalSeconds: 5
  dnsHosts:
  - ns0.example.org
  - ns1.example.org

Then reference the namer in the dtab to use it:

dtab: |
  /dnssrv => /#/io.l5d.dnssrv
  /svc => /dnssrv
  /svc/myservice =>
    /dnssrv/myservice |
    /dnssrv/myservice.srv.dc-2.example.org.;

Linkerd provides support for service discovery via DNS SRV records.

Key Default Value Description
prefix io.l5d.dnssrv Resolves names with /#/<prefix>.
experimental false Since the DNS-SRV namer is still considered experimental, this must be set to true.
refreshIntervalSeconds 5 Linkerd will perform a SRV lookup for each host every refreshIntervalSeconds.
dnsHosts <empty list> If specified, Linkerd will use these DNS servers to perform SRV lookups. If not specified, Linkerd will use the default system resolver.

DNS-SRV Path Parameters

Dtab Path Format

/#/<prefix>/<address>
Key Required Description
prefix yes Tells Linkerd to resolve the request path using the marathon namer.
address yes The DNS address of a SRV record. Linkerd resolves the record to one or more address:port tuples using a SRV lookup.

ZooKeeper Leader

kind: io.l5d.zkLeader

ZK Leader Configuration

A namer backed by ZooKeeper leader election.

Key Default Value Description
prefix io.l5d.zkLeader Resolves names with /#/<prefix>.
zkAddrs required A list of ZooKeeper addresses, each of which have host and port parameters.

ZK Leader Path Parameters

Dtab Path Format

/#/<prefix>/<zkPath>
Key Required Description
prefix yes Tells Linkerd to resolve the request path using the marathon namer.
zkPath yes The ZooKeeper path of a leader group. This path can be multiple path segments long. The namer resolves to the address stored in the data of the leader.

Curator

kind: io.l5d.curator

Curator Configuration

A namer that uses the Curator discovery library to resolve names.

Note: If you have registered Curator services with a custom payload object, that class file must be on the classpath. Otherwise you will get a java.lang.IllegalArgumentException: Invalid type id '<some-payload-class' error.

Key Default Value Description
prefix io.l5d.curator Resolves names with /#/<prefix>.
experimental required Because this namer is still considered experimental, you must set this to true to use it.
zkAddrs required A list of ZooKeeper addresses, each of which have host and port parameters.
basePath / The ZooKeeper path for Curator discovery.

Curator Path Parameters

Dtab Path Format

/#/<prefix>/<serviceName>
Key Required Description
prefix yes Tells Linkerd to resolve the request path using the curator namer.
serviceName yes The name of the Curator service to lookup in ZooKeeper.

Rancher

kind: io.l5d.rancher

Rancher configuration

Configure a Rancher namer:

namers:
- kind: io.l5d.rancher
  experimental: true
  portMappings:
    proxy: 8080

Then reference the namer in the dtab to use it:

dtab: |
  /rancher => /#/io.l5d.rancher;
  /s => /rancher/http;
  /svc => /$/io.buoyant.http.domainToPathPfx/s;

linkerd provides support for service discovery via Rancher’s Metadata-API.

Key Default Value Description
prefix io.l5d.rancher Resolves names with /#/<prefix>.
experimental false Since the Rancher namer is still considered experimental, this must be set to true.
portMappings <empty map> If specified, you can use the names of these port-mappings for the <port> path parameter. By default, the namer knows http and https.
maxWait 30 The max number of seconds to wait for changes in the Rancher Metadata-API before starting a new request.

Rancher Path Parameters

Dtab Path Format

/#/<prefix>/<port>/<stack>/<service>
Key Required Description
prefix yes Tells linkerd to resolve the request path using the Rancher namer.
port yes The port name or number to route the request to
stack yes Name of the stack of the service
service yes The name of the service

Rewrite

kind: io.l5d.rewrite

Rewrite Configuration

Example rewrite configuration:

namers:
- kind: io.l5d.rewrite
  prefix: /rewrite
  pattern: "/{service}/api"
  name: "/srv/{service}"

Then reference the namer in the dtab to use it:

dtab: |
  /svc => /#/rewrite

A namer that completely rewrites a path. This is useful for doing arbitrary reordering of the path segments that is not possible using standard prefix replacement. In addition to reordering path segments, this tool can be used to modify or split individual segments using regex capture groups.

If the name matches the pattern in the config, it will be replaced by the name in the config. Additionally, any variables in the pattern will capture the value of the matching path segment and may be used in the final name.

Note: Pattern matches are greedy. For example patterns like “{foo}{bar}” are ambiguous. With the capture implementation, {foo} would capture the whole segment and {bar} would be empty. Similarly, the pattern “{foo}-{bar}” on the segment “a-b-c” would capture “a-b” into foo and “c” into bar.

Key Default Value Description
prefix required Resolves names with /#/<prefix>.
pattern required If the name matches this prefix, replace it with the name configured in the name parameter. Wildcards and variable capture are allowed (see: io.buoyant.namer.util.PathMatcher).
name required The replacement name. Variables captured in the pattern may be used in this string.

Rewrite Path Parameters

Dtab Path Format

/#/<prefix> [/ *name ]
Key Required Description
prefix yes Tells Linkerd to resolve the request path using the rewrite namer.
name yes Attempt to match this name against the pattern and replace it with the configured name.

Built-In Namers

The following namers are always available to be used in dtabs. They are prefixed with /$/ instead of /#/, and can be used without explicitly adding them to the namers section of the config.

inet

The inet namer does a DNS lookup for the given hostname and uses the given port.

/$/inet/<hostname>/<port>

io.buoyant.rinet

The rinet namer is like the inet namer but takes the hostname and port arguments in the reverse order. This is often easier to work with than the inet namer because dtabs can only make prefix substitutions and we often wish to use a fixed port while varying the hostname.

/$/io.buoyant.rinet/<port>/<hostname>

Rewriting Namers

In addition to service discovery namers, Linkerd supplies a number of utility namers. These namers assist in path rewriting when the transformation is more complicated than just prefix substitution. They are prefixed with /$/ instead of /#/, and can be used without explicitly adding them to the namers section of the config.

domainToPathPfx

/marathonId => /#/io.l5d.marathon;
/host       => /$/io.buoyant.http.domainToPathPfx/marathonId;
/svc => /host;

Dtab Path Format

/$/io.buoyant.http.domainToPathPfx/<prefix>/<host>

Rewrites the path’s prefix with <prefix> first, followed by each subdomain of <host> separated and in reverse order.

For example, /$/io.buoyant.http.domainToPathPfx/pfx/foo.buoyant.io/resource/name would be rewritten to /pfx/io/buoyant/foo/resource/name.

subdomainOfPfx

/consulSvc  => /#/io.l5d.consul/.local
/host       => /$/io.buoyant.http.subdomainOfPfx/service.consul/consulSvc;
/svc => /host;

Dtab Path Format

/$/io.buoyant.http.subdomainOfPfx/<domain>/<prefix>/<host>

Rewrites the path’s prefix with <prefix> first, followed by <host> with the <domain> dropped.

For example, /$/io.buoyant.http.subdomainOfPfx/buoyant.io/pfx/foo.buoyant.io/resource/name would be rewritten to /pfx/foo/resource/name

hostportPfx

/ip-hostport => /$/inet;
/svc         => /$/io.buoyant.hostportPfx/ip-hostport;

Dtab Path Format

/$/io.buoyant.hostportPfx/<prefix>/<host>:<port>/etc

Rewrites a name of the form “host:port” as a path with the port followed by the host. Does not support IPv6 host IPs (because IPv6 notation doesn’t work in Paths as-is due to bracket characters).

For example, /$/io.buoyant.hostportPfx/pfx/host:port/etc would be rewritten to /pfx/host/port/etc.

porthostPfx

/k8s-porthost => /#/io.l5d.k8s/default;
/svc          => /$/io.buoyant.porthostPfx/k8s-porthost;

Dtab Path Format

/$/io.buoyant.porthostPfx/<prefix>/<host>:<port>/etc

Rewrites a name of the form “host:port” as a path with the port followed by the host. Does not support IPv6 host IPs (because IPv6 notation doesn’t work in Paths as-is due to bracket characters).

For example, /$/io.buoyant.porthostPfx/pfx/host:port/etc would be rewritten to /pfx/port/host/etc.

Telemetry

A telemeter may receive stats and trace annotations, e.g., to send to a collector or export. Telemetry data can be collected and exported from a Linkerd process by configuring telemeters via a top-level telemetry section.

Key Default Value Description
kind required Either io.l5d.prometheus, io.l5d.influxdb, io.l5d.statsd, io.l5d.tracelog, io.l5d.recentRequests, or io.l5d.zipkin.
experimental false Set this to true to enable the telemeter if it is experimental.

Prometheus

Example Prometheus config

telemetry:
- kind: io.l5d.prometheus
  path: /admin/metrics/prometheus
  prefix: linkerd_

kind: io.l5d.prometheus

Exposes admin endpoints:

Key Default Value Description
path /admin/metrics/prometheus HTTP path where Linkerd exposes Prometheus metrics
prefix No prefix Prefix for exposed Prometheus metrics

InfluxDB

Example InfluxDB config

telemetry:
- kind: io.l5d.influxdb

kind: io.l5d.influxdb

This telemeter is intended for collection by Telegraf. Each measurement will have a host tag, set from the Host header on the collector’s incoming request. Recommended Telegraf configuration is using inputs.exec plugin with curl -s http://[LINKERD_IP]/admin/metrics/influxdb.

Exposes admin endpoints:

This telemeter has no additional parameters.

StatsD (experimental)

Example StatD config

telemetry:
- kind: io.l5d.statsd
  experimental: true
  prefix: linkerd
  hostname: 127.0.0.1
  port: 8125
  gaugeIntervalMs: 10000
  sampleRate: 1.0

kind: io.l5d.statsd

StatsD metrics exporting. This telemeter connects to a given StatsD server via UDP. Counters and timers/histograms are exported immediately, based on sample rate. Gauge export interval is configurable.

Key Default Value Description
experimental required Because this telemeter is still considered experimental, you must set this to true to use it.
prefix linkerd String to prefix all exported metric names with.
hostname 127.0.0.1 Hostname of the StatsD server.
port 8125 Port of the StatsD server.
gaugeIntervalMs 10000 Interval to export Gauges, in milliseconds.
sampleRate 0.01 A value between 0.0 and 1.0 indicating what proportion of counter and timing/histogram events to export. Higher values will result in higher Linkerd latency.

TraceLog

Example TraceLog config

telemetry:
- kind: io.l5d.tracelog
  sampleRate: 0.2
  level: TRACE

kind: io.l5d.tracelog

Log all tracing data, given a log-level and sample rate.

Key Default Value Description
host localhost Host to send trace data to.
sampleRate 1.0 A value between 0.0 and 1.0 indicating what proportion of traces to log.
level INFO Log-level used to log traces. It should be equal (or greater) to the Linkerd log level, set by the -log.level flag or at runtime in the logging tab of the admin dashboard (defaults to INFO). Field can have one of the following values: ALL, CRITICAL, DEBUG, ERROR, FATAL, INFO, OFF, TRACE, WARNING. For full details, see TwitterServer’s Logging documentation.

Recent Requests

Example Recent Requests config

telemetry:
- kind: io.l5d.recentRequests
  sampleRate: 1.0
  capacity: 10

kind: io.l5d.recentRequests

The recent requests telemeter keeps an in-memory record of recent requests and uses it to populate the recent requests table on the admin dashboard. This table can be viewed at /requests on the admin port. Recording requests can have an impact on Linkerd performance, so make sure to set a sample rate that is appropriate for your level of traffic.

Key Default Value Description
sampleRate required A value between 0.0 and 1.0 indicating what proportion of traces to record.
capacity 10 The maximum number of recent traces to store

Zipkin telemeter

Example zipkin config

telemetry:
- kind: io.l5d.zipkin
  host: localhost
  port: 9410
  sampleRate: 0.02

kind: io.l5d.zipkin

Finagle’s zipkin-tracer. Use this telemeter to send trace data to a Zipkin Scribe collector.

Key Default Value Description
host localhost Host to send trace data to.
port 9410 Port to send trace data to (must be the Scribe collector port).
sampleRate 0.001 A value between 0.0 and 1.0 indicating what proportion of requests to trace.

Announcers

An announcer registers servers in service discovery. Each server may specify a list of concrete names to announce as in the announce server key. Each announcer has a prefix and will only announce names that begin with that prefix.

Key Default Value Description
kind required Only io.l5d.serversets is available at this time.
prefix kind-specific Announces names beginning with /#/<prefix>.

Serversets

kind: io.l5d.serversets

Announce to ZooKeeper using the serverset format.

Key Default Value Description
prefix io.l5d.serversets Announces names beginning with /#/<prefix>.
zkAddrs required A list of ZooKeeper addresses, each of which have host and port parameters.
pathPrefix /discovery The ZooKeeper path under which services should be registered.