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:

172.20.0.4:4567 [/#/io.l5d.fs/icecube] (residual: /cubes/smallCube/pivot)

This is exactly what I expected. I interpreted this to correspond to a URL like 172.20.0.4:4567/cubes/smallCube/pivot, 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:

linkerd.yaml:

admin:
  port: 9990

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

namerd.yaml:

storage:
  kind: io.l5d.inMemory
  namespaces:
    default: |
      /hosts          => /#/io.l5d.fs;
      /svc/oddShard   => /hosts/icecube/cubes/smallCube;
namers:
- kind: io.l5d.fs
  rootDir: static-config
interfaces:
- kind: io.l5d.thriftNameInterpreter
  port: 4100
  ip: 0.0.0.0
  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.)