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

Introduction

A namerd config example

storage:
  kind: io.l5d.inMemory
  namespaces:
    galaxyquest: |
      /host       => /#/io.l5d.fs;
      /http/1.1/* => /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 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 no 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.

Administrative interface

admin:
  port: 9991

namerd supports an administrative interface. The exposed admin port is configurable via a top-level admin section.

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

Interfaces

An interface is a published network interface to namerd.

Key Default Value Description
kind required Either io.l5d.thriftNameInterpreter 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 server the namer interface.

Thrift Name Interpreter

kind: io.l5d.thriftNameInterpreter

A read-only interface providing NameInterpreter functionality over the ThriftMux protocol.

Key Default Value Description
ip 0.0.0.0 The local IP address on which to serve the namer interface.
port 4100 The port number on which to server the namer interface.
retryBaseSecs 600 Base number of seconds to tell clients to wait before retrying after an error.
retryJitterSecs 60 Maximum number of seconds to jitter retry time by.
cache see cache Binding and address cache size configuration.

Cache

Key Default Value Description
bindingCacheActive 1000 The size of the binding active cache.
bindingCacheInactive 100 The size of the binding inactive cache.
addrCacheActive 1000 The size of the address active cache.
addrCacheInactive 100 The size of the address inactive cache.

Http Controller

kind: io.l5d.httpController

A read-write HTTP interface to the storage.

Key Default Value Description
ip loopback The local IP address on which to serve the namer interface.
port 4180 The port number on which to serve the namer interface.

Storage

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

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
experimental required Because this storage is still considered experimental, you must set this to true to use it.
host kubernetes.default.svc.cluster.local The location of the Kubernetes API.
port 443 The port used to connect to the Kubernetes API.
tls true Whether to connect to the Kubernetes API using TLS.
tlsWithoutValidation false Whether to disable certificate checking against the Kubernetes API. Meaningless if tls is false.
authTokenFile no auth The location of the token used to authenticate against the Kubernetes API, if any.
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 ThirdPartyResource is enabled 1. Open extensions/v1beta1 api - https://<k8s-cluster-host>/apis/extensions/v1beta1. 2. Check that kind ThirdPartyResource exists in response:

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

Example of configuration for ThirdPartyResource in Kubernetes

  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.

Complete example of Namerd configuration with k8s storage and exposed 2 services for sync with Linkerd and Namerd API:

apiVersion: v1
kind: Service
metadata:
  name: namerd-sync
spec:
  selector:
    app: namerd
  ports:
  - name: sync
    port: 4100
---
apiVersion: v1
kind: Service
metadata:
  name: namerd-api
spec:
  selector:
    app: namerd
  ports:
  - name: api
    port: 4180
---
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.
---
kind: ConfigMap
apiVersion: v1
metadata:
  name: namerd-config
data:
  config.yml: |-
    admin:
      port: 9991
    storage:
      kind: io.l5d.k8s
      experimental: true
    namers:
      - kind: io.l5d.k8s
        experimental: true
        host: 127.0.0.1
        port: 8001
    interfaces:
      - kind: io.l5d.thriftNameInterpreter
        ip: 0.0.0.0
        port: 4100
      - kind: io.l5d.httpController
        ip: 0.0.0.0
        port: 4180
---
kind: ReplicationController
apiVersion: v1
metadata:
  name: namerd
spec:
  replicas: 1
  selector:
    app: namerd
  template:
    metadata:
      labels:
        app: namerd
    spec:
      dnsPolicy: ClusterFirst
      volumes:
        - name: namerd-config
          configMap:
            name: namerd-config
      containers:
        - name: namerd
          image: buoyantio/namerd:<version> # specify required version or remove to use the latest
          args:
            - /io.buoyant/namerd/config/config.yml
            - -com.twitter.finagle.tracing.debugTrace=true
            - -log.level=DEBUG
          imagePullPolicy: Always
          ports:
            - name: sync
              containerPort: 4100
            - name: api
              containerPort: 4180
          volumeMounts:
            - name: "namerd-config"
              mountPath: "/io.buoyant/namerd/config"
              readOnly: true
        - name: kubectl
          image: buoyantio/kubectl:<version> # specify required version or remove to use the latest
          args:
          - "proxy"
          - "-p"
          - "8001"
          imagePullPolicy: Always

ZooKeeper

kind: io.l5d.zk

Stores the dtab in ZooKeeper.

Key Default Value Description
experimental required Because this storage is still considered experimental, you must set this to true to use it.
zkAddrs required A list of ZooKeeper addresses, each of which have host and port parameters.
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.

Consul

kind: io.l5d.consul

Stores the dtab in Consul KV storage.

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