Add Hostname concept and explanation document

[youngnick]

This adds a document that further explains how the various hostname fields in Gateway API work together, and how integrations should consume them.

/kind documentation

NONE

[kflynn]

@youngnick This is great, thanks! I made some suggestions, but with one exception (my question about "suffix match" at one point), these are minor. (The biggest diff is mostly reordering what you wrote. 🙂)

[krishicks]

Is there a description of the algorithm used for intersecting hostnames? A pointer to actual code would be helpful.

[youngnick]

This the closest thing we have today. There is no supplied-by-the-project implementation of hostname intersection, it's just implied by how the spec and the conformance tests work.

I acknowledge this is not ideal, I've started roughing out what some library functions to handle this would look like.

[krishicks]

This line is maybe a little confusing because "precise" hostnames were just defined as e.g. "www.example.com", but there's no more precise version of that hostname, and any less precise would make it a wildcard hostname, right? It feels like the precision of any wildcard hostnames can be ordered, with the most-precise exact match (true "precise" hostname) being a winner over any wildcard.

[youngnick]

I added a little more explanation - this is intended to guide folks a little bit in implementation.

When sorting a list of hostnames:

• hostnames with no wildcards sort before hostnames with wildcards
• Precise Hostnames with more labels sort before precise hostnames with less labels (that is sub.domain.example.com is before www.example.com).
• The special hostname * is always last.

[youngnick]

Still aiming to add some helpers to the types to handle this, but this should help in the meantime.

[rostislavbobo]

Thanks @youngnick for clarifying this long-standing ambiguity! My main concern is introducing a breaking change if we force *.com TLS listeners to reject www.example.com SNI hostnames (whether for passthrough or termination using certificates with, for instance, both *.example.com, *.com SANs listed).

[rikatz]

A heads up this table is not rendered fine on the page (you need to scroll left/right), not sure how to improve it tho

[youngnick]

Yeah, I didn't like that either, but I couldn't think of a better way to represent all this information at once.

[krishicks]

Some additional feedback after viewing the netlify preview, but otherwise it looks good to me!

[rikatz]

nit (do as a followup): it is slightly confusing if implementation here is the Gateway API implementation (which I know it is) or the controller integrating with Gateway API

[youngnick]

I've tried to be consistent in using "implementation" for the actual Gateway API reconciler, and "integration" for things that consume Gateway API - that's what we call it on the implementations page as well.

Maybe I should explain that at the top of the page as well?

[rikatz]

/hold
/lgtm
feel free to wait for @robscott or unhold

[robscott]

Thanks @youngnick!

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: robscott, youngnick

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [robscott,youngnick]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[youngnick]

/unhold

Next LGTM should merge this one, we can iterate from here.

[rikatz]

/lgtm

Thanks Nick!