Clarify documentation of RequestHeaderModifier `.set` and `.add` behaviour

[FredrikAugust]

What would you like to be added:

The documentation for set currently reads:

To edit an existing header, use the set action and specify the value of the header to be modified and the new header value to be set.

However, according to the implementation by Traefik it actually sets it regardless of it exists or not. Go playground

This also goes for the add functionality, which according to the implementation in Traefik will add values iteratively, i.e. if an incoming request already has header x-header set to value and you add the add filter with value2 the actual header value will be value,value2. This is just a clarification I think could be useful to add.

If this is a wrong implementation by Traefik then let me know and I'll move the issue over there.

Why this is needed:

To avoid confusion when using the filters.

[youngnick]

I think the issue here is that we haven't been clear enough about the expected behavior.

set is supposed to unconditionally set that header to that value and only that value. So, if the header is not present, then the header will be added, set to the specified value. If values are already set, they will be overridden with the specified value.

That's how you can edit a header that's already existing - set will do that if it's already set, with the side effect that it will set it if unset.

add is supposed add to values, setting them if unset, and adding comma-separated values to an existing header if the header already exists.

If you are looking for "edit this value if present and don't do anything if not", I don't think we have a way to do that at the moment.

From what I can see above, Traefik is behaving according to the spec.

[FredrikAugust]

That's what I was expecting @youngnick, and I'm glad to hear that this is the intended behaviour. Then I think it should just be clarified in the docs, as it now reads:

To edit an existing header, use the set action and specify the value of the header to be modified and the new header value to be set.

Which for me implies that set does not unconditionally set, but rather only sets if it is already present.

[youngnick]

Yes, I agree that line could be changed to something more like:

To edit an existing header, use the fact that set unconditionally sets a header to override whatever is in that header using the same header name and the new value.

or something.

Does that make more sense to you @FredrikAugust?

[FredrikAugust]

It stills appears a little self-contradictory to me as the first sentence reads "existing header" which implies that the header has to be there in the first place — which we have established is not the case.

What about:

To unconditionally set the value of a header, use set. It will override the value of a header with the provided value if the header is already present, or set it to the provided value if the header does not exist.

[youngnick]

Sorry for the delay here @FredrikAugust. That suggestion lgtm.

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale