Improve Quickstart Guide

[danehans]

This doc contains several steps to run kgateway. This is daunting and error-prone for a first-time user. The quickstart is the "standard" install and not a "quickstart" install and should be renamed accordingly. The project should add a "quickstart" install option that contains:

• Two deps (kubectl and a k8s cluster)
• A single command to deploy an example environment: kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/quickstart.yaml.
• quickstart.yaml should contain all the k8s resources required to tests e2e functionality.
• A step to clean up, e.g. kubectl delete -f
• Next steps with a link to the "standard" install guide

cc: @artberger @timflannagan @npolshakova

[craigbox]

I can help with the docs side of this, if there's someone who can make whatever changes to the packaging as required to make it possible.

[timflannagan]

@craigbox that would be awesome. re:where to make changes, https://github.com/kgateway-dev/kgateway/blob/main/.goreleaser.yaml#L155-L197 is the source of truth here.

[craigbox]

/assign

(is that a thing?)

[timflannagan]

Haha unfortunately not. cc @jenshu @lgadban anyone have the perms to assign craig?

[artberger]

kgateway-dev/kgateway.dev#48

[craigbox]

Here's my "friction log" for the new Quickstart guide. It's a stream of consciousness doc as I went through the page.
I know all this is in flux, but it might help explain a few things as we do a giant s/gloo/kgateway in the docs. It may or may not warrant turning into issues.

kubectl apply --kustomize "https://github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=v1.2.1"

• Why am I using –kustomize?
• Why am I installing 1.21? (This appears hard coded in the page)
• Do I need experimental channel?

helm install --create-namespace --namespace kgateway-system --version v2.0.0-main kgateway oci://ghcr.io/kgateway-dev/charts/kgateway
Pulled: ghcr.io/kgateway-dev/charts/kgateway:v2.0.0-main
Digest: sha256:a8487018a16189edc2c92d6c9d13922b052d3151b9a069944f959a7a762bbeaf
NAME: kgateway
LAST DEPLOYED: Fri Feb 14 13:28:56 2025
NAMESPACE: kgateway-system
STATUS: deployed
REVISION: 1
TEST SUITE: None

Needs a text file output here which says what to do next. "Congratulations, you've installed kgateway! Go here for more information" etc

kubectl create ns httpbin
kubectl -n httpbin apply -f https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/policy-demo/httpbin.yaml

should we have our own httpbin sample? Should we use https://github.com/istio/istio/blob/master/samples/httpbin/httpbin.yaml? Rev the container version? Why are we including 'hey'?

The next steps listed are “Set up a listener”, with a llink to https://kgateway.dev/docs/setup/listeners/. That page doesn't tell me what a listener is. I click HTTP, it says “If you followed the Get started guide, you already have a gateway named http in the gloo-system namespace of your cluster.”

I have a gateway called kgateway in the kgateway-system namespace, and I still don’t know what a listener is or if I have one. This is also very underdocumented on the Gateway API site.

[artberger]

Hey @craigbox thanks so much for capturing these notes. I have another PR open that addresses these, amongst other things: kgateway-dev/kgateway.dev#51

• Updates the Kubernetes Gateway CR install command and uses a shortcode for the version going forward
• Updates the httpbin sample app to use the one in the kgateway repo
• Adds a little more info to the listener pages
• Clarifies on the GS that you don't have a gateway yet, just the control plane

[craigbox]

Is this format of feedback useful? I can make much more of it if so