Skip to content

docs: ensure example files reference proper pages + update API version - #4840

Merged
k8s-ci-robot merged 4 commits into
kubernetes-sigs:mainfrom
JoeyC-Dev:refFix
May 18, 2026
Merged

k8s-ci-robot merged 4 commits into
kubernetes-sigs:mainfrom
JoeyC-Dev:refFix

Conversation

@JoeyC-Dev

@JoeyC-Dev JoeyC-Dev commented May 11, 2026 •

Copy link
Copy Markdown
Contributor

What type of PR is this?

/kind documentation

What this PR does / why we need it:

  • Fix outdated/missing reference in YAML examples.
  • Update API version from v1beta1 to v1.

Note: technically, if this commit does not add any reference lines to the existing example YAML files, then those example YAML files are not referenced by any files. I already added/fixed all example YAML files that are quoted by a file.

Files With No References:

- examples/experimental/destination-port-matching-tcp.yaml
- examples/experimental/http-response-header.yaml
- examples/experimental/v1alpha2/tls-routing/gateway.yaml
- examples/experimental/v1alpha2/tls-routing/tls-route.yaml
- examples/experimental/v1alpha3/tls-routing/gateway.yaml
- examples/experimental/v1alpha3/tls-routing/tls-route.yaml
- examples/standard/0-namespaces.yaml
- examples/standard/default-match-http.yaml
- examples/standard/gateway-addresses.yaml
- examples/standard/http-redirect-path.yaml
- examples/standard/http-redirect.yaml
- examples/standard/http-request-header-remove.yaml
- examples/standard/http-request-header-set.yaml
- examples/standard/http-rewrite.yaml
- examples/standard/httproute.yaml
- examples/standard/multicluster/0-namespaces.yaml

Which issue(s) this PR fixes:

N/A

Does this PR introduce a user-facing change?:

NONE

Signed-off-by: Joey Chen <142381267+JoeyC-Dev@users.noreply.github.com>
@k8s-ci-robot k8s-ci-robot added release-note-none Denotes a PR that doesn't merit a release note. kind/documentation Categorizes issue or PR as related to documentation. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels May 11, 2026
@k8s-ci-robot

Copy link
Copy Markdown
Contributor

Hi @JoeyC-Dev. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Tip

We noticed you've done this a few times! Consider joining the org to skip this step and gain /lgtm and other bot rights. We recommend asking approvers on your previous PRs to sponsor you.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

@k8s-ci-robot
k8s-ci-robot requested review from aojea and rikatz May 11, 2026 03:08
@rikatz

rikatz commented May 11, 2026

Copy link
Copy Markdown
Member

@JoeyC-Dev we are going to move to docsy/hugo sooner this week, I would like to wait that PR to merge and then we fix this one, sounds good?

Thanks for the work here, I appreciate the help and improvements!

@JoeyC-Dev

Copy link
Copy Markdown
Contributor Author

@rikatz Good to know. I’ll check back on this PR next week and see what I can do then.

@rikatz

rikatz commented May 15, 2026

Copy link
Copy Markdown
Member

hugo/docsy is merged, go ahead. You will probably need to rebase and re-verify things

JoeyC-Dev added 2 commits May 17, 2026 12:03
- Use content-relative doc paths instead of legacy `site-src/` paths or full `site/content/en` paths.

Signed-off-by: Joey Chen <142381267+JoeyC-Dev@users.noreply.github.com>
@k8s-ci-robot k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels May 17, 2026
Signed-off-by: Joey Chen <142381267+JoeyC-Dev@users.noreply.github.com>
@k8s-ci-robot k8s-ci-robot added do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. kind/gep PRs related to Gateway Enhancement Proposal(GEP) labels May 17, 2026
@JoeyC-Dev JoeyC-Dev changed the title docs: ensure example files reference proper guide and API docs pages docs: ensure example files reference proper pages + update API version May 17, 2026
@JoeyC-Dev

JoeyC-Dev commented May 17, 2026 •

Copy link
Copy Markdown
Contributor Author

@rikatz I’ve updated the example files with the latest references. Full report below:
Summary

  Markdown files scanned: 134
  Example YAML files scanned: 84
  Referenced examples: 68
  Files needing attention: 0
  Files with no references: 16

Reference List

Details
- examples/experimental/basic-tcp.yaml
    guides/user-guides/tcp.md
- examples/experimental/http-route-rule-name.yaml
    reference/api-types/httproute.md
- examples/experimental/http-route-timeouts/timeout-example.yaml
    reference/api-types/httproute.md
- examples/standard/backend-tls.yaml
    guides/user-guides/tls.md
- examples/standard/backendtlspolicy/backendtlspolicy-ca-certs.yaml
    guides/user-guides/tls.md
- examples/standard/backendtlspolicy/backendtlspolicy-system-certs.yaml
    guides/user-guides/tls.md
- examples/standard/basic-grpc.yaml
    reference/api-types/grpcroute.md
