Linkerd2: Developer Documentation

[manimaul]

Feature Request

The Linkerd2-Proxy needs better developer documentation. Empower contributors to be able to work in the productivity fast lane

What problem are you trying to solve?

Contributing developers should be able to read docs that demonstrate a simple setup in order to easily build, run and debug the proxy inside and outside of a k8s environment.

How should the problem be solved?

The Linkerd2-Proxy repo needs good developer documentation allowing them to:

• Build
• Run (locally, outside of a k8s environment)
• Debug (provide tooling for building a remote debuggable image)
• Understand the proxy project architecture
  
  
  
  • Documentation describing the assembly of the pipeline/layer cake (Layer, Stack, Service)
  
  

There should be some canned dev environment / setups documented that allow developers to get up and running in development mode with minimal dependencies.

Any alternatives you've considered?

How would users interact with this feature?

By reading and following documentation. :)

[hawkw]

I definitely agree that the internal architecture of the proxy codebase ought to be better documented!

Regarding docs for how to run the proxy, are there make targets(s) that could be added to the proxy's Makefile to make this easier? IMO it's probably less flaky to automate things than to explain them, if that makes sense.

[manimaul]

@hawkw Makefile targets would be great as that is where one will likely be looking first when looking to contribute. There likely needs to be some accompanying documentation. For example if I start up the proxy with LINKERD2_PROXY_LOG=debug LINKERD2_PROXY_POD_NAMESPACE=linkerd cargo run and notice the log output:

INFO linkerd2_proxy::app::main routing on V4(127.0.0.1:4140)
INFO linkerd2_proxy::app::main proxying on V4(0.0.0.0:4143) to None

Then I refer back to the code I notice that V4(127.0.0.1:4140) is outbound_listener pipeline which I kind of assume if for proxying local requests outbound.

I also refer back to the code and notice V4(0.0.0.0:4143) is the inbound_listener pipeline and assume it is for reverse proxying inbound requests.

So, I also have debug symbols on so I can step through the code and observe.

[profile.dev]
debug = true 

Now, I spin up some http service with docker: docker run -p 8080:80 nginx:1.7.9
And, I attempt to proxy a request with curl manipulating the host header: curl -iv 127.0.0.1:4140 -H "Host: localhost:8080"

I also want to inspect the proxy behavior for the reverse proxy functionality. This kind of process should be documented somewhere IMO.

[zaharidichev]

I absolutelly support that. As a new commer lurking around the code its quite hard for me to grasp the basic data pipeline. As a matter of fact a write up that is something like "The life of a request" will be very useful. Just tracking what happens when an http request hits a pod, how is that instrumented relayed, etc as well as providing pointers to concrete parts of the code will be super useful. That will certainly make it a lot easier for people to get started working with the codebase.