Repository: envoyproxy/gateway

Issue:
docs: Show GatewayAPI APIs in EG docs
*Description*:
>Describe the issue.

Currently the API reference only shows Envoy Gateway extensions https://gateway.envoyproxy.io/latest/api/

We should also show Gateway API reference within Envoy Gateway to provide a better experience https://gateway-api.sigs.k8s.io/reference/spec/


[optional *Relevant Links*:]
>Any extra documentation required to understand the issue.


Hints from issue comments:
@arkodg: @zirain @Xunzhuo thoughts on the best way to do this ?
lets copy these over from upstream https://github.com/kubernetes-sigs/gateway-api/tree/main/site-src/api-types into https://github.com/envoyproxy/gateway/tree/main/site/content/en/latest/api ? @zirain: that make sense@Xunzhuo: When should we update the copied files? Each time we bump the gwapi version ?@arkodg: @Xunzhuo we could add the new make target that does the fetch + copy and add it into existing docs pipeline
and we can use the go mod version when fetching, so it will ideally only change when we bump gwapi version@Xunzhuo: Yep, let me add it.@github-actions: This issue has been automatically marked as stale because it has not had activity in the last 30 days.@shawnh2: Seems we can do something as in https://github.com/envoyproxy/gateway/pull/3416, to link the GW-API type to relevant field.@github-actions: This issue has been automatically marked as stale because it has not had activity in the last 30 days.@StevenACoffman: /unstaleify@github-actions: This issue has been automatically marked as stale because it has not had activity in the last 30 days.@arkodg: hey @zirain can you hep with this one ?@zirain: wait for upstream: https://github.com/kubernetes-sigs/gateway-api/pull/3204@github-actions: This issue has been automatically marked as stale because it has not had activity in the last 30 days.@arkodg: @zirain looks like 3204 is probably not going to land anytime soon
can we generate https://github.com/kubernetes-sigs/gateway-api/blob/main/site-src/reference/spec.md as part of docs CI and save the content with `make generate` . It will only change when gateway-api versions change@github-actions: This issue has been automatically marked as stale because it has not had activity in the last 30 days.@github-actions: This issue has been automatically marked as stale because it has not had activity in the last 30 days.@StevenACoffman: Awww, modifying the milestone doesn't count as non-stale?@arkodg: @zirain it looks like upstream is not moving to elastic's crd-ref-docs, what's the alternative here@zirain: I have no idea now.@github-actions: This issue has been automatically marked as stale because it has not had activity in the last 30 days.@StevenACoffman: Post-Holiday un-stale bump.@github-actions: This issue has been automatically marked as stale because it has not had activity in the last 30 days.

Solution patch:
diff --git a/site/static/img/envoy-gateway-resources-overview.png b/site/static/img/envoy-gateway-resources-overview.png
new file mode 100644
index 000000000..d42ac01e2
Binary files /dev/null and b/site/static/img/envoy-gateway-resources-overview.png differ


