docs: Conceptual Docs for Api Gateways, The Gateway Api & Envoy Proxy [Clean]

site/content/en/latest/concepts/introduction/_index.md

@@ -0,0 +1,40 @@
+---
+title: "Introduction"
+weight: 1
+---
+
+## Overview
+
+**Envoy Gateway** is a Kubernetes-native [API Gateway](api_gateways.md) and reverse proxy control plane. It simplifies deploying and operating [Envoy Proxy](envoy_proxy.md) as a data plane by using the standard [Gateway API](gateway_api.md) and its own extensible APIs.
+
+By combining Envoy's performance and flexibility with Kubernetes-native configuration, Envoy Gateway helps platform teams expose and manage secure, observable, and scalable APIs with minimal operational overhead.
+
+## Why Use Envoy Gateway?
+
+Traditionally, configuring Envoy Proxy required deep networking expertise and writing complex configuration files. Envoy Gateway removes that barrier by:
+
+- Integrating tightly with Kubernetes through the Gateway API
+- Providing custom CRDs for advanced traffic policies
+- Automatically translating Kubernetes resources into Envoy config
+- Managing the lifecycle of Envoy Proxy instances
+
+Envoy Gateway is designed to be **simple for app developers**, **powerful for platform engineers**, and **production-ready for large-scale deployments**.
+
+## Structure
+
+The different layers of Envoy Gateway are the following:
+
+| Layer       | Description |
+|----------------|-------------|
+| **User Configuration** | Users define routing, security, and traffic policies using standard Kubernetes Gateway API resources, optionally extended with Envoy Gateway CRDs.|
+| **Envoy Gateway Controller** | A control plane component that watches Gateway API and Envoy Gateway-specific resources, translates them, and produces configuration for Envoy Proxy.|
+| **Envoy Proxy(Data Plane)** | A high-performance proxy that receives and handles live traffic according to the configuration generated by Envoy Gateway.|
+
+Together, these layers create a system that's:
+- Easy to configure
+- Powerful enough for complex needs
+- Standardized and familiar
+- Ready for the future
+
+## Next Steps
+For a deeper understanding of Envoy Gateway’s building blocks, you may also wish to explore these conceptual guides:

site/content/en/latest/concepts/introduction/api_gateways.md

@@ -0,0 +1,26 @@
+---
+title: "API Gateways"
+---
+
+## Overview
+An API gateway is a centralized entry point for managing, securing, and routing requests to backend services. It handles cross-cutting concerns, like authentication, rate limiting, and protocol translation, so individual services don’t have to. Decoupling clients from internal systems simplifies scaling, enforces consistency, and reduces redundancy.
+
+## Use Cases
+
+Use an API Gateway to:
+- Avoid duplicating logic across microservices.
+- Create a central point of control for access, monitoring, and traffic rules.
+- Expose internal services to the public internet.
+- Provide protocol support for HTTP, gRPC, or TLS.
+- Enforce policies and see traffic metrics at the edge.
+
+## API Gateways in relation to Envoy Gateway
+
+Under the hood, Envoy Proxy is a powerful, production-grade proxy that supports many of the capabilities you'd expect from an API Gateway, like traffic routing, retries, TLS termination, observability, and more. However, configuring Envoy directly can be complex and verbose.
+
+Envoy Gateway solves this by providing a Kubernetes-native interface, using the standard Gateway API and its own custom resources, to make configuring Envoy Proxy simpler and more approachable. You define high-level traffic rules using resources like Gateway, HTTPRoute, or TLSRoute, and Envoy Gateway automatically translates them into detailed Envoy Proxy configurations.
+
+## Related Resources
+
+- [Getting Started with Envoy Gateway](../../tasks/quickstart.md)
+- [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/)

site/content/en/latest/concepts/introduction/envoy_proxy.md

