Update KIC troubleshooting for 2.9 and add GWAPI port note

[rainest]

Description

Revises the Events section of the KIC troubleshooting guide to provide a more detailed example and cover the new Event type to be introduced in 2.9 for Kong/kubernetes-ingress-controller#3551

Adds a note to HTTPRoute documentation indicating that we don't support port restrictions per the GWAPI spec, for Kong/kubernetes-ingress-controller#3315

Testing instructions

Awaiting Netlify.

Revised example is derived from a local runthrough of an Event search.

Checklist

• Review label added
• PR pointed to correct branch (main for immediate publishing, or a release branch: e.g. release/gateway-3.2, release/deck-1.17)

Latter bit is sort of a lie. We don't have a running release branch for KIC 2.9. This also does not add a separate 2.9 version gate in the source because the end user experience for the new 2.9 Event type is virtually identical to the 2.8 experience--the only differences are the Event reason and the situations that cause them (we don't cover the situations in depth though, and it's mostly a technical distinction--users need to fix some problem with a resource regardless of whether KIC catches the problem in translation or apply). The doc does mention this discrepancy with a note admonition.

May make sense to just leave this un-merged after review until 2.9 is out, or just go ahead and merge it (we intend to release 2.9 soon).

[netlify]

✅ Deploy Preview for kongdocs ready!

Name	Link
🔨 Latest commit	a92fefb
🔍 Latest deploy log	https://app.netlify.com/sites/kongdocs/deploys/63f7deff925e1c00078fa9a9
😎 Deploy Preview	https://deploy-preview-5196--kongdocs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[rainest]

https://deploy-preview-5196--kongdocs.netlify.app/kubernetes-ingress-controller/latest/troubleshooting/#identifying-and-fixing-invalid-configuration formatting looks okay. I don't love my presentation of brief "how Event lifecycle works" (there apparently isn't a good description of this upstream? I am only finding unofficial blogs, unfortunately), but eh.

Is there a way to tell Vale to ignore anything within a codeblock? The "typos" it's catching in the examples are all proper case for those Kubernetes resources.

[cloudjumpercat]

Thanks for making these changes! I left a few comments, mostly about if we needed to add conditional rendering to specific examples for 2.9.x vs. 2.8.x. Let me know if you have any questions!

[cloudjumpercat]

I think if we conditionalize the examples I referenced earlier, I don't think this note would be needed.

[cloudjumpercat]

Should we also have an example for 2.8.x since this is specific to 2.9.x?

[cloudjumpercat]

@rainest WRT your other comment on here, I think the "Identify and fix an invalid configuration" section looks good to me! I thought the content flowed well and made sense.

For the Vale errors, I can fix those on your branch in just a minute. I just have to add those words to the dictionary file (I don't believe Vale skips over anything in code).

[rainest]

@cloudjumpercat re all the 2.9/2.8 stuff this is kind of a weird one. For end users, the functionality is virtually identical: if KIC can't process a resource for some reason, it generates an Event, and that Event's message indicates which field is broken.

The distinction between translation and apply failures is largely an internal technical one that matters to us, the application developers, because KIC handles them a bit differently internally. For end users, the action you need to take doesn't change (you always need to correct whatever issue the Event message describes). Apply errors (which only 2.9+ raises) are, however, the ones we expect users to encounter more often, because translation errors we make a best-effort fix--they alert you to something we can't do as requested, but that doesn't break everything. Apply errors, by contrast, do break everything: KIC literally cannot make updates until you fix them.

Given that the user workflow is basically the same for either, I wanted to showcase the more severe problem in examples even though 2.8 doesn't support it. We expect most 2.8 users will just go to 2.9, as 2.9 doesn't have breaking changes, mostly just new functionality you can ignore if it's not of interest to you and bugfixes.

On that basis, I wanted to use a slightly atypical approach without full version gates, because doing that would mean having two basically identical sections with different types of broken resources. I did add a92fefb to hide the note on 2.9 onward and try and clarify a bit, do you think that works?

[cloudjumpercat]

LGTM! Thanks for updating this! I'll hold off on merging until 2.9 is released.

[cloudjumpercat]

@rainest That makes sense to me! Thanks for explaining that :)