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
tolocalhost: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 ofio.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, becauseconsume
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. |