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.

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.

Cache

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.

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.

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.

GET /api/1/dtabs

Sample request

curl :4180/api/1/dtabs

Sample response

["default"]

Returns a list of all dtab namespaces.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Content-types: application/json