Introduction

A Linkerd config example

admin:
  port: 9990

routers:
- protocol: http
  label: int-http
  baseDtab: |
    /host       => /#/io.l5d.fs;
    /http/1.1/* => /host;
  identifier:
    kind: io.l5d.methodAndHost
    httpUriInDst: true
  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
  baseDtab: |
    /thrift => /#/io.l5d.fs/thrift;

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

tracers:
- kind: io.l5d.zipkin
  sampleRate: 0.02

Welcome to the Configuration Reference for linkerd!

linkerd’s configuration is controlled via config 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. Four 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.
tracers	no	Configures Linkerd’s request instrumentation.

Administrative interface

admin:
  port: 9990

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

Key	Default Value	Description
port	9990	Port for the admin interface.

Routers

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

routers:
- protocol: http
  baseDtab: /http => /$/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.

Tracers

tracers:
- kind: io.l5d.zipkin
  sampleRate: 0.02

Requests that are routed by Linkerd are also traceable using Finagle’s built-in tracing instrumentation. Trace data can be exported from a Linkerd process by configuring tracers via a top-level tracers section. See tracers.

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, and client, which configures how clients are built.

Router Parameters

routers:
- protocol: http
  servers: ...
  client: ...
  announcers: ...
  bindingCache: ...
  label: myPackIce
  dstPrefix: /walruses/http
  baseDtab: |
    /host                => /#/io.l5d.fs;
    /walruses/http/1.1/* => /host;
  failFast: false
  timeoutMs: 10000
  bindingTimeoutMs: 5000
  responseClassifier: io.l5d.nonRetryable5XX

Key	Default Value	Description
protocol	required	Either http, 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.
baseDtab	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	An object of client params.
dstPrefix	protocol dependent	A path prefix to be used on request destinations.
failFast	false	If true, connection failures are punished more aggressively. Should not be used with small destination pools.
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)
response Classifier	io.l5d.nonRetryable5XX	A (sometimes protocol-specific) response classifier that determines which responses should be considered failures and, of those, which should be considered retryable.
timeoutMs	no timeout	Per-request timeout in milliseconds.

Binding Cache

- protocol: http
  servers:
  - port: 9000
  bindingCache:
    paths: 100
    trees: 100
    bounds: 100
    clients: 10

Key	Default Value	Description
paths	100	Max number of paths in the path cache.
trees	100	Max number of trees in the tree cache.
bounds	100	Max number of bounds in the bounds cache.
clients	10	Max number of clients in the clients cache.

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.
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.

Client Parameters

client:
  tls:
    kind: io.l5d.noValidation
    commonName: foo
    caCertPath: /foo/caCert.pem
  loadBalancer:
    kind: ewma
    enableProbation: false
  retries:
    backoff:
      kind: jittered
      minMs: 10
      maxMs: 10000

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.
retries	see retries	A retry policy for all clients created by this router.

Host Connection Pool

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.
maxWaiters	Int.MaxValue	The maximum number of connection requests that are queued when the connection concurrency exceeds maxSize.

HTTP/1.1 protocol

Below: http-specific configuration options

routers:
- protocol: http
  httpAccessLog: access.log
  identifier:
    kind: io.l5d.methodAndHost
  maxChunkKB: 8KB
  maxHeadersKB: 8KB
  maxInitialLineKB: 4KB
  maxRequestKB: 5MB
  maxResponseKB: 5MB
  servers:
  - port: 5000

Below: an example HTTP router config that routes all POST requests to 8091 and all other requests to 8081, using the default identifier of io.l5d.methodAndHost, listening on port 5000

routers:
- protocol: http
  label: split-get-and-post
  baseDtab: |
    /method/*    => /$/inet/127.1/8081;
    /method/POST => /$/inet/127.1/8091;
    /http/1.1    => /method;
  servers:
  - port: 5000

The baseDtab above is written to work with the methodAndHost identifier. Using a different identifier would require a different set of dtab rules.

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	http	A path prefix used by Http-specific identifiers.
httpAccessLog	none	Sets the access log path. If not specified, no access log is written.
identifier	The methodAndHost identifier	An identifier or list of identifiers. See Http-specific identifiers.
maxChunkKB	8KB	The maximum size of an HTTP chunk.
maxHeadersKB	8KB	The maximum size of all headers in an HTTP message.
maxInitialLineKB	4KB	The maximum size of an initial HTTP message line.
maxRequestKB	5MB	The maximum size of a non-chunked HTTP request payload.
maxResponseKB	5MB	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).

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.

Key	Default Value	Description
kind	required	Either io.l5d.methodAndHost or io.l5d.path.

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.

Namer 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.

Namer 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	http	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.

Namer Configuration:

With this configuration, a request to :5000/true/love/waits.php will be mapped to /http/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.

Namer Path Parameters:

Dtab Path Format

  / dstPrefix [/ *urlPath ]

Key	Default Value	Description
dstPrefix	http	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. If the header value is a valid path, that path is used. Otherwise, the header value is converted to a path with one path segment.

Namer 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

Namer Path Parameters:

Dtab Path Format

  / dstPrefix [/ *headerValue ]

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

HTTP Engines

This configures an HTTP router that uses the new netty4 implementation on both the client and server:

- protocol: http
  servers:
  - port: 4141
    ip: 0.0.0.0
    engine:
      kind: netty4
  client:
    engine:
      kind: netty4

An engine may be configured on HTTP clients and servers, causing an alternate HTTP implementation to be used.

Key	Default Value	Description
kind	netty3	Either netty3 or netty4 (netty4 will become default in an upcoming release).

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 baseDtab 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-logical	The logical name of the request as identified by linkerd.
l5d-dst-concrete	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.

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
  baseDtab: |
    /thrift => /$/inet/127.1/5005;
  servers:
  - port: 4004
    ip: 0.0.0.0
    thriftFramed: false
    thriftProtocol: compact
  client:
    thriftFramed: false
    thriftProtocol: compact

protocol: thrift

Since the Thrift protocol does not encode a destination name in the message itself, routing must be done per port. This implies one port per Thrift service. For out-of-the-box configuration, this means that the contents of disco/thrift will be treated as a newline-delimited list of host:port combinations for a specific thrift service.

Thrift Router Parameters

Key	Default Value	Description
dstPrefix	thrift	A path prefix used in baseDtab.
thriftMethodInDst	false	If true, thrift method names are appended to destinations for outgoing requests.

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.
thriftProtocol	binary	Either binary (TBinaryProtocol) or compact (TCompantProtocol). Typically this setting matches the router’s client thriftProtocol 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.
thriftProtocol	binary	Either binary (TBinaryProtocol) or compact (TCompantProtocol). Typically this setting matches the router’s servers’ thriftProtocol param.
attemptTTwitterUpgrade	true	Controls whether thrift protocol upgrade should be attempted.

Mux Protocol (experimental)

A mux router configuration that routes requests to port 9001

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

protocol: mux

Linkerd experimentally supports the mux protocol.

Mux Router Parameters

Key	Default Value	Description
dstPrefix	mux	A path prefix used in baseDtab.

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, or io.l5d.fs.
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

kind: io.l5d.namerd

The namerd interpreter offloads the responsibilities of name resolution to the namerd service. Any namers configured in this Linkerd are not used.

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.

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.

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.

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	One of the transformer kinds listed below.

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 only route traffic to local destinations.

Port

kind: io.l5d.port

The port transformer replaces the port number in every addresses 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 with 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 k8s 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 post.
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.

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 k8s 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

HTTP Response Classifiers

Example response classifier config

routers:
- ...
  client:
  responseClassifier:
    kind: io.l5d.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.nonRetryable5XX	Either io.l5d.nonRetryable5XX, io.l5d.retryableRead5XX, or io.l5d.retryableIdempotent5XX.

Non-Retryable 5XX

kind: io.l5d.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.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.retryableIdempotent5XX

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

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
  baseDtab: |
    /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
certPath	required	File path to the TLS certificate file.
keyPath	required	File path to the TLS key file.

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:
      kind: io.l5d.noValidation

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

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

Key	Default Value	Description
kind	required	Either io.l5d.noValidation, io.l5d.static, or io.l5d.boundPath.

No Validation TLS

tls:
  kind: io.l5d.noValidation

kind: io.l5d.noValidation

Static TLS

tls:
  kind: io.l5d.static
  commonName: foo
  caCertPath: /foo/caCert.pem

kind: io.l5d.static

Uses a single common name for all TLS requests. This assumes all servers that the router connects to use the same TLS cert (or all use certs generated with the same common name).

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

TLS with Bound Path

tls:
  kind: io.l5d.boundPath
  caCertPath: /foo/cacert.pem
  names:
  - prefix: "/#/io.l5d.fs/{host}"
    commonNamePattern: "{host}.buoyant.io"
  strict: false

kind: io.l5d.boundPath

Determine the common name based on the destination bound path. This plugin supports the following options:

Key	Default Value	Description
caCertPath	?	The path to the CA cert used for common name validation.
names	required	A list of name matchers.
strict	true	When true, paths that fail to match any prefixes throw an exception.

Bound Path Name Matchers

Key	Default Value	Description
prefix	required	A path prefix. All destinations which match this prefix will use this entry to determine the common name. Wildcards and variable capture are allowed (see: io.buoyant.linkerd.util.PathMatcher).
commonNamePattern	required	The common name to use for destinations matching the above prefix. Variables captured in the prefix may be used in this string.

See Transparent TLS with linkerd for more on how boundPath matches prefixes when routing requests.

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, or heap.
enableProbation	false	If true, endpoints are eagerly evicted from service discovery. 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.
smoothWin	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

Retries

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

Linkerd can automatically retry requests on certain failures (for example, connection errors) and can be configured via the retries block.

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.

Retry Budget Parameters

For every 10 non-retry calls, allow 1 retry

client:
  retries:
    budget:
      percentCanRetry: 0.1

For every non-retry call, allow 2 retries

client:
  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, or io.l5d.zkLeader.
prefix	namer dependent	Resolves names with /#/<prefix>.
experimental	false	Set this to true to enable the namer if it is experimental.

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:

baseDtab: |
  /http/1.1/* => /#/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

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:

baseDtab: |
  /http/1.1/* => /#/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 (experimental)

kind: io.l5d.consul

Consul Configuration

Configure a consul namer:

namers:
- kind: io.l5d.consul
  experimental: true
  host: 127.0.0.1
  port: 2181
  includeTag: true
  useHealthCheck: true
  setHost: true
  consistencyMode: stale

Then reference the namer in the dtab to use it:

baseDtab: |
  /http/1.1/* => /#/io.l5d.consul/dc1/prod;

linker provides support for service discovery via Consul.

Key	Default Value	Description
prefix	io.l5d.consul	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 Consul host.
port	8500	The Consul port.
includeTag	false	If true, read a Consul tag from the path.
useHealthCheck	false	If true, rely on Consul health checks.
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

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.
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.

Kubernetes service discovery (experimental)

kind : io.l5d.k8s

K8s Configuration

Configure a K8s namer

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

Then reference the namer in the dtab to use it:

baseDtab: |
  /http/1.1/* => /#/io.l5d.k8s/prod/http;

Linkerd provides support for service discovery via Kubernetes.

Key	Default Value	Description
prefix	io.l5d.k8s	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 post.

K8s Path Parameters

Dtab Path Format

/#/<prefix>/<namespace>/<port-name>/<svc-name>

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.
svc-name	yes	The name of the service.

Marathon service discovery (experimental)

kind: io.l5d.marathon

Marathon Configuration

Configure a marathon namer

namers:
- kind:         io.l5d.marathon
  experimental: true
  prefix:       /#/io.l5d.marathon
  host:         marathon.mesos
  port:         80
  uriPrefix:    /marathon
  ttlMs:        500

Then reference the namer in the dtab to use it:

baseDtab: |
  /marathonId => /#/io.l5d.marathon;
  /host       => /$/io.buoyant.http.domainToPathPfx/marathonId;
  /http/1.1/* => /host;

Linkerd provides support for service discovery via Marathon.

Key	Default Value	Description
prefix	io.l5d.marathon	Resolves names with /#/<prefix>.
experimental	required	Because this namer is still considered experimental, you must set this to true to use it.
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 avaiable at localhost:8080/v2/, while the default setup on AWS/DCOS is $(dcos config show core.dcos_url)/marathon/v2/apps.
ttlMs	500	The polling timeout in milliseconds against the marathon API.

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.

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.

Tracers

Requests that are routed by Linkerd are also traceable using Finagle’s built-in tracing instrumentation.

Key	Default Value	Description
kind	required	Only io.l5d.zipkin is available at this time.

Zipkin

Example zipkin config

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

kind: io.l5d.zipkin

Finagle’s zipkin-tracer.

Key	Default Value	Description
host	localhost	Host to send trace data to.
port	9410	Port to send trace data to.
sampleRate	0.001	What percentage 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.