- examples/standard/basic-http.yaml
    reference/api-types/httproute.md
- examples/standard/cross-namespace-routing/0-namespaces.yaml
    guides/user-guides/multiple-ns.md
- examples/standard/cross-namespace-routing/gateway.yaml
    guides/user-guides/multiple-ns.md
- examples/standard/cross-namespace-routing/site-route.yaml
    guides/user-guides/multiple-ns.md
- examples/standard/cross-namespace-routing/store-route.yaml
    guides/user-guides/multiple-ns.md
- examples/standard/frontend-cert-validation.yaml
    guides/user-guides/tls.md
- examples/standard/grpc-filter.yaml
    reference/api-types/grpcroute.md
- examples/standard/grpc-routing/bar-grpcroute.yaml
    guides/user-guides/grpc-routing.md
- examples/standard/grpc-routing/foo-grpcroute.yaml
    guides/user-guides/grpc-routing.md
- examples/standard/grpc-routing/gateway.yaml
    guides/user-guides/grpc-routing.md
- examples/standard/grpc-routing/reflection-grpcroute.yaml
    guides/user-guides/grpc-routing.md
- examples/standard/http-cors/httproute-all-fields-set.yaml
    guides/user-guides/http-cors.md
- examples/standard/http-cors/httproute-all-origins-no-creds.yaml
    guides/user-guides/http-cors.md
- examples/standard/http-cors/httproute-credentials-true.yaml
    guides/user-guides/http-cors.md
- examples/standard/http-cors/httproute-origins-with-wildcards-no-creds.yaml
    guides/user-guides/http-cors.md
- examples/standard/http-cors/httproute-specific-origin-no-creds.yaml
    guides/user-guides/http-cors.md
- examples/standard/http-filter.yaml
    reference/api-types/httproute.md
- examples/standard/http-redirect-rewrite/gateway-redirect-http-https.yaml
    guides/user-guides/http-redirect-rewrite.md
- examples/standard/http-redirect-rewrite/httproute-redirect-303.yaml
    guides/user-guides/http-redirect-rewrite.md
- examples/standard/http-redirect-rewrite/httproute-redirect-307.yaml
    guides/user-guides/http-redirect-rewrite.md
- examples/standard/http-redirect-rewrite/httproute-redirect-308.yaml
    guides/user-guides/http-redirect-rewrite.md
- examples/standard/http-redirect-rewrite/httproute-redirect-full.yaml
    guides/user-guides/http-redirect-rewrite.md
- examples/standard/http-redirect-rewrite/httproute-redirect-http.yaml
    guides/user-guides/http-redirect-rewrite.md
- examples/standard/http-redirect-rewrite/httproute-redirect-https.yaml
    guides/user-guides/http-redirect-rewrite.md
- examples/standard/http-redirect-rewrite/httproute-redirect-prefix.yaml
    guides/user-guides/http-redirect-rewrite.md
- examples/standard/http-redirect-rewrite/httproute-rewrite-full-path.yaml
    guides/user-guides/http-redirect-rewrite.md
- examples/standard/http-redirect-rewrite/httproute-rewrite-prefix-path.yaml
    guides/user-guides/http-redirect-rewrite.md
- examples/standard/http-redirect-rewrite/httproute-rewrite.yaml
    guides/user-guides/http-redirect-rewrite.md
- examples/standard/http-request-header-add.yaml
    guides/user-guides/http-header-modifier.md
- examples/standard/http-request-mirroring/httproute-mirroring.yaml
    guides/user-guides/http-request-mirroring.md
- examples/standard/http-route-attachment/gateway-namespaces.yaml
    docs/concepts/api-overview.md
- examples/standard/http-route-attachment/gateway-strict.yaml
    docs/concepts/api-overview.md
- examples/standard/http-route-attachment/httproute.yaml
    docs/concepts/api-overview.md
- examples/standard/http-routing/bar-httproute.yaml
    guides/user-guides/http-routing.md
- examples/standard/http-routing/foo-httproute.yaml
    guides/user-guides/http-routing.md
- examples/standard/http-routing/gateway.yaml
    guides/user-guides/http-routing.md
- examples/standard/listenerset/listenerset.yaml
    guides/user-guides/listener-set.md
- examples/standard/multicluster/httproute-gamma.yaml
    geps/gep-1748/index.md
- examples/standard/multicluster/httproute-hybrid.yaml
    geps/gep-1748/index.md
- examples/standard/multicluster/httproute-location.yaml
    geps/gep-1748/index.md
- examples/standard/multicluster/httproute-method.yaml
    geps/gep-1748/index.md
- examples/standard/multicluster/httproute-referencegrant.yaml
    geps/gep-1748/index.md
- examples/standard/multicluster/httproute-simple.yaml
    geps/gep-1748/index.md
- examples/standard/reference-grant.yaml
    docs/concepts/security.md
- examples/standard/simple-gateway/gateway.yaml
    guides/getting-started/simple-gateway.md
    guides/user-guides/traffic-splitting.md
