search

nginxinc / nginx-gateway-fabric

NGINX Gateway Fabric provides an implementation for the Gateway API using NGINX as the data plane.
Apache License 2.0
498 stars 96 forks source link

NGINX Gateway Fabric Docs Not Very Easy To Follow #2350

Closed conradwt closed 1 week ago

conradwt commented 2 months ago

When attempting to install the Nginx implementation K8s Gateway API (i.e. Nginx Gateway Fabric), I found the documentation hard to follow because I had to jump from one page of the site to another. Thus, it wasn't clear as to what I was installing here. In the documentation, there should be a quick start that provides an end-to-end example of how to install and use Nginx's K8s Gateway API features. For example, here's a possible Getting Started outline for local development:

  1. create the cluster
  2. install MetalLB
  3. install the Gateway CRDs
  4. create the Gateway and Gateway resources
  5. install Nginx Gateway Fabric
  6. deploy a sample service
  7. create HTTPRoute for our deployed service
  8. test the routing rule
  9. and so on

BTW, the steps were inspired by both the Kong and Traefik K8s Gateway API implementations. Furthermore, I put together a document for using the Kong implementation that can be found here:

sjberman commented 2 months ago

@conradwt Thanks for the feedback. We're always looking to improve the flow of our documentation, and will have some improvements in our upcoming release.

For now, the simplest path I can see to meet your requirements of local development would be to follow:

We also have a developer guide in our Github repo: https://github.com/nginxinc/nginx-gateway-fabric/blob/main/docs/developer/quickstart.md#deploy-on-kind that helps with a basic setup and links to some example apps/routes.

mpstefan commented 1 month ago

Modifying the original ask by a bit, we should definitely produce a complete on-boarding journey. Here's the resulting story:

As a new user to NGF I want a guide that gets me started using the project as quickly as possible So that I do not get stuck on my path to install NGF And so that trying out NGF does not take an excessive amount of time.

Acceptance

ADubhlaoich commented 4 weeks ago

I've started work on this! I will link a draft PR once it's gotten to an appropriate state.

ADubhlaoich commented 2 weeks ago

Image

I have what I anticipate is most of the finer details on initial set-up finished: I've condensed the existing kind set-up guide down to its essential information. There's a lot of noise around conditional configuration in the Helm installation page, so I've taken the minimum steps necessary with the one "peripheral" path being the changes needed for experimental features.

The remaining sections are for setting up an example application, configuring a HTTPRoute and testing everything works. I have not accounted for if the reader wants to use NGINX Plus in this particular guide: I think there's improvements to existing documents that could facilitate that instead, and it isn't a core use case for someone trying to see how NGINX Gateway Fabric works.

ADubhlaoich commented 1 week ago

I will be putting up a draft PR to resolve this issue tomorrow.

With a lot of help from @sjberman I managed to combine the existing kind tutorial, Helm installation and the cafe example into a single document.

It has been (thoroughly) tested, so I need to clean up the explanatory text and add some contextual notes.