docs: refactor user guides (#2797)

* docs: refactor user guides Signed-off-by: bitliu <[email protected]> * fix: relative paths Signed-off-by: bitliu <[email protected]> --------- Signed-off-by: bitliu <[email protected]>
envoyproxy · Mar 7, 2024 · 10b39e0 · 10b39e0
1 parent ef1934f
commit 10b39e0
Show file tree

Hide file tree

Showing 43 changed files with 98 additions and 75 deletions.
diff --git a/site/content/en/latest/install/api.md b/site/content/en/latest/install/api.md
@@ -1,7 +1,4 @@
-+++
-title = "gateway-helm"
-+++
-
+# gateway-helm
 
 ![Version: v0.0.0-latest](https://img.shields.io/badge/Version-v0.0.0--latest-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: latest](https://img.shields.io/badge/AppVersion-latest-informational?style=flat-square)
 

diff --git a/site/content/en/latest/user/extensibility/_index.md b/site/content/en/latest/user/extensibility/_index.md
@@ -0,0 +1,5 @@
+---
+title: "Extensibility"
+weight: 4
+description: This section includes User Guides of Extensibility.
+---
diff --git a/...tent/en/latest/user/envoy-patch-policy.md → .../user/extensibility/envoy-patch-policy.md b/...tent/en/latest/user/envoy-patch-policy.md → .../user/extensibility/envoy-patch-policy.md
@@ -22,7 +22,7 @@ not exposed by Envoy Gateway APIs today.
 
 ### Prerequisites
 
-* Follow the steps from the [Quickstart](../quickstart) guide to install Envoy Gateway and the example manifest.
+* Follow the steps from the [Quickstart](../../quickstart) guide to install Envoy Gateway and the example manifest.
 Before proceeding, you should be able to query the example backend using HTTP.
 
 ### Enable EnvoyPatchPolicy
@@ -233,8 +233,8 @@ across versions for these reasons
 * Envoy Gateway might alter the xDS translation creating a different xDS output
 such as changing the `name` field of resources.
 
-[EnvoyPatchPolicy]: ../../api/extension_types#envoypatchpolicy
-[EnvoyGateway]: ../../api/extension_types#envoygateway
+[EnvoyPatchPolicy]: ../../../api/extension_types#envoypatchpolicy
+[EnvoyGateway]: ../../../api/extension_types#envoygateway
 [JSON Patch]: https://datatracker.ietf.org/doc/html/rfc6902
 [xDS]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/operations/dynamic_configuration
 [Local Reply Modification]: https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/local_reply

diff --git a/site/content/en/latest/user/observability/_index.md b/site/content/en/latest/user/observability/_index.md
@@ -0,0 +1,5 @@
+---
+title: "Observability"
+weight: 4
+description: This section includes User Guides of Observability.
+---
diff --git a/...ent/en/latest/user/gateway-api-metrics.md → ...user/observability/gateway-api-metrics.md b/...ent/en/latest/user/gateway-api-metrics.md → ...user/observability/gateway-api-metrics.md
@@ -7,7 +7,7 @@ The project also provides example dashboard for visualising the metrics using Gr
 
 ## Prerequisites
 
-Follow the steps from the [Quickstart Guide](../quickstart) to install Envoy Gateway and the example manifest.
+Follow the steps from the [Quickstart Guide](../../quickstart) to install Envoy Gateway and the example manifest.
 Before proceeding, you should be able to query the example backend using HTTP.
 
 Run the following commands to install the metrics stack, with the Gateway API State Metrics configuration, on your kubernetes cluster:

diff --git a/...ent/en/latest/user/grafana-integration.md → ...user/observability/grafana-integration.md b/...ent/en/latest/user/grafana-integration.md → ...user/observability/grafana-integration.md
@@ -7,7 +7,7 @@ This guide shows you how to visualise the metrics exposed to prometheus using gr
 
 ## Prerequisites
 
-Follow the steps from the [Quickstart Guide](../quickstart) to install Envoy Gateway and the example manifest.
+Follow the steps from the [Quickstart Guide](../../quickstart) to install Envoy Gateway and the example manifest.
 Before proceeding, you should be able to query the example backend using HTTP.
 
 Follow the steps from the [Proxy Observability](../proxy-observability#Metrics) to enable prometheus metrics.

diff --git a/...ent/en/latest/user/proxy-observability.md → ...user/observability/proxy-observability.md b/...ent/en/latest/user/proxy-observability.md → ...user/observability/proxy-observability.md
@@ -7,7 +7,7 @@ This guide show you how to config proxy observability, includes metrics, logs, a
 
 ## Prerequisites
 
-Follow the steps from the [Quickstart Guide](../quickstart) to install Envoy Gateway and the example manifest.
+Follow the steps from the [Quickstart Guide](../../quickstart) to install Envoy Gateway and the example manifest.
 Before proceeding, you should be able to query the example backend using HTTP.
 
 [FluentBit](https://fluentbit.io/) is used to collect logs from the EnvoyProxy instances and forward them to Loki. Install FluentBit:

diff --git a/site/content/en/latest/user/operations/_index.md b/site/content/en/latest/user/operations/_index.md
@@ -0,0 +1,5 @@
+---
+title: "Operations"
+weight: 4
+description: This section includes User Guides of Operations.
+---
diff --git a/...nt/en/latest/user/customize-envoyproxy.md → ...t/user/operations/customize-envoyproxy.md b/...nt/en/latest/user/customize-envoyproxy.md → ...t/user/operations/customize-envoyproxy.md
@@ -8,7 +8,7 @@ Service. To learn more about GatewayClass and ParametersRef, please refer to [Ga
 
 ## Installation
 
-Follow the steps from the [Quickstart Guide](../quickstart) to install Envoy Gateway and the example manifest.
+Follow the steps from the [Quickstart Guide](../../quickstart) to install Envoy Gateway and the example manifest.
 Before proceeding, you should be able to query the example backend using HTTP.
 
 ## Add GatewayClass ParametersRef
@@ -368,5 +368,5 @@ EOF
 ```
 
 [Gateway API documentation]: https://gateway-api.sigs.k8s.io/
-[EnvoyProxy]: ../../api/extension_types#envoyproxy
+[EnvoyProxy]: ../../../api/extension_types#envoyproxy
 [egctl translate]: ../egctl/#validating-gateway-api-configuration
diff --git a/...content/en/latest/user/deployment-mode.md → ...latest/user/operations/deployment-mode.md b/...content/en/latest/user/deployment-mode.md → ...latest/user/operations/deployment-mode.md
@@ -410,6 +410,6 @@ Handling connection for 8889
 ```
 
 [GatewayClass]: https://gateway-api.sigs.k8s.io/api-types/gatewayclass/
-[Namespaced deployment mode]: ../../api/extension_types#kuberneteswatchmode
+[Namespaced deployment mode]: ../../../api/extension_types#kuberneteswatchmode
 [issue1231]: https://github.com/envoyproxy/gateway/issues/1231
 [issue1117]: https://github.com/envoyproxy/gateway/issues/1117
diff --git a/site/content/en/latest/user/egctl.md → ...ontent/en/latest/user/operations/egctl.md b/site/content/en/latest/user/egctl.md → ...ontent/en/latest/user/operations/egctl.md
@@ -824,7 +824,7 @@ product     backend   ResolvedRefs   True      ResolvedRefs
 
 
 [Multi-tenancy]: ../deployment-mode#multi-tenancy
-[EnvoyProxy]: ../../api/extension_types#envoyproxy
+[EnvoyProxy]: ../../../api/extension_types#envoyproxy
 
 
 ## egctl experimental dashboard

diff --git a/site/content/en/latest/user/quickstart.md b/site/content/en/latest/user/quickstart.md
@@ -1,6 +1,7 @@
 ---
 title: "Quickstart"
 weight: 1
+description: Get started with Envoy Gateway in a few simple steps.
 ---
 
 This guide will help you get started with Envoy Gateway in a few simple steps.

diff --git a/site/content/en/latest/user/security/_index.md b/site/content/en/latest/user/security/_index.md
@@ -0,0 +1,5 @@
+---
+title: "Security"
+weight: 2
+description: This section includes User Guides of Security.
+---
diff --git a/site/content/en/latest/user/basic-auth.md → ...ent/en/latest/user/security/basic-auth.md b/site/content/en/latest/user/basic-auth.md → ...ent/en/latest/user/security/basic-auth.md
@@ -12,7 +12,7 @@ This instantiated resource can be linked to a [Gateway][Gateway], [HTTPRoute][HT
 
 ## Prerequisites
 
-Follow the steps from the [Quickstart](../quickstart) guide to install Envoy Gateway and the example manifest.
+Follow the steps from the [Quickstart](../../quickstart) guide to install Envoy Gateway and the example manifest.
 Before proceeding, you should be able to query the example backend using HTTP.
 
 ## Configuration
@@ -78,7 +78,7 @@ kubectl get securitypolicy/basic-auth-example -o yaml
 
 ## Testing
 
-Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../quickstart) guide is set. If not, follow the
+Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) guide is set. If not, follow the
 Quickstart instructions to set the variable.
 
 ```shell
@@ -117,7 +117,7 @@ The request should be allowed and you should see the response from the backend s
 
 ## Clean-Up
 
-Follow the steps from the [Quickstart](../quickstart) guide to uninstall Envoy Gateway and the example manifest.
+Follow the steps from the [Quickstart](../../quickstart) guide to uninstall Envoy Gateway and the example manifest.
 
 Delete the SecurityPolicy and the secret
 
@@ -128,9 +128,9 @@ kubectl delete secret/basic-auth
 
 ## Next Steps
 
-Checkout the [Developer Guide](../../contributions/develop/) to get involved in the project.
+Checkout the [Developer Guide](../../../contributions/develop/) to get involved in the project.
 
-[SecurityPolicy]: ../../design/security-policy/
+[SecurityPolicy]: ../../../design/security-policy/
 [http Basic authentication]: https://tools.ietf.org/html/rfc2617
 [Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway
 [HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute

diff --git a/site/content/en/latest/user/cors.md → site/content/en/latest/user/security/cors.md b/site/content/en/latest/user/cors.md → site/content/en/latest/user/security/cors.md
@@ -11,7 +11,7 @@ This instantiated resource can be linked to a [Gateway][Gateway], [HTTPRoute][HT
 
 ## Prerequisites
 
-Follow the steps from the [Quickstart](../quickstart) guide to install Envoy Gateway and the example manifest.
+Follow the steps from the [Quickstart](../../quickstart) guide to install Envoy Gateway and the example manifest.
 Before proceeding, you should be able to query the example backend using HTTP.
 
 ## Configuration
@@ -57,7 +57,7 @@ kubectl get securitypolicy/cors-example -o yaml
 
 ## Testing
 
-Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../quickstart) guide is set. If not, follow the
+Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) guide is set. If not, follow the
 Quickstart instructions to set the variable.
 
 ```shell
@@ -122,7 +122,7 @@ filter to work. Otherwise, the OPTIONS request won't match the routes and the CO
 
 ## Clean-Up
 
-Follow the steps from the [Quickstart](../quickstart) guide to uninstall Envoy Gateway and the example manifest.
+Follow the steps from the [Quickstart](../../quickstart) guide to uninstall Envoy Gateway and the example manifest.
 
 Delete the SecurityPolicy:
 
@@ -132,9 +132,9 @@ kubectl delete securitypolicy/cors-example
 
 ## Next Steps
 
-Checkout the [Developer Guide](../../contributions/develop/) to get involved in the project.
+Checkout the [Developer Guide](../../../contributions/develop/) to get involved in the project.
 
-[SecurityPolicy]: ../../design/security-policy/
+[SecurityPolicy]: ../../../design/security-policy/
 [cors]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
 [Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway
 [HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute

diff --git a/...tent/en/latest/user/jwt-authentication.md → ...atest/user/security/jwt-authentication.md b/...tent/en/latest/user/jwt-authentication.md → ...atest/user/security/jwt-authentication.md
@@ -11,7 +11,7 @@ This instantiated resource can be linked to a [Gateway][Gateway], [HTTPRoute][HT
 
 ## Prerequisites
 
-Follow the steps from the [Quickstart](../quickstart) guide to install Envoy Gateway and the example manifest.
+Follow the steps from the [Quickstart](../../quickstart) guide to install Envoy Gateway and the example manifest.
 For GRPC - follow the steps from the [GRPC Routing](../grpc-routing) example.
 Before proceeding, you should be able to query the example backend using HTTP or GRPC.
 
@@ -71,7 +71,7 @@ kubectl get securitypolicy/jwt-example -o yaml
 
 ## Testing
 
-Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../quickstart) guide is set. If not, follow the
+Ensure the `GATEWAY_HOST` environment variable from the [Quickstart](../../quickstart) guide is set. If not, follow the
 Quickstart instructions to set the variable.
 
 ```shell
@@ -150,7 +150,7 @@ You should see the below response
 
 ## Clean-Up
 
-Follow the steps from the [Quickstart](../quickstart) guide to uninstall Envoy Gateway and the example manifest.
+Follow the steps from the [Quickstart](../../quickstart) guide to uninstall Envoy Gateway and the example manifest.
 
 Delete the SecurityPolicy:
 
@@ -160,9 +160,9 @@ kubectl delete securitypolicy/jwt-example
 
 ## Next Steps
 
-Checkout the [Developer Guide](../../contributions/develop/) to get involved in the project.
+Checkout the [Developer Guide](../../../contributions/develop/) to get involved in the project.
 
-[SecurityPolicy]: ../../design/security-policy/
+[SecurityPolicy]: ../../../design/security-policy/
 [jwt]: https://tools.ietf.org/html/rfc7519
 [jwks]: https://tools.ietf.org/html/rfc7517
 [Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway

diff --git a/site/content/en/latest/user/oidc.md → site/content/en/latest/user/security/oidc.md b/site/content/en/latest/user/oidc.md → site/content/en/latest/user/security/oidc.md
@@ -13,7 +13,7 @@ This instantiated resource can be linked to a [Gateway][Gateway] and [HTTPRoute]
 
 ## Prerequisites
 
-Follow the steps from the [Quickstart](../quickstart) guide to install Envoy Gateway and the example manifest.
+Follow the steps from the [Quickstart](../../quickstart) guide to install Envoy Gateway and the example manifest.
 Before proceeding, you should be able to query the example backend using HTTP.
 
 OIDC authentication requires the redirect URL to be HTTPS. Follow the [Secure Gateways](../secure-gateways) guide
@@ -110,7 +110,7 @@ successfully login, you should see the response from the backend service.
 
 ## Clean-Up
 
-Follow the steps from the [Quickstart](../quickstart) guide to uninstall Envoy Gateway and the example manifest.
+Follow the steps from the [Quickstart](../../quickstart) guide to uninstall Envoy Gateway and the example manifest.
 
 Delete the SecurityPolicy and the secret:
 
@@ -121,10 +121,10 @@ kubectl delete secret/my-app-client-secret
 
 ## Next Steps
 
-Checkout the [Developer Guide](../../contributions/develop/) to get involved in the project.
+Checkout the [Developer Guide](../../../contributions/develop/) to get involved in the project.
 
 [oidc]: https://openid.net/connect/
 [google-oidc]: https://developers.google.com/identity/protocols/oauth2/openid-connect
-[SecurityPolicy]: ../../design/security-policy/
+[SecurityPolicy]: ../../../design/security-policy/
 [Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway
 [HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute
diff --git a/...content/en/latest/user/secure-gateways.md → ...n/latest/user/security/secure-gateways.md b/...content/en/latest/user/secure-gateways.md → ...n/latest/user/security/secure-gateways.md
@@ -11,7 +11,7 @@ testing and demonstration purposes only.
 
 ## Installation
 
-Follow the steps from the [Quickstart Guide](../quickstart) to install Envoy Gateway and the example manifest.
+Follow the steps from the [Quickstart Guide](../../quickstart) to install Envoy Gateway and the example manifest.
 Before proceeding, you should be able to query the example backend using HTTP.
 
 ## TLS Certificates
@@ -242,7 +242,7 @@ Lastly, test connectivity using the above [Testing section](#testing).
 
 ## Clean-Up
 
-Follow the steps from the [Quickstart Guide](../quickstart) to uninstall Envoy Gateway and the example manifest.
+Follow the steps from the [Quickstart Guide](../../quickstart) to uninstall Envoy Gateway and the example manifest.
 
 Delete the Secrets:
 
@@ -257,7 +257,7 @@ This section gives a walkthrough to generate RSA and ECDSA derived certificates
 
 ## Prerequisites
 
-Follow the steps from the [Quickstart Guide](../quickstart) to install Envoy Gateway and the example manifest.
+Follow the steps from the [Quickstart Guide](../../quickstart) to install Envoy Gateway and the example manifest.
 Before proceeding, you should be able to query the example backend using HTTP.
 
 Follow the steps in the [TLS Certificates](../secure-gateways#tls-certificates) section in the guide to generate self-signed RSA derived Server certificate and private key, and configure those in the Gateway listener configuration to terminate HTTPS traffic.
@@ -369,7 +369,7 @@ This sections gives a walkthrough to generate multiple certificates correspondin
 
 ## Prerequisites
 
-Follow the steps from the [Quickstart Guide](../quickstart) to install Envoy Gateway and the example manifest.
+Follow the steps from the [Quickstart Guide](../../quickstart) to install Envoy Gateway and the example manifest.
 Before proceeding, you should be able to query the example backend using HTTP.
 
 Follow the steps in the [TLS Certificates](../secure-gateways#tls-certificates) section in the guide to generate self-signed RSA derived Server certificate and private key, and configure those in the Gateway listener configuration to terminate HTTPS traffic.
@@ -450,6 +450,6 @@ Refer to the steps mentioned earlier in the guide under [Testing in clusters wit
 
 ## Next Steps
 
-Checkout the [Developer Guide](../../contributions/develop/) to get involved in the project.
+Checkout the [Developer Guide](../../../contributions/develop/) to get involved in the project.
 
 [ReferenceGrant]: https://gateway-api.sigs.k8s.io/api-types/referencegrant/
diff --git a/...ontent/en/latest/user/tls-cert-manager.md → .../latest/user/security/tls-cert-manager.md b/...ontent/en/latest/user/tls-cert-manager.md → .../latest/user/security/tls-cert-manager.md
@@ -18,7 +18,7 @@ Changing to the Let's Encrypt production environment is straight-forward after t
 
 ## Installation
 
-Follow the steps from the [Quickstart Guide](../quickstart) to install Envoy Gateway and the example manifest.
+Follow the steps from the [Quickstart Guide](../../quickstart) to install Envoy Gateway and the example manifest.
 Before proceeding, you should be able to query the example backend using HTTP.
 
 ## Deploying cert-manager

diff --git a/...content/en/latest/user/tls-passthrough.md → ...n/latest/user/security/tls-passthrough.md b/...content/en/latest/user/tls-passthrough.md → ...n/latest/user/security/tls-passthrough.md
@@ -12,7 +12,7 @@ to terminate the TLS connection, while the Gateway routes the requests to the ap
 
 ## Installation
 
-Follow the steps from the [Quickstart Guide](../quickstart) to install Envoy Gateway and the example manifest.
+Follow the steps from the [Quickstart Guide](../../quickstart) to install Envoy Gateway and the example manifest.
 Before proceeding, you should be able to query the example backend using HTTP.
 
 ## TLS Certificates
@@ -106,7 +106,7 @@ curl -v -HHost:passthrough.example.com --resolve "passthrough.example.com:6443:$
 
 ## Clean-Up
 
-Follow the steps from the [Quickstart Guide](../quickstart) to uninstall Envoy Gateway and the example manifest.
+Follow the steps from the [Quickstart Guide](../../quickstart) to uninstall Envoy Gateway and the example manifest.
 
 Delete the Secret:
 
@@ -116,4 +116,4 @@ kubectl delete secret/server-certs
 
 ## Next Steps
 
-Checkout the [Developer Guide](../../contributions/develop/) to get involved in the project.
+Checkout the [Developer Guide](../../../contributions/develop/) to get involved in the project.
diff --git a/...content/en/latest/user/tls-termination.md → ...n/latest/user/security/tls-termination.md b/...content/en/latest/user/tls-termination.md → ...n/latest/user/security/tls-termination.md
@@ -10,7 +10,7 @@ This guide will walk through the steps required to configure TLS Terminate mode
 
 ## Installation
 
-Follow the steps from the [Quickstart Guide](../quickstart) to install Envoy Gateway.
+Follow the steps from the [Quickstart Guide](../../quickstart) to install Envoy Gateway.
 
 ## TLS Certificates
 Generate the certificates and keys used by the Gateway to terminate client TLS connections.

diff --git a/site/content/en/latest/user/traffic/_index.md b/site/content/en/latest/user/traffic/_index.md
@@ -0,0 +1,5 @@
+---
+title: "Traffic"
+weight: 1
+description: This section includes User Guides of Traffic Management.
+---
diff --git a/...content/en/latest/user/circuit-breaker.md → ...en/latest/user/traffic/circuit-breaker.md b/...content/en/latest/user/circuit-breaker.md → ...en/latest/user/traffic/circuit-breaker.md
@@ -20,7 +20,7 @@ This instantiated resource can be linked to a [Gateway][], [HTTPRoute][] or [GRP
 
 ### Install Envoy Gateway
 
-* Follow the installation step from the [Quickstart Guide](../quickstart) to install Envoy Gateway and sample resources.
+* Follow the installation step from the [Quickstart Guide](../../quickstart) to install Envoy Gateway and sample resources.
 
 ### Install the hey load testing tool
 * The `hey` CLI will be used to generate load and measure response times. Follow the installation instruction from the [Hey project] docs.   
@@ -116,7 +116,7 @@ With the new circuit breaker settings, and due to the slowness of the backend, o
 * Upstream traffic was limited, alleviating the pressure on the degraded service. 
 
 [Envoy Circuit Breakers]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/circuit_breaking
-[BackendTrafficPolicy]: ../../api/extension_types#backendtrafficpolicy
+[BackendTrafficPolicy]: ../../../api/extension_types#backendtrafficpolicy
 [Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway/
 [HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute/
 [GRPCRoute]: https://gateway-api.sigs.k8s.io/api-types/grpcroute/

diff --git a/...t/en/latest/user/client-traffic-policy.md → ...est/user/traffic/client-traffic-policy.md b/...t/en/latest/user/client-traffic-policy.md → ...est/user/traffic/client-traffic-policy.md
@@ -18,7 +18,7 @@ This API was added as a new policy attachment resource that can be applied to Ga
 
 ### Prerequisites
 
-* Follow the steps from the [Quickstart](../quickstart) guide to install Envoy Gateway and the example manifest.
+* Follow the steps from the [Quickstart](../../quickstart) guide to install Envoy Gateway and the example manifest.
 Before proceeding, you should be able to query the example backend using HTTP.
 
 ### Support TCP keepalive for downstream client
@@ -464,5 +464,5 @@ curl -v http://$GATEWAY_HOST/get \
 request timeout
 ```
 
-[ClientTrafficPolicy]: ../../api/extension_types#clienttrafficpolicy
-[BackendTrafficPolicy]: ../../api/extension_types#backendtrafficpolicy
+[ClientTrafficPolicy]: ../../../api/extension_types#clienttrafficpolicy
+[BackendTrafficPolicy]: ../../../api/extension_types#backendtrafficpolicy