- examples/standard/simple-gateway/httproute.yaml
    guides/getting-started/simple-gateway.md
- examples/standard/simple-http-https/bar-route.yaml
    guides/getting-started/migrating-from-ingress.md
- examples/standard/simple-http-https/foo-route.yaml
    guides/getting-started/migrating-from-ingress.md
- examples/standard/simple-http-https/gateway.yaml
    guides/getting-started/migrating-from-ingress.md
- examples/standard/simple-http-https/tls-redirect-route.yaml
    guides/getting-started/migrating-from-ingress.md
- examples/standard/tls-basic.yaml
    guides/user-guides/tls.md
- examples/standard/tls-cert-cross-namespace.yaml
    guides/user-guides/tls.md
- examples/standard/tls-routing/gateway.yaml
    guides/user-guides/tls-routing.md
    reference/api-types/tlsroute.md
- examples/standard/tls-routing/tls-route-terminate.yaml
    guides/user-guides/tls-routing.md
- examples/standard/tls-routing/tls-route.yaml
    guides/user-guides/tls-routing.md
    reference/api-types/tlsroute.md
- examples/standard/traffic-splitting/grpc-traffic-split-2.yaml
    reference/api-types/grpcroute.md
- examples/standard/traffic-splitting/simple-split.yaml
    guides/user-guides/traffic-splitting.md
- examples/standard/traffic-splitting/traffic-split-1.yaml
    guides/user-guides/traffic-splitting.md
- examples/standard/traffic-splitting/traffic-split-2.yaml
    guides/user-guides/traffic-splitting.md
    reference/api-types/httproute.md
- examples/standard/traffic-splitting/traffic-split-3.yaml
    guides/user-guides/traffic-splitting.md
- examples/standard/wildcard-tls-gateway.yaml
    guides/user-guides/tls.md

Files Needing Attention
None

Files With No References

- examples/experimental/destination-port-matching-tcp.yaml
- examples/experimental/http-response-header.yaml
- examples/experimental/v1alpha2/tls-routing/gateway.yaml
- examples/experimental/v1alpha2/tls-routing/tls-route.yaml
- examples/experimental/v1alpha3/tls-routing/gateway.yaml
- examples/experimental/v1alpha3/tls-routing/tls-route.yaml
- examples/standard/0-namespaces.yaml
- examples/standard/default-match-http.yaml
- examples/standard/gateway-addresses.yaml
- examples/standard/http-redirect-path.yaml
- examples/standard/http-redirect.yaml
- examples/standard/http-request-header-remove.yaml
- examples/standard/http-request-header-set.yaml
- examples/standard/http-rewrite.yaml
- examples/standard/httproute.yaml
- examples/standard/multicluster/0-namespaces.yaml

Note that the /site/content/en path prefix is truncated from the results.


I also updated some GEP files that still referenced the old v1beta1. This continues the unfinished work in #4796 (comment).


I checked one of the YAML file (examples/standard/0-namespaces.yaml) with no reference, and found it was added with GPE-746, but never being referenced by any page: a6f1fa8

I also checked examples/standard/default-match-http.yaml, this file can be tracked to 5da5d55 (but disconnected in git history because it was deleted and re-added instead of moved)
The direct relationship is GEP‑3965, but I can’t find a place to insert it, so I’m unsure whether it should be added.

Anyway, the YAML files have no references are for another PR to resolve.


I'm also concerned that adding a GitHub workflow to validate these YAML files will likely fail if the theme changes in the future (like recent Docsy change). So not sure if going to make such workflow.

@rikatz

rikatz commented May 18, 2026

Copy link
Copy Markdown
Member

/ok-to-test

@k8s-ci-robot k8s-ci-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels May 18, 2026
@rikatz

rikatz commented May 18, 2026

Copy link
Copy Markdown
Member

/lgtm
/approve
thanks @JoeyC-Dev !

@rikatz

rikatz commented May 18, 2026

Copy link
Copy Markdown
Member

/hold cancel

@k8s-ci-robot k8s-ci-robot added lgtm "Looks good to me", indicates that a PR is ready to be merged. and removed do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. labels May 18, 2026
@k8s-ci-robot

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: JoeyC-Dev, rikatz

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@k8s-ci-robot k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label May 18, 2026
@k8s-ci-robot
k8s-ci-robot merged commit 6bb2275 into kubernetes-sigs:main May 18, 2026
79 of 80 checks passed
@JoeyC-Dev
JoeyC-Dev deleted the refFix branch May 18, 2026 15:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. kind/documentation Categorizes issue or PR as related to documentation. kind/gep PRs related to Gateway Enhancement Proposal(GEP) lgtm "Looks good to me", indicates that a PR is ready to be merged. ok-to-test Indicates a non-member PR verified by an org member that is safe to test. release-note-none Denotes a PR that doesn't merit a release note. size/L Denotes a PR that changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants