Make max_header_list_size configurable (Currently 16KB only)

[chbloemer]

What problem are you trying to solve?

I have an issue when sending more than 16kb of headers. We increased header size on our ingress and our application but linkerd is the last in the chain which needs to allow a bigger header size to work.

Linkerd Debug output is:
{"timestamp":"2025-05-22T06:14:04.309437Z","level":"DEBUG","fields":{"message":"received","frame":"Headers { stream_id: StreamId(3), flags: (0x5: END_HEADERS | END_STREAM) }"},"target":"h2::codec::framed_read","threadId":"ThreadId(1)"} {"timestamp":"2025-05-22T06:14:04.309477Z","level":"DEBUG","fields":{"message":"stream error REQUEST_HEADER_FIELDS_TOO_LARGE -- recv_headers: frame is over size; stream=StreamId(3)"},"target":"h2::proto::streams::recv","threadId":"ThreadId(1)"}

linkerd return the following error to the client:
HTTP/1.1 431 Request Header Fields Too Large

Linkerd is using h2 which default header size value is 16kb
https://docs.rs/hyper/latest/hyper/client/conn/http2/struct.Builder.html#method.max_header_list_size

We need the option to increase this value.

How should the problem be solved?

Add an option to make this value configurable.

Any alternatives you've considered?

No. Only removing linkerd. But thats not really an option.

How would users interact with this feature?

Configure it via helm-chart or maybe annotation on the pod.

Would you like to work on this feature?

no

[chbloemer]

If I understand the source code correct. It should be possible to set

LINKERD2_PROXY_OUTBOUND_SERVER_HTTP2_MAX_HEADER_LIST_SIZE=32768
LINKERD2_PROXY_INBOUND_SERVER_HTTP2_MAX_HEADER_LIST_SIZE=32768

Is there a way to set this via annotation?

[alpeb]

There are no explicit settings available for this, but you can use the following escape hatch, adding this into your helm values and then restarting your workloads (note this will apply globally to all your cluster):

proxy:
  additionalEnv:
  - name: LINKERD2_PROXY_OUTBOUND_SERVER_HTTP2_MAX_HEADER_LIST_SIZE
    value: 32768
  - name: LINKERD2_PROXY_INBOUND_SERVER_HTTP2_MAX_HEADER_LIST_SIZE
    value: 32768

Let me know how it goes!

[chbloemer]

It works. Maybe some more documentation about this would be nice. I close the ticket.

The correct setting was:

proxy:
  additionalEnv:
  - name: LINKERD2_PROXY_OUTBOUND_SERVER_HTTP2_MAX_HEADER_LIST_SIZE
    value: "32768"
  - name: LINKERD2_PROXY_INBOUND_SERVER_HTTP2_MAX_HEADER_LIST_SIZE
    value: "32768"

The value must be a string.

[mirrajabi]

This is also the fix for: 431 Request header fields too large

Just adding this comment for SEO reasons to help others get to the answer above since I couldn't find any documentation on it yet.

[gjohnston9]

Also adding for SEO purposes: this is the fix for "header list size to send violates the maximum size (16384 bytes) set by server"

(That was the error we saw with gRPC in Go: google.golang.org/grpc/internal/transport/http2_client.go)

[alpeb]

Thanks for the extra data points. I've raised #14232 to capture the effort for providing a better solution.