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:

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.

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:

Endpoints only available in Linkerd:

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):

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.

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

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.