Adding ingress-nginx welcome guide along with new "getting started" section (#4334)

* Adding ingress-nginx welcome guide along with new "getting started"
section

* Responding to feedback

Author: robscott

mkdocs.yml

@@ -49,7 +49,8 @@ plugins:
       j2_line_comment_prefix: "#$"
   - redirects:
       redirect_maps:
-        'guides/getting-started.md': 'guides/index.md'
+        'guides/index.md': 'guides/getting-started/index.md'
+        'ingress-nginx': 'guides/getting-started/migrating-from-ingress-nginx.md'
         'concepts/gamma.md': 'mesh/index.md'
         'concepts/service-facets.md': 'mesh/service-facets.md'
         'concepts/guidelines.md': 'guides/api-design.md'

nav.yml

@@ -24,9 +24,12 @@ nav:
     - FAQ: faq.md
     - Glossary: concepts/glossary.md
   - Guides:
+    - Getting Started:
+      - Introduction: guides/getting-started/index.md
+      - Deploying a simple Gateway: guides/getting-started/simple-gateway.md
+      - Migrating from Ingress: guides/getting-started/migrating-from-ingress.md
+      - Migrating from Ingress-NGINX: guides/getting-started/migrating-from-ingress-nginx.md
     - User Guides:
-      - Getting started: guides/index.md
-      - Simple Gateway: guides/simple-gateway.md
       - HTTP routing: guides/http-routing.md
       - HTTP redirects and rewrites: guides/http-redirect-rewrite.md
       - HTTP header modifier: guides/http-header-modifier.md
@@ -40,7 +43,6 @@ nav:
       - TLS: guides/tls.md
       - TCP routing: guides/tcp.md
       - gRPC Routing: guides/grpc-routing.md
-      - Migrating from Ingress: guides/migrating-from-ingress.md
       - Backend Protocol Selection: guides/backend-protocol.md
       - Infrastructure attributes: guides/infrastructure.md
     - API Design: guides/api-design.md

site-src/guides/index.md site-src/guides/getting-started/index.mdsite-src/guides/index.md renamed to site-src/guides/getting-started/index.md

@@ -1,21 +1,37 @@
 # Getting started with Gateway API
 
-**1.**  **[Install a Gateway controller](#installing-a-gateway-controller)**
- _OR_  **[install the Gateway API CRDs manually](#installing-gateway-api)**
-
-_THEN_
-
-**2.**   **Try out one of the available guides:**
-
-- [Simple Gateway](simple-gateway.md) (a good one to start out with)
-- [HTTP routing](http-routing.md)
-- [HTTP redirects and rewrites](http-redirect-rewrite.md)
-- [HTTP traffic splitting](traffic-splitting.md)
-- [Routing across Namespaces](multiple-ns.md)
-- [Configuring TLS](tls.md)
-- [TCP routing](tcp.md)
-- [gRPC routing](grpc-routing.md)
-- [Migrating from Ingress](migrating-from-ingress.md)
+Welcome to the Gateway API! This page is the best place to start, whether you're a new user or migrating from another ingress solution.
+
+## For New Users
+
+If you are new to Gateway API, we recommend the following path:
+
+**1. Install Gateway API CRDs and a Controller**
+
+You can either [install a Gateway controller](#installing-a-gateway-controller) which often installs the CRDs for you, or [install the Gateway API CRDs manually](#installing-gateway-api).
+
+**2. Try out the guides**
+
+Once you have a controller running, you can start with a simple example and then explore more advanced features.
+
+- [Deploying a simple Gateway](./simple-gateway.md) (a good one to start out with)
+- [HTTP routing](../http-routing.md)
+- [HTTP redirects and rewrites](../http-redirect-rewrite.md)
+- [HTTP traffic splitting](../traffic-splitting.md)
+- [Routing across Namespaces](../multiple-ns.md)
+- [Configuring TLS](../tls.md)
+- [TCP routing](../tcp.md)
+- [gRPC routing](../grpc-routing.md)
+
+
+## Migrating from Ingress
+
+If you are looking to migrate from Kubernetes Ingress, we have guides to help you get started.
+
+- **[Migrating from Ingress](./migrating-from-ingress.md)**: A general guide for migrating from any Ingress implementation to Gateway API. It covers the key differences and provides a manual migration example.
+- **[A Welcome Guide for Ingress-NGINX Users](./migrating-from-ingress-nginx.md)**: A guide specifically for users of Ingress-NGINX, the most popular Ingress implementation. It provides a set of resources and answers to frequently asked questions.
+
+---
 
 ## Installing a Gateway controller
 

site-src/guides/getting-started/migrating-from-ingress-nginx.md

@@ -0,0 +1,64 @@
+# A Welcome Guide for Ingress-NGINX Users
+
+Welcome! If you're an Ingress-NGINX user, you're in the right place. This page is a central hub of resources for those considering or actively migrating to Gateway API. We aim to continue to build out this page to be more comprehensive over time. If you're looking for a general overview of migrating from Ingress, please refer to our [Migrating from Ingress guide](./migrating-from-ingress.md).
+
+We understand that migrations can be complex, and our goal is to provide you with the information and tools you need for a smooth transition.
+
+## Common Questions
+
+### How does Gateway API compare to Ingress?
+
+Gateway API provides a role-oriented and more expressive API than Ingress. Where Ingress combines the concepts of a load balancer and routing rules into a single resource, Gateway API splits them apart:
+
+* **Gateway:** Defines where and how traffic enters the cluster, a task for a cluster operator.
+* **HTTPRoute:** Defines how traffic is routed to services, a task for an application developer.
+
+This separation allows for safer, multi-tenant infrastructure. For a deeper dive, check the [Ingress Migration Guide](./migrating-from-ingress.md).
+
+### How do I map Ingress-NGINX features to Gateway API?
+
+Many annotation-based features in Ingress-NGINX have corresponding fields in Gateway API. For example, traffic splitting, header manipulation, and TLS configuration are all native to the API. For a detailed mapping, we recommend exploring the [Gateway API HTTPRoute documentation](../../../api-types/httproute/) and the documentation of your chosen [implementation](/implementations/).
+
+### Can I try Gateway API without removing Ingress-NGINX?
+
+Yes, and it's highly recommended. You can run a Gateway API controller alongside your existing Ingress-NGINX controller. They will each get a different external IP address, allowing you to test and validate your new configuration in isolation without affecting production traffic.
+
+## Migration Resources
+
+A successful migration requires careful planning. These resources are here to help.
+
+### ingress2gateway
+
+Manually translating complex Ingress rules and annotations is error-prone. The **[ingress2gateway](https://github.com/kubernetes-sigs/ingress2gateway)** tool is designed to automate this process. It reads your existing Ingress resources and converts them into the corresponding Gateway and HTTPRoute resources.
+
+The tool is under active development, with ongoing work to support the most widely-used Ingress-NGINX annotations. We strongly recommend using it as the starting point for your migration.
+
+### Choosing an Implementation
+
+The first step is to select an implementation that fits your needs. Key factors to consider include:
+
+* **Conformance:** Check the [conformance reports](https://gateway-api.sigs.k8s.io/implementations/) to ensure the implementation supports the Gateway API features you require.
+* **Underlying Technology:** Your team's familiarity with a proxy like Envoy, NGINX, or others can influence your choice.
+* **Integration:** Your cloud provider or CNI may already offer an integrated Gateway API implementation.
+
+## Lots in Progress
+
+We've got a lot of work in progress that we hope will help your migration to Gateway API even better in the future. In addition to our ongoing work to improve ingress2gateway and work towards a v1.0 release, we're also planning for the next release of Gateway API (currently targeting February). In that release, we're hoping to graduate the following features to GA:
+
+* TLSRoute
+* ListenerSet
+* HTTPRoute CORS filter
+
+If there are other features that we should be working on, please let us know.
+
+## We're Here to Help
+
+The Gateway API community is committed to making the migration experience as smooth as possible. The `ingress2gateway` tool is a key part of this, and we are actively working to improve its annotation support.
+
+If you have questions, encounter issues, or are missing a feature, please get in touch:
+
+* **File an issue** on the [Gateway API repository](https://github.com/kubernetes-sigs/gateway-api/issues).
+* **Join a community meeting** to discuss your use case.
+* **Provide feedback** on the `ingress2gateway` tool by opening an issue on its [repository](https://github.com/kubernetes-sigs/ingress2gateway/issues).
+
+Your feedback is invaluable in helping us improve the API and the migration tooling for everyone.