Migration guide for Ingress users

[pleshakov]

What would you like to be added:

As part of the guides section of the docs (https://gateway-api.sigs.k8s.io/guides/), add a "Migrating from the Ingress resource" guide to help Ingress users adopt the Gateway API.

Why this is needed:

The Gateway API resources are quite different from the Ingress resource, so explaining the differences and how to translate the Ingress resource to Gateway API resources will hopefully reduce the friction for Ingress users when they try to migrate to the Gateway API.

Note: this is different from the ingress2gateway cli tool -- this is just a guide.

[pleshakov]

I wonder what people think about the following ideas about the migration guide:

Goals:

• Prepare Ingress users to migrate from the Ingress resource to the Gateway API resources.
• Keep the guide Ingress Controller agnostic -- only focus on portable features.
• Make the guide only about the data plane configuration.

Non goals:

• Nothing about live migration (ex. how to migrate to Gateway API resources with zero downtime)

Outline:

• Intro. Explain what this guide is about.
• Key differences between the Ingress API and the Gateway API. Explain about differences in personas. Explain how each part of the Ingress resource map to which Gateway API resources. This will include annotations, but in a way that general enough without mentioning any specific non-portable annotations.
• Migration steps. Provide some steps for a user to take to convert Ingress resources to the Gateway API resources.
• Examples. Show an example of converting Ingress resources to the Gateway API resources. This will cover TLS termination and few routing rules.
• Link to the ingress2gateway documentation/tool for automated conversion of Ingress resources.
• Summary

Happy to volunteer to write a draft.

[robscott]

Thanks @pleshakov! This is a great idea. There's a lot of overlap here with what @shaneutt and I will be talking about in https://sched.co/182IG, it would be great to actually have this kind of content on our website in advance though. Happy to share our WIP slides if they're helpful when writing this.

[shaneutt]

Yes, also sounds like something that would be potentially good to do as part of the upcoming ingress2gateway migration tool (that is, to document using this tool to migrate potentially).

[pleshakov]

great! I will write a draft and create a PR.