Test patch:
diff --git a/site/content/en/latest/concepts/_index.md b/site/content/en/latest/concepts/_index.md
new file mode 100644
index 000000000..4d568bd44
--- /dev/null
+++ b/site/content/en/latest/concepts/_index.md
@@ -0,0 +1,5 @@
+---
+title: "Concepts"
+weight: 1
+description: Learn about key concepts when working with Envoy Gateway
+---
diff --git a/site/content/en/latest/concepts/concepts_overview.md b/site/content/en/latest/concepts/concepts_overview.md
new file mode 100644
index 000000000..31838b520
--- /dev/null
+++ b/site/content/en/latest/concepts/concepts_overview.md
@@ -0,0 +1,54 @@
++++
+title = "Envoy Gateway Resources"
++++
+
+There are several resources that play a part in enabling you to meet your Kubernetes ingress traffic handling needs. This page provides a brief overview of the resources you’ll be working with.
+
+## Overview
+
+![](/img/envoy-gateway-resources-overview.png)
+
+There are several resources that play a part in enabling you to meet your Kubernetes ingress traffic handling needs. This page provides a brief overview of the resources you’ll be working with.
+
+# Overview
+
+## Kubernetes Gateway API Resources
+- **GatewayClass:** Defines a class of Gateways with common configuration.
+- **Gateway:** Specifies how traffic can enter the cluster.
+- **Routes:** **HTTPRoute, GRPCRoute, TLSRoute, TCPRoute, UDPRoute:** Define routing rules for different types of traffic.
+## Envoy Gateway (EG) API Resources
+- **EnvoyProxy:** Represents the deployment and configuration of the Envoy proxy within a Kubernetes cluster, managing its lifecycle and settings.
+- **EnvoyPatchPolicy, ClientTrafficPolicy, SecurityPolicy, BackendTrafficPolicy, EnvoyExtensionPolicy, BackendTLSPolicy:** Additional policies and configurations specific to Envoy Gateway.
+- **Backend:** A resource that makes routing to cluster-external backends easier and makes access to external processes via Unix Domain Sockets possible.
+
+| Resource                                                                | API         | Required | Purpose            | References             | Description                                                                                                                                                                                                 |
+| ----------------------------------------------------------------------- | ----------- | -------- | ------------------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [GatewayClass][1]                                                       | Gateway API | Yes      | Gateway Config     | Core                   | Defines a class of Gateways with common configuration.                                                                                                                                                      |
+| [Gateway][2]                                                            | Gateway API | Yes      | Gateway Config     | GatewayClass           | Specifies how traffic can enter the cluster.                                                                                                                                                                |
+| [HTTPRoute][3] [GRPCRoute][4] [TLSRoute][5] [TCPRoute][6] [UDPRoute][7] | Gateway API | Yes      | Routing            | Gateway                | Define routing rules for different types of traffic. **Note:**_For simplicity these resources are referenced collectively as Route in the References column_                                                |
+| [Backend][8]                                                            | EG API      | No       | Routing            | N/A                    | Used for routing to cluster-external backends using FQDN or IP. Can also be used when you want to extend Envoy with external processes accessed via Unix Domain Sockets.                                    |
+| [ClientTrafficPolicy][9]                                                | EG API      | No       | Traffic Handling   | Gateway                | Specifies policies for handling client traffic, including rate limiting, retries, and other client-specific configurations.                                                                                 |
+| [BackendTrafficPolicy][10]                                              | EG API      | No       | Traffic Handling   | Gateway Route          | Specifies policies for traffic directed towards backend services, including load balancing, health checks, and failover strategies. **Note:**_Most specific configuration wins_                             |
+| [SecurityPolicy][11]                                                    | EG API      | No       | Security           | Gateway Route          | Defines security-related policies such as authentication, authorization, and encryption settings for traffic handled by Envoy Gateway. **Note:**_Most specific configuration wins_                          |
+| [BackendTLSPolicy][12]                                                  | Gateway API | No       | Security           | Service                | Defines TLS settings for backend connections, including certificate management, TLS version settings, and other security configurations. This policy is applied to Kubernetes Services.                     |
+| [EnvoyProxy][13]                                                        | EG API      | No       | Customize & Extend | GatewayClass Gateway   | The EnvoyProxy resource represents the deployment and configuration of the Envoy proxy itself within a Kubernetes cluster, managing its lifecycle and settings. **Note:**_Most specific configuration wins_ |
+| [EnvoyPatchPolicy][14]                                                  | EG API      | No       | Customize & Extend | GatewayClass Gateway   | This policy defines custom patches to be applied to Envoy Gateway resources, allowing users to tailor the configuration to their specific needs. **Note:**_Most specific configuration wins_                |
+| [EnvoyExtensionPolicy][15]                                              | EG API      | No       | Customize & Extend | Gateway Route, Backend | Allows for the configuration of Envoy proxy extensions, enabling custom behavior and functionality. **Note:**_Most specific configuration wins_                                                             |
+
+
+
+[1]:	https://gateway-api.sigs.k8s.io/api-types/gatewayclass/
+[2]:	https://gateway-api.sigs.k8s.io/api-types/gateway/
+[3]:	https://gateway-api.sigs.k8s.io/api-types/httproute/
+[4]:	https://gateway-api.sigs.k8s.io/api-types/grpcroute/
+[5]:	https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.TLSRoute
+[6]:	https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute
+[7]:	https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.UDPRoute
+[8]:	../tasks/traffic/backend
+[9]:	../api/extension_types#clienttrafficpolicy
+[10]:	../api/extension_types#backendtrafficpolicy
+[11]:	../api/extension_types#securitypolicy
+[12]:	https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/
+[13]:	../api/extension_types#envoyproxy
+[14]:	../api/extension_types#envoypatchpolicy
+[15]:	../api/extension_types#envoyextensionpolicy
\ No newline at end of file