@@ -0,0 +1,39 @@
+---
+title: "Envoy Proxy"
+---
+
+## Overview
+
+A proxy server acts as an intermediary between a client (like a web browser) and another server (such as a website). When the client makes a request, the proxy forwards it to the destination server, receives the response, and then sends it back to the client.
+
+Proxies are commonly used to enhance security, manage traffic, anonymize user activity, or optimize performance through features like caching and load balancing. In cloud environments, they often handle critical tasks such as request routing, TLS termination, authentication, and traffic shaping.
+
+Envoy Proxy is a high-performance, open-source proxy designed for cloud-native applications. Originally developed at Lyft and now a graduated project in the Cloud Native Computing Foundation (CNCF), Envoy supports use cases for edge and service proxies, routing traffic at the system’s boundary or between internal services.
+
+## Use Cases
+
+Use Envoy Proxy to:
+- Manage internal or external traffic with a powerful L3/L4/L7 proxy
+- Control HTTP, gRPC, or TLS routing with fine-grained match and rewrite rules
+- Gain full observability via built-in metrics, tracing, and logging
+- Implement smart load balancing and resilient failover strategies
+- Integrate seamlessly with service meshes, API gateways, and other control planes
+
+## Envoy Proxy in Envoy Gateway
+
+Because of its rich feature set and extensibility,Envoy Gateway uses Envoy Proxy as its data plane. That means Envoy Proxy is the component actually handling traffic—terminating TLS, routing requests, and applying policies.
+
+Here’s how the interaction works:
+
+1. You define traffic rules using Kubernetes Gateway API resources like `Gateway`, `HTTPRoute`, or Envoy Gateway's own CRDs (e.g., `BackendTrafficPolicy`, `ClientTrafficPolicy`) implemented as Gateway API extensions.
+
+2. Envoy Gateway translates those rules into Envoy Proxy configuration behind the scenes.
+
+3. Envoy Proxy enforces those rules, acting on real-world traffic—balancing requests, rejecting unauthorized ones, collecting metrics, etc.
+
+This separation of concerns allows users to configure traffic behavior declaratively (with CRDs), while leveraging Envoy Proxy's robust capabilities under the hood.
+
+
+## Related Resources
+- [Getting Started with Envoy Gateway](../../tasks/quickstart.md)
+- [Envoy Proxy](https://www.envoyproxy.io/)

site/content/en/latest/concepts/introduction/gateway_api.md

@@ -0,0 +1,36 @@
+---
+title: "The Gateway API"
+---
+
+## Before You Begin
+You may want to be familiar with:
+- [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/)
+- [Kubernetes Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/)
+
+## Overview
+
+Kubernetes users may already be familiar with Ingress, which provides a simple mechanism for exposing HTTP(S) services to external traffic. While effective for basic use cases such as host and path-based routing, the Ingress API lacks advanced features like regex path matching. To compensate for this deficiency, custom annotations are needed. However, this non-standard approach leads to fragmentation across Ingress Controllers, making portability challenging.
+
+The Gateway API is a modern Kubernetes API designed to provide a more consistent, expressive, and extensible method for managing network traffic into and within a Kubernetes cluster, compared to the legacy Ingress API. It introduces core resources such as `GatewayClass`, `Gateway`, and various route types like `HTTPRoute` and `TLSRoute`, which allow you to define how traffic is routed, secured, and exposed.
+
+## Use Cases
+Use The Gateway API to:
+- Define how external traffic enters and is routed within your cluster
+- Configure HTTP(S), TLS, and TCP traffic routing in a standardized, Kubernetes-native way
+- Apply host-based, path-based, and header-based routing rules using HTTPRoute
+- Terminate TLS at the edge using Gateway TLS configuration
+- Separate responsibilities between infrastructure and application teams through role-oriented resource design
+- Improve portability and consistency across different gateway implementations
+
+## The Gateway API in Envoy Gateway
+In essence, the Gateway API provides a standard interface, and Envoy Gateway adds production-grade capabilities to that interface—bridging the gap between simplicity and power while keeping everything Kubernetes-native.
+
+One of the key strengths of the Gateway API is its extensibility. While it provides a solid foundation for routing and traffic control, it also enables implementations to introduce custom resources that enhance and tailor functionality for specific use cases.
+
+Envoy Gateway leverages this model by introducing a suite of Gateway API extensions—implemented as Kubernetes Custom Resource Definitions (CRDs)—to expose powerful features from Envoy Proxy. These features include enhanced support for rate limiting, authentication, traffic shaping, and more. By utilizing these extensions, users can access production-grade functionality in a Kubernetes-native and declarative manner, without needing to write low-level Envoy configuration.
+
+## Related Resources
+
+- [Getting Started with Envoy Gateway](../../tasks/quickstart.md)
+- [Envoy Gateway API Reference](../../api/extension_types)
+- [Extensibility Tasks](../../tasks/extensibility/_index.md)

site/content/en/v1.3/concepts/introduction/_index.md

@@ -0,0 +1,40 @@
+---
+title: "Introduction"
+weight: 1
+---
+
+## Overview
+
+**Envoy Gateway** is a Kubernetes-native [API Gateway](api_gateways.md) and reverse proxy control plane. It simplifies deploying and operating [Envoy Proxy](envoy_proxy.md) as a data plane by using the standard [Gateway API](gateway_api.md) and its own extensible APIs.
+
+By combining Envoy's performance and flexibility with Kubernetes-native configuration, Envoy Gateway helps platform teams expose and manage secure, observable, and scalable APIs with minimal operational overhead.
+
+## Why Use Envoy Gateway?
+
+Traditionally, configuring Envoy Proxy required deep networking expertise and writing complex configuration files. Envoy Gateway removes that barrier by:
+
+- Integrating tightly with Kubernetes through the Gateway API
+- Providing custom CRDs for advanced traffic policies
+- Automatically translating Kubernetes resources into Envoy config
+- Managing the lifecycle of Envoy Proxy instances
+
+Envoy Gateway is designed to be **simple for app developers**, **powerful for platform engineers**, and **production-ready for large-scale deployments**.
+
+## Structure
+
+The different layers of Envoy Gateway are the following:
+
+| Layer       | Description |
+|----------------|-------------|
+| **User Configuration** | Users define routing, security, and traffic policies using standard Kubernetes Gateway API resources, optionally extended with Envoy Gateway CRDs.|
+| **Envoy Gateway Controller** | A control plane component that watches Gateway API and Envoy Gateway-specific resources, translates them, and produces configuration for Envoy Proxy.|
+| **Envoy Proxy(Data Plane)** | A high-performance proxy that receives and handles live traffic according to the configuration generated by Envoy Gateway.|
+
+Together, these layers create a system that's:
+- Easy to configure
+- Powerful enough for complex needs
+- Standardized and familiar
+- Ready for the future
+
+## Next Steps
+For a deeper understanding of Envoy Gateway’s building blocks, you may also wish to explore these conceptual guides:

site/content/en/v1.3/concepts/introduction/api_gateways.md

@@ -0,0 +1,26 @@
+---
+title: "API Gateways"
+---
+
+## Overview
+An API gateway is a centralized entry point for managing, securing, and routing requests to backend services. It handles cross-cutting concerns, like authentication, rate limiting, and protocol translation, so individual services don’t have to. Decoupling clients from internal systems simplifies scaling, enforces consistency, and reduces redundancy.
+
+## Use Cases
+
+Use an API Gateway to:
+- Avoid duplicating logic across microservices.
+- Create a central point of control for access, monitoring, and traffic rules.
+- Expose internal services to the public internet.
+- Provide protocol support for HTTP, gRPC, or TLS.
+- Enforce policies and see traffic metrics at the edge.
+
+## API Gateways in relation to Envoy Gateway
+
+Under the hood, Envoy Proxy is a powerful, production-grade proxy that supports many of the capabilities you'd expect from an API Gateway, like traffic routing, retries, TLS termination, observability, and more. However, configuring Envoy directly can be complex and verbose.
+
+Envoy Gateway solves this by providing a Kubernetes-native interface, using the standard Gateway API and its own custom resources, to make configuring Envoy Proxy simpler and more approachable. You define high-level traffic rules using resources like Gateway, HTTPRoute, or TLSRoute, and Envoy Gateway automatically translates them into detailed Envoy Proxy configurations.
+
+## Related Resources
+
+- [Getting Started with Envoy Gateway](../../tasks/quickstart.md)
+- [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/)

site/content/en/v1.3/concepts/introduction/envoy_proxy.md

@@ -0,0 +1,39 @@
+---
+title: "Envoy Proxy"
+---
+
+## Overview
+
+A proxy server acts as an intermediary between a client (like a web browser) and another server (such as a website). When the client makes a request, the proxy forwards it to the destination server, receives the response, and then sends it back to the client.
+
+Proxies are commonly used to enhance security, manage traffic, anonymize user activity, or optimize performance through features like caching and load balancing. In cloud environments, they often handle critical tasks such as request routing, TLS termination, authentication, and traffic shaping.
+
+Envoy Proxy is a high-performance, open-source proxy designed for cloud-native applications. Originally developed at Lyft and now a graduated project in the Cloud Native Computing Foundation (CNCF), Envoy supports use cases for edge and service proxies, routing traffic at the system’s boundary or between internal services.
+
+## Use Cases
+
+Use Envoy Proxy to:
+- Manage internal or external traffic with a powerful L3/L4/L7 proxy
+- Control HTTP, gRPC, or TLS routing with fine-grained match and rewrite rules
+- Gain full observability via built-in metrics, tracing, and logging
+- Implement smart load balancing and resilient failover strategies
+- Integrate seamlessly with service meshes, API gateways, and other control planes
+
+## Envoy Proxy in Envoy Gateway
+
+Because of its rich feature set and extensibility,Envoy Gateway uses Envoy Proxy as its data plane. That means Envoy Proxy is the component actually handling traffic—terminating TLS, routing requests, and applying policies.
+
+Here’s how the interaction works:
+
+1. You define traffic rules using Kubernetes Gateway API resources like `Gateway`, `HTTPRoute`, or Envoy Gateway's own CRDs (e.g., `BackendTrafficPolicy`, `ClientTrafficPolicy`) implemented as Gateway API extensions.
+
+2. Envoy Gateway translates those rules into Envoy Proxy configuration behind the scenes.
+
+3. Envoy Proxy enforces those rules, acting on real-world traffic—balancing requests, rejecting unauthorized ones, collecting metrics, etc.
+
+This separation of concerns allows users to configure traffic behavior declaratively (with CRDs), while leveraging Envoy Proxy's robust capabilities under the hood.
+
+
+## Related Resources
+- [Getting Started with Envoy Gateway](../../tasks/quickstart.md)
+- [Envoy Proxy](https://www.envoyproxy.io/)

site/content/en/v1.3/concepts/introduction/gateway_api.md

@@ -0,0 +1,36 @@
+---
+title: "The Gateway API"
+---
+
+## Before You Begin
+You may want to be familiar with:
+- [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/)
+- [Kubernetes Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/)
+
+## Overview
+
+Kubernetes users may already be familiar with Ingress, which provides a simple mechanism for exposing HTTP(S) services to external traffic. While effective for basic use cases such as host and path-based routing, the Ingress API lacks advanced features like regex path matching. To compensate for this deficiency, custom annotations are needed. However, this non-standard approach leads to fragmentation across Ingress Controllers, making portability challenging.
+
+The Gateway API is a modern Kubernetes API designed to provide a more consistent, expressive, and extensible method for managing network traffic into and within a Kubernetes cluster, compared to the legacy Ingress API. It introduces core resources such as `GatewayClass`, `Gateway`, and various route types like `HTTPRoute` and `TLSRoute`, which allow you to define how traffic is routed, secured, and exposed.
+
+## Use Cases
+Use The Gateway API to:
+- Define how external traffic enters and is routed within your cluster
+- Configure HTTP(S), TLS, and TCP traffic routing in a standardized, Kubernetes-native way
+- Apply host-based, path-based, and header-based routing rules using HTTPRoute
+- Terminate TLS at the edge using Gateway TLS configuration
+- Separate responsibilities between infrastructure and application teams through role-oriented resource design
+- Improve portability and consistency across different gateway implementations
+
+## The Gateway API in Envoy Gateway
+In essence, the Gateway API provides a standard interface, and Envoy Gateway adds production-grade capabilities to that interface—bridging the gap between simplicity and power while keeping everything Kubernetes-native.
+
+One of the key strengths of the Gateway API is its extensibility. While it provides a solid foundation for routing and traffic control, it also enables implementations to introduce custom resources that enhance and tailor functionality for specific use cases.
+
+Envoy Gateway leverages this model by introducing a suite of Gateway API extensions—implemented as Kubernetes Custom Resource Definitions (CRDs)—to expose powerful features from Envoy Proxy. These features include enhanced support for rate limiting, authentication, traffic shaping, and more. By utilizing these extensions, users can access production-grade functionality in a Kubernetes-native and declarative manner, without needing to write low-level Envoy configuration.
+
+## Related Resources
+
+- [Getting Started with Envoy Gateway](../../tasks/quickstart.md)
+- [Envoy Gateway API Reference](../../api/extension_types)
+- [Extensibility Tasks](../../tasks/extensibility/_index.md)