Add HTTP Rewrite and Redirect Filter guide

[rainest]

What type of PR is this?
/kind documentation

What this PR does / why we need it:
Adds a guide for GEP-726 features, including the changes currently under review in #1124

It is a WIP for two reasons:

• For HTTP->HTTPS redirects, are implementations expected to not redirect requests that are already HTTPS, or does the spec allow misconfigurations that result in redirect loops? If so, how should users properly set up their HTTPRoutes and Gateway Listener configuration to only match these redirect rules on HTTP requests? I expect this generalizes to path/hostname/etc. also, but this was the most prominent case I could think of.
• Do we care about path types for path modifiers? It seems that you can use prefix modifiers for exact paths, though it's probably pointless (if harmless), and I'm not sure whether RegularExpression paths would be considered prefixes here (i.e. ReplacePrefixMatch changes only the path segment matching the regex).
• I added the text suggested in Document HTTPRoute Filter Compatibility #928 mostly as-is, but it raises the question "what status must we set?". It seems like we need a new RouteConditionType for filter-related statuses if we want this, or a new RouteConditionReason (it doesn't seem like it'd fit under any of the existing types unless we reject routes with invalid filters entirely, and I wouldn't expect to since they're per-rule and since the text indicates this should just be a warning, not an error).

As a side note, I have bad timing and will be out from 5/18-5/28, so it may make sense to use this as a starting point for someone else if review takes time or it needs significant changes. Edit: then I forgot this is the week that a bunch of people are at Kubecon 🙂 I should actually be able to check things on the 26th even though I'm still technically out.

Which issue(s) this PR fixes:
Fixes #1038
Fixes #928

Does this PR introduce a user-facing change?:

NONE

[k8s-ci-robot]

Hi @rainest. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[robscott]

/ok-to-test

[robscott]

Thanks @rainest, this is really great!

[robscott]

Good point, I think #1166 will resolve this.

[rainest]

Original in case the diff does something silly now that it's gone:

Do these behave at all differently based on matches.path.type? I expect no, and that implementations should just always replace only the matching path prefix or the entire path. Using ReplacePrefixMatch on Exact is the same as ReplaceFullPath. RegularExpression looks a bit ambiguous, since the PathMatchType looks unclear on whether they're handled as prefixes or not.

I simply removed this without adding additional explanation since it looks like 1166's answer is just "you can't configure them on those other types". Do we think we'd need explanation of that here or is that too far off into the weeds?

[rainest]

examples/experimental/http-redirect-rewrite/httproute-redirect-https.yaml is technically already valid under v1alpha2, but I expect it's easier to not split hairs and just call the whole thing experimental, assuming it'll imminently become not experimental and we'll move the whole directory back.

[youngnick]

/lgtm

Nice work @rainest, this is very clear.

[shaneutt]

Looks like we're at a point with this one where we can remove [WIP] from the name. Thanks Travis for the effort on this one, looks great.

/lgtm

[robscott]

Thanks @rainest! Mostly LGTM, just a few small nits. On an unrelated note, if anyone wants to remove https://github.com/kubernetes-sigs/gateway-api/blob/master/site-src/css/extra.css, I would welcome that. The alignment that results in is particularly bad with this new page.

[rainest]

@robscott do we indeed want the backref comments in examples? Those do actually render in the guide:

The other examples don't include the same; their usage is just loosely indicated by the directory name, though I'm not sure others have the same quality where the guide is under v1alpha2 and the examples are under experimental. I removed the original commit from the PR, backrefs.diff.txt if we want to re-add it.

[robscott]

@rainest any chance you checked that after #1186 merged? I had to change the prefix characters to #? to avoid hiding all subheadings. If that doesn't work, I think it's fine to just leave that part out of this PR. This is a great improvement and would love to get it in.

[rainest]

Alright, preview properly stripping the new header (albeit only after the second try for some reason), so this should be all good to go.

[youngnick]

LGTM, I'll just approve though.

/approve

[shaneutt]

/lgtm

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: rainest, shaneutt, youngnick

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

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [youngnick]

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