Introduction

A Namerd config example

storage:
  kind: io.l5d.inMemory
  namespaces:
    galaxyquest: |
      /host       => /#/io.l5d.fs;
      /svc => /host;
namers:
- kind: io.l5d.fs
  rootDir: examples/disco
interfaces:
- kind: io.l5d.thriftNameInterpreter
  port: 4100
  ip: 0.0.0.0
  retryBaseSecs:  600
  retryJitterSecs: 60
- kind: io.l5d.httpController
  port: 4321

Welcome to the Configuration Reference for Namerd!

Namerd’s configuration is controlled via a 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.

File Format

The configuration may be specified as a JSON or YAML object.

Key	Required	Description
admin	no	Configures Namerd’s administrative interface. Namerd admin has the same options as Linkerd admin.
interfaces	yes	Configures Namerd’s published network interfaces.
storage	yes	Configures Namerd’s storage backend.
namers	no	Configures Namerd’s integration with various service discovery backends. Namerd uses the same namers as Linkerd.
telemetry	no	Configures Namerd’s metrics instrumentation. Namerd does not support tracing, so tracers provided by telemeters are ignored.

Administrative interface

admin:
  ip: 127.0.0.1
  port: 9991

Namerd supports an administrative interface. The exposed admin port and IP 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. See Socket Options
shutdownGraceMs	10000	maximum grace period before the Namerd process exits
tls	no tls	The admin interface will serve over TLS if this parameter is provided. see TLS.
workerThreads	2	The number of worker threads used to serve the admin interface.

Administrative endpoints

Namerd’s admin interface mirrors Linkerd’s, with one exception: the /delegator.json endpoint in Linkerd is served as /dtab/delegator.json in Namerd.

To learn about default admin endpoints, have a look at Linkerd’s administrative interface.

For metrics information, Namerd also exposes Linkerd’s CommonMetrics endpoints by default.

Interfaces

An interface is a published network interface to Namerd. All of the interfaces listed below provide Finagle’s NameInterpreter functionality for remote resolution of destinations using dtabs stored in Namerd. Additionally, the io.l5d.httpController interface provides a dtab read/write API that’s used by namerctl.

Key	Default Value	Description
kind	required	Either `io.l5d.thriftNameInterpreter`, `io.l5d.mesh`,`io.l5d.destination` or `io.l5d.httpController`.
ip	interface dependent	The local IP address on which to serve the namer interface.
port	interface dependent	The port number on which to serve the namer interface.
socketOptions	none	Socket options for a configured interface. See Socket Options
tls	no tls	The namer interface will serve over TLS if this parameter is provided. See Server TLS.

Thrift Name Interpreter

kind: io.l5d.thriftNameInterpreter

A read-only interface providing NameInterpreter functionality over the ThriftMux protocol. Use Linkerd’s io.l5d.namerd interpreter to resolve destinations via this interface.

Key	Default Value	Description
ip	loopback address	The local IP address on which to serve the namer interface. A value like 0.0.0.0 configures Namerd to listen on all local IPv4 interfaces.
port	`4100`	The port number on which to serve the namer interface.
socketOptions	none	Socket options for the thrift name interpreter interface. See Socket Options
cache	see cache	Binding and address cache size configuration.
tls	no tls	The namer interface will serve over TLS if this parameter is provided. See Server TLS.

Cache

Key	Default Value	Description
bindingCacheActive	`1000`	The size of the binding active cache.
bindingCacheInactive	`100`	The size of the binding inactive cache.
bindingCacheInactiveTTLSecs	`600`	The amount of time, in seconds, to keep objects in the binding inactive cache before expiring them.
addrCacheActive	`1000`	The size of the address active cache.
addrCacheInactive	`100`	The size of the address inactive cache.
addrCacheInactiveTTLSecs	`600`	The amount of time, in seconds, to keep objects in the address inactive cache before expiring them.

gRPC Mesh Interface

kind: io.l5d.mesh

A read-only interface providing NameInterpreter functionality over the gRPC protocol. Use Linkerd’s io.l5d.mesh interpreter to resolve destinations via this interface.

Key	Default Value	Description
ip	loopback address	The local IP address on which to serve the namer interface. A value like 0.0.0.0 configures Namerd to listen on all local IPv4 interfaces.
port	`4321`	The port number on which to serve the namer interface.
socketOptions	none	Socket options for the mesh interface. See Socket Options
tls	no tls	The namer interface will serve over TLS if this parameter is provided. See Server TLS. The server TLS key file must be in PKCS#8 format.

Linkerd2 Destination Interface

kind: io.l5d.destination

A gRPC interface implementation based on Linkerd 2’s destination API. It’s intended for Linkerd 2 proxies to resolve request paths through Namerd’s interpreter in a Linkerd 1.x Kubernetes daemonset environment.

Key	Default Value	Description
ip	loopback address	The local IP address on which to serve the destination interface. A value like 0.0.0.0 configures Namerd to listen on all local IPv4 interfaces.
port	`8086`	The port number on which to serve the destination interface.
socketOptions	none	Socket options to set for the l5d2 destination interface. See Socket Options
prefix	/svc	The prefix to use when delegating Linkerd2 request paths to Namerd
namespace	default	The namespace with which Namerd should use to retrieve a dtab

Http Controller

kind: io.l5d.httpController

The HTTP controller provides APIs for reading and writing dtabs, as well as for viewing how names are resolved. This API can also be accessed using the namerctl command line tool. Additionally, this API provides an HTTP implementation of the NameInterpreter interface. Use Linkerd’s io.l5d.namerd.http interpreter to resolve destinations via this interface.

Key	Default Value	Description
ip	loopback address	The local IP address on which to serve the namer interface. A value like 0.0.0.0 configures Namerd to listen on all local IPv4 interfaces.
port	`4180`	The port number on which to serve the namer interface.
socketOptions	none	Socket options to set for the http controller interface. See Socket Options
tls	no tls	The namer interface will serve over TLS if this parameter is provided. See Server TLS.

GET /api/1/dtabs

Sample request

curl :4180/api/1/dtabs

Sample response

["default"]

Returns a list of all dtab namespaces.

Response Code	Description
200	Ok

Content-types: application/json

GET /api/1/dtabs/<namespace>

Sample request

curl :4180/api/1/dtabs/default

Sample response

[{"prefix":"/svc","dst":"/#/io.l5d.fs"}]

Returns the requested dtab. The dtab version is returned in the Etag response header.

Parameter	Type	Description
namespace	path	The dtab namespace to retrieve.
watch	uri	If true, updates are returned as a streaming response.
Accept	header	The requested content type for the dtab (`application/dtab` or `application/json`).

Response Code	Description
200	Ok
404	Dtab namespace does not exist

Content-types: application/json, application/dtab

POST /api/1/dtabs/<namespace>

Sample request

curl :4180/api/1/dtabs/pandoracorn -X POST -d '/foo => /bar' -H 'Content-Type: application/dtab'

Sample response (204 NO CONTENT)

Creates a new dtab with the given namespace. The post body should contain the dtab to create and can be in json or dtab format.

Parameter	Type	Description
namespace	path	The dtab namespace to create.
Content-Type	header	The content type of the provided dtab (`application/dtab` or `application/json`).
N/A	post-body	The dtab to create.

Response Code	Description
204	Created
400	Dtab is malformed
409	Dtab namespace already exists

PUT /api/1/dtabs/<namespace>

Sample request

curl :4180/api/1/dtabs/pandoracorn -X PUT -d '/bar => /bas' -H 'Content-Type: application/dtab'

Sample response (204 NO CONTENT)

Modifies an existing dtab. The post body should contain the updated dtab.

Parameter	Type	Description
namespace	path	The dtab namespace to update.
Content-Type	header	The content type of the provided dtab (`application/dtab` or `application/json`).
If-Match	header	If provided, the update will only be applied if the If-Match header matches the current dtab version. This can be used to prevent conflicting updates.
N/A	post-body	The dtab to create.

Response Code	Description
204	Updated
400	Dtab is malformed
404	Dtab namespace does not exist
412	If-Match header is provided and does not match the current dtab version

DELETE /api/1/dtabs/<namespace>

Sample request

curl :4180/api/1/dtabs/pandoracorn -X DELETE

Sample response (204 NO CONTENT)

Deletes an existing dtab with the given namespace. Returns status code 404 if the dtab namespace does not exist.

Parameter	Type	Description
namespace	path	The dtab namespace to delete.

Response Code	Description
204	Deleted
404	Dtab namespace does not exist

GET /api/1/bind/<namespace>

Sample request

curl ':4180/api/1/bind/default?path=/http/1.1/GET/default'

Sample response

{
   "bound" : {
      "addr" : {
         "type" : "bound",
         "meta" : {},
         "addrs" : [
            {
               "meta" : {},
               "ip" : "127.0.0.1",
               "port" : 9990
            }
         ]
      },
      "id" : "/#/io.l5d.fs/default",
      "path" : "/"
   },
   "type" : "leaf"
}

Returns the bound tree for the given logical name in the context of the given namespace.

Parameter	Type	Description
namespace	path	The dtab namespace to use.
path	uri	The logical name to bind.
dtab	uri	Additional dtab entries to use, in application/dtab format.
watch	uri	If true, updates are returned as a streaming response.

Response Code	Description
200	Ok
400	Path is malformed

Content-types: application/json

GET /api/1/addr/<namespace>

Sample request

curl ':4180/api/1/addr/default?path=/%23/io.l5d.fs/default'

Sample response

{
   "addrs" : [
      {
         "meta" : {},
         "ip" : "127.0.0.1",
         "port" : 9990
      }
   ],
   "meta" : {},
   "type" : "bound"
}

Returns the addresses for a given concrete name.

Parameter	Type	Description
namespace	path	The dtab namespace to use.
path	uri	The logical name to bind.
watch	uri	If true, updates are returned as a streaming response.

Response Code	Description
200	Ok
400	Path is malformed

Content-types: application/json

GET /api/1/resolve/<namespace>

Sample request

curl ':4180/api/1/bind/resolve?path=/http/1.1/GET/default'

Sample response

{
   "type" : "bound",
   "meta" : {},
   "addrs" : [
      {
         "ip" : "127.0.0.1",
         "meta" : {},
         "port" : 9990
      }
   ]
}

Returns the addresses for a given logical name. This is effectively a combination of the bind and addr APIs.

Parameter	Type	Description
namespace	path	The dtab namespace to use.
path	uri	The logical name to bind.
dtab	uri	Additional dtab entries to use, in application/dtab format.
watch	uri	If true, updates are returned as a streaming response.

Response Code	Description
200	Ok
400	Path is malformed

Content-types: application/json

GET /api/1/delegate/<namespace>

Sample request

curl ':4180/api/1/bind/delegate?path=/svc/default'

Sample response

{
   "path" : "/svc/default",
   "type" : "delegate",
   "delegate" : {
      "bound" : {
         "path" : "/",
         "addr" : {
            "type" : "bound",
            "addrs" : [
               {
                  "meta" : {},
                  "ip" : "127.0.0.1",
                  "port" : 9990
               }
            ],
            "meta" : {}
         },
         "id" : "/#/io.l5d.fs/default"
      },
      "type" : "leaf",
      "dentry" : {
         "prefix" : "/svc",
         "dst" : "/#/io.l5d.fs"
      },
      "path" : "/#/io.l5d.fs/default"
   }
}

Returns a delegation tree for a given logical name which shows each step of the delegation process.

Parameter	Type	Description
namespace	path	The dtab namespace to use.
path	uri	The logical name to bind.
dtab	uri	Additional dtab entries to use, in application/dtab format.
watch	uri	If true, updates are returned as a streaming response.

Response Code	Description
200	Ok
400	Path is malformed

Content-types: application/json

GET /api/1/bound-names

Sample Request

curl :4180/api/1/bound-names

Sample Response

[
   "/#/io.l5d.fs/default"
]

Returns a list of concrete names that Namerd knows about.

Parameter	Type	Description
watch	uri	If true, updates are returned as a streaming response.

Response Code	Description
200	Ok

Content-types: application/json

Storage

A storage object configures the Namerd dtabStore which stores and retrieves dtabs. This object supports the following parameters:

Key	Default Value	Description
kind	required	Either `io.l5d.inMemory`, `io.l5d.k8s`, `io.l5d.zk`, `io.l5d.etcd` or `io.l5d.consul`.
experimental	`false`	Set this to `true` to enable the storage if it is experimental.

In Memory

kind: io.l5d.inMemory

Stores the dtab in memory. Not suitable for production use.

Key	Default Value	Description
namespaces	empty map	A map of namespaces to corresponding dtabs.

Kubernetes

kind: io.l5d.k8s

Stores the dtab with the Kubernetes master via the ThirdPartyResource APIs. Requires a cluster running Kubernetes 1.2+ with the ThirdPartyResource feature enabled.

Key	Default Value	Description
host	`localhost`	The Kubernetes master host.
port	`8001`	The Kubernetes master port.
namespace	`default`	The Kubernetes namespace in which dtabs will be stored. This should usually be the same namespace in which Namerd is running.

How to check if ThirdPartyResource is enabled (for Kubernetes v1.7 and below)

Open extensions/v1beta1 api - https://<k8s-cluster-host>/apis/extensions/v1beta1.
Check that kind ThirdPartyResource exists in the response.

Example ThirdPartyResource response

{
  "kind": "APIResourceList",
  "groupVersion": "extensions/v1beta1",
  "resources": [
    {
      "name": "thirdpartyresources",
      "namespaced": false,
      "kind": "ThirdPartyResource"
    }
  ]
}

Example of configuration for ThirdPartyResource in Kubernetes

Use this configuration to create the ThirdPartyResource if it does not exist.

metadata:
  name: d-tab.l5d.io # the hyphen is required by the Kubernetes API. This will be converted to the CamelCase name "DTab".
apiVersion: extensions/v1beta1
kind: ThirdPartyResource
description: stores dtabs used by Buoyant's `namerd` service
versions:
  - name: v1alpha1 # Do not change this value as it hardcoded in Namerd and doesn't work with other value.

How to check if CustomResourceDefinition is enabled (for Kubernetes v1.8+)

Open apiextensions.k8s.io/v1beta1 api - https://<k8s-cluster-host>/apis/apiextensions.k8s.io/v1beta1.
Check that kind CustomResourceDefinition exists in the response.

Example CustomResourceDefinition response

{
  "kind": "APIResourceList",
  "apiVersion": "v1",
  "groupVersion": "apiextensions.k8s.io/v1beta1",
  "resources": [
  {
    "name": "customresourcedefinitions",
    "singularName": "",
    "namespaced": false,
    "kind": "CustomResourceDefinition"
  }
  ]
}

Example of configuration for CustomResourceDefinition in Kubernetes

To create a new CustomResourceDefinition if using Kubernetes 1.8 and greater, use this configuration.

kind: CustomResourceDefinition
apiVersion: apiextensions.k8s.io/v1beta1
metadata:
  name: dtabs.l5d.io
spec:
  scope: Namespaced
  group: l5d.io
  version: v1alpha1
  names:
    kind: DTab
    plural: dtabs
    singular: dtab

For a complete example configuration for Namerd configured with k8s storage, see the linkerd-examples repo.

ZooKeeper

kind: io.l5d.zk

Stores the dtab in ZooKeeper.

Key	Default Value	Description
zkAddrs	required	A list of ZooKeeper addresses, each of which have `host` and `port` parameters.
pathPrefix	`/dtabs`	The ZooKeeper path under which dtabs should be stored.
sessionTimeoutMs	`10000`	ZooKeeper session timeout in milliseconds.
authInfo	no auth when logging	Configures the authentication information to use when logging. See authInfo.
acls	an empty list	A list of ACLs to set on each dtab znode created. See acls.

authInfo

Key	Default Value	Description
scheme	required	The ZooKeeper auth scheme to use.
auth	required	The ZooKeeper auth value to use.

acls

Key	Default Value	Description
scheme	required	The ACL auth scheme to use.
id	required	The ACL id to use.
perms	required	A subset of the string “crwda” representing the permissions of this ACL. The characters represent create, read, write, delete, and admin, respectively.

Etcd

kind: io.l5d.etcd

Stores the dtab in etcd.

Key	Default Value	Description
experimental	required	Because this storage is still considered experimental, you must set this to `true` to use it.
host	`localhost`	The location of the etcd API.
port	`2379`	The port used to connect to the etcd API.
pathPrefix	`/namerd/dtabs`	The key path under which dtabs should be stored.
tls	no tls	Use TLS encryption for connections to etcd. See Namer TLS.

Consul

kind: io.l5d.consul

Stores the dtab in Consul KV storage.

The current state of Consul stored dtabs can be viewed at the admin endpoint: /storage/<pathPrefix>.json.

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.

Namer TLS

Linkerd supports encrypted communication via TLS to io.l5d.consul and io.l5d.etcd namer backends.

namers:
- kind: ...
  host: ...
  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.