Update tutorials to reference 'Getting Started' as prereq

[david-martin]

Replaces #1126

Closes #1093

Other changes:

• Add Gateway creation to some tutorials where before it relied on a Gateway created by a make target
• Add some missing HTTPRoute sectionNames
• Remove make cleanup references
• Some small typos fixed

[jasonmadigan]

👀

[jasonmadigan]

just because this will 404 on GH, maybe we include an absolute link? https://docs.kuadrant.io/latest/getting-started

[jasonmadigan]

(I realise this will 404 too right now until we do our next stable release)

[david-martin]

@jasonmadigan summarising some options discussed offline:

1. Your suggestion above to change link to absolute /latest
2. Similar to above, but use a /dev link
3. Leaving as is, knowing it will 404 on github, but be OK on docs site
4. Move those user guides into the docs repo, so relative links work in github and on docs site

The links 404ing are a symptom of how these docs are being used for the docs site by mkdocs.
The dual target is not ideal, given this limitation around relative links if referencing a doc from another repo.
I'm not keen on having the absolute url as that gets treated as an external url by the mkdocs tooling and potentially bypasses some CI checks (like detecting 404s)

If you're in agreement, how about we go with 3 (as that's already the case potentially for other docs),
with an agreement to investigate 4 as a long term option, at least for these docs in the kuadrant operator site.
I wonder if there's a need to have these docs in this repo as well, if we have them in the docs repo and site, and link to the site from the main README.

[jasonmadigan]

seems like the most pragmatic option to me. can work on 4 longer term.

[jasonmadigan]

w/ helm guide, GW API v1.1 is installed

kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: toystore
  namespace: ${KUADRANT_DEVELOPER_NS}
  labels:
     app: toystore
spec:
  parentRefs:
  - name: ${KUADRANT_GATEWAY_NAME}
    namespace: ${KUADRANT_GATEWAY_NS}
  hostnames:
  - api.toystore.com
  rules:
  - name: rule-1
    matches:
    - method: GET
      path:
        type: PathPrefix
        value: "/cars"
    - method: GET
      path:
        type: PathPrefix
        value: "/dolls"
    backendRefs:
    - name: toystore
      port: 80
  - name: rule-2
    matches:
    - path:
        type: PathPrefix
        value: "/admin"
    backendRefs:                                                                           <....
Error from server (BadRequest): error when creating "STDIN": HTTPRoute in version "v1" cannot be handled as a HTTPRoute: strict decoding error: unknown field "spec.rules[0].name", unknown field "spec.rules[1].name"

[jasonmadigan]

will continue tomorrow

[jasonmadigan]

@david-martin did you install your stack with helm (via the guide on https://artifacthub.io/packages/helm/kuadrant/kuadrant-operator) + cloud-provider-kind ?

[jasonmadigan]

IIRC, named rules are in 1.2[1], I guess this won't work as the helm guide currently installs the v1.1 CRDs

[1] https://kubernetes.io/blog/2024/11/21/gateway-api-v1-2/#new-additions-to-experimental-channel

went without to push forward:

kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: toystore
  namespace: ${KUADRANT_DEVELOPER_NS}
  labels:
     app: toystore
spec:
  parentRefs:
  - name: ${KUADRANT_GATEWAY_NAME}
    namespace: ${KUADRANT_GATEWAY_NS}
  hostnames:
  - api.toystore.com
  rules:
  - matches:
    - method: GET
      path:
        type: PathPrefix
        value: "/cars"
    - method: GET
      path:
        type: PathPrefix
        value: "/dolls"
    backendRefs:
    - name: toystore
      port: 80
  - matches:
    - path:
        type: PathPrefix
        value: "/admin"
    backendRefs:
    - name: toystore
      port: 80
EOF

[david-martin]

I haven't tried the tutorials where I made the updates to add rule names.
I added those as I thought it was an oversight in those guides, given the reference to sectionNames in the Policy examples.
We might have to back out those sectionName references if they won't work with the latest kuadrant release.

[jasonmadigan]

yeah, just looks bad ootb as the helm guide steers you towards 1.1

if we're not highlighting sectionNames, perhaps we don't need right now

[david-martin]

Both the helm install and olm install reference 1.1.0 of the gateway api CRDs.
I've traced back the original author of the guide to look for advice on what to do here.
Turns out this wasn't an oversight and it was written as intended.
Currently in Kuadrant, there are implied rule names when referencing them from a policy

• https://github.com/Kuadrant/policy-machinery/blob/ca213ee94f9b9f35d59d2d8a54a70902d91c8537/machinery/gateway_api_topology.go#L391
  For example, rule-1 means the first rule, and so on.

The reason for this was to support sectionNames in a policy targetRef if gateway api 1.1 is used (which is the case with OSSM support at present on OpenShift).
The plan is to remove this and leverage the experimental feature in gateway api 1.2.

https://github.com/Kuadrant/policy-machinery/blob/ca213ee94f9b9f35d59d2d8a54a70902d91c8537/machinery/gateway_api_types.go#L144

I'll back out the changes

[david-martin]

Updated

[jasonmadigan]

👀 - continuing

[jasonmadigan]

couple of small things that I think we should fixup

[jasonmadigan]

LGTM now