How are residuals calculated and used?

I have a toy setup using linkerd and namerd that is not behaving the way I thought it would. Config files are below. When I use the linkerd’s delegator interface to resolve /svc/oddShard/pivot it gives me this ultimate result: [/#/io.l5d.fs/icecube] (residual: /cubes/smallCube/pivot)

This is exactly what I expected. I interpreted this to correspond to a URL like, which would be perfect.

However, when I actually hit linkerd:4568/oddShard/pivot, that is hitting my service with a URI of just /pivot instead of the full residual /cubes/smallCube/pivot.

Am I wrong in expecting the whole residual to become the URI path in the eventual API request?

Here are the configs:


  port: 9990

- protocol: http
  label: java-spark
  - port: 4568
    kind: io.l5d.path
    segments: 1
    consume: true
    kind: io.l5d.namerd
    dst: /$/inet/namerd/4100


  kind: io.l5d.inMemory
    default: |
      /hosts          => /#/io.l5d.fs;
      /svc/oddShard   => /hosts/icecube/cubes/smallCube;
- kind: io.l5d.fs
  rootDir: static-config
- kind: io.l5d.thriftNameInterpreter
  port: 4100
  retryBaseSecs:  600
  retryJitterSecs: 60
- kind: io.l5d.httpController
  port: 4321

Hi @prdoyle! Good question, this is a common point of confusion. The residual is the leftover bit of the name that is not used after dtab resolution. It is not appended to the request URI. Linkerd generally only routes requests and does not modify the request URI (the only exception to this is the path segments consumed by the io.l5d.path identifier).

1 Like

Ok I see. So the rewriting is only for routing; once the target host has been computed, it’s the original URI that’s passed in, possibly minus consumed path secments. Is that right?

So if I do want to modify the URI, I guess my best bet is io.l5d.rewrite?

Yup, that’s exactly right.

Linkerd generally does not do URI modification. The io.l5d.rewrite namer is only for routing also. To do modification of the request, I recommend adding something like NGINX.

Oh I see. May I ask why? It seems like a very simple and powerful capability to offer.

(Having said that, when I started redesigning with this new insight in mind, I realized that it led to a cleaner design, so perhaps I’m observing the wisdom of linkerd.)