docs: Add new conceptual pages for intro concepts

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](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,27 @@
+---
+title: "API Gateways"
+weight: 3
+---
+
+## 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 makes configuring Envoy Proxy simple by implementing and extending the Kubernetes-native Gateway API. 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/gateway-api.md

@@ -0,0 +1,35 @@
+---
+title: "The Gateway API"
+weight: 1
+---
+
+## 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
+The Gateway API is a Kubernetes API designed to provide a 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` and `Gateway` and various route types like `HTTPRoute` and `TLSRoute`, which allow you to define how traffic is routed, secured, and exposed.
+
+The Gateway API succeeds the Ingress API, which many Kubernetes users may already be familiar with. The Ingress API provided a mechanism for exposing HTTP(S) services to external traffic. The lack of advanced features like regex path matching led to custom annotations to compensate for these deficiencies. This non-standard approach led to fragmentation across Ingress Controllers, challenging portability.
+
+## 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. Envoy Gateway adds production-grade capabilities to that interface, bridging the gap between simplicity and power while keeping everything Kubernetes-native.
+
+One of the Gateway API's key strengths is that implementers can extend it. While providing a foundation for standard routing and traffic control needs, it enables implementations to introduce custom resources that address 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 a 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/latest/concepts/introduction/gateway_api_extensions/_index.md

@@ -0,0 +1,46 @@
+---
+title: "Gateway API Extensions"
+weight: 2
+---
+## Before You Begin
+- [The Gateway API](https://gateway-api.sigs.k8s.io/)
+
+## Overview
+Gateway API Extensions let you configure extra features that aren’t part of the standard Kubernetes Gateway API. These extensions are built by the teams that create and maintain Gateway API implementations.
+The Gateway API was designed to be extensible safe, and reliable. In the old Ingress API, people had to use custom annotations to add new features, but those weren’t type-safe, making it hard to check if their configuration was correct.
+With Gateway API Extensions, implementers provide type-safe Custom Resource Definitions (CRDs). This means every configuration you write has a clear structure and strict rules, making it easier to catch mistakes early and be confident your setup is valid.
+## Use Cases
+
+Here are some examples of what kind of features extensions include:
+
+1. **Advanced Traffic Management:** 
+    Implementing sophisticated load balancing algorithms, circuit breaking, or retries not defined in the core API
+2. **Enhanced Security Controls:** 
+    Adding implementation-specific TLS configurations, authentication mechanisms, or access control rules
+3. **Observability Integration:** 
+    Connecting Gateway resources to monitoring systems, logging pipelines, or tracing frameworks
+4. **Custom Protocol Support:** 
+    Extending beyond HTTP/TCP/UDP with specialized protocol handling
+5. **Rate Limiting and Compression:** 
+    Implementing traffic policing specific to the implementation's capabilities
+
+## Gateway API Extensions in Envoy Gateway
+
+The Envoy Gateway API introduces a set of Gateway API extensions that enable users to leverage the power of the Envoy proxy. Envoy Gateway uses a policy attachment model, where custom policies are applied to standard Gateway API resources (like HTTPRoute or Gateway) without modifying the core API. This approach provides separation of concerns and makes it easier to manage configurations across teams.
+
+{{% alert title="Current Extensions" color="info" %}}
+Currently supported extensions include 
+[`Backend`](../../../api/extension_types#backend), 
+[`BackendTrafficPolicy`](../../../api/extension_types#backendtrafficpolicy), 
+[`ClientTrafficPolicy`](../../../api/extension_types#clienttrafficpolicy), 
+[`EnvoyExtensionPolicy`](../../../api/extension_types#envoyextensionpolicy), 
+[`EnvoyGateway`](../../../api/extension_types#envoygateway), 
+[`EnvoyPatchPolicy`](../../../api/extension_types#envoypatchpolicy), 
+[`EnvoyProxy`](../../../api/extension_types#envoyproxy), 
+[`HTTPRouteFilter`](../../../api/extension_types#httproutefilter), and 
+[`SecurityPolicy`](../../../api/extension_types#securitypolicy), 
+{{% /alert %}}
+
+These extensions are processed through Envoy Gateway's control plane, translating them into xDS configurations applied to Envoy Proxy instances. This layered architecture allows for consistent, scalable, and production-grade traffic control without needing to manage raw Envoy configuration directly.
+
+## Related Resources

site/content/en/latest/concepts/introduction/gateway_api_extensions/backend-traffic-policy.md

@@ -0,0 +1,82 @@
+---
+title: "BackendTrafficPolicy"
+---
+## Before you Begin
+- [Gateway API Extensions](_index.md)
+
+## Overview
+`BackendTrafficPolicy` is an extension to the Kubernetes Gateway API that controls how Envoy Gateway communicates with your backend services. It can configure connection behavior, resilience mechanisms, and performance optimizations without requiring changes to your applications.
+
+Think of it as a traffic controller between your gateway and backend services. It can detect problems, prevent failures from spreading, and optimize request handling to improve system stability.
+
+## Use Cases
+
+`BackendTrafficPolicy` is particularly useful in scenarios where you need to:
+
+1. **Protect your services:** 
+   Limit connections and reject excess traffic when necessary
+
+2. **Build resilient systems:** 
+   Detect failing services and redirect traffic
+
+3. **Improve performance:** 
+   Optimize how requests are distributed and responses are handled
+
+4. **Test system behavior:** 
+   Inject faults and validate your recovery mechanisms
+
+## BackendTrafficPolicy in Envoy Gateway
+
+`BackendTrafficPolicy` is part of the Envoy Gateway API suite, which extends the Kubernetes Gateway API with additional capabilities. It's implemented as a Custom Resource Definition (CRD) that you can use to configure how Envoy Gateway manages traffic to your backend services. 
+
+You can attach it to Gateway API resources in two ways:
+
+1. Using `targetRefs` to directly reference specific Gateway resources
+2. Using `targetSelectors` to match Gateway resources based on labels
+
+The policy applies to all resources that match either targeting method. When multiple policies target the same resource, the most specific configuration wins.
+
+For example, consider these two policies:
+
+```yaml
+# Policy 1: Applies to all routes in the gateway
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: BackendTrafficPolicy
+metadata:
+  name: gateway-policy
+spec:
+  targetRefs:
+    - kind: Gateway
+      name: my-gateway
+  circuitBreaker:
+    maxConnections: 100
+
+---
+# Policy 2: Applies to a specific route
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: BackendTrafficPolicy
+metadata:
+  name: route-policy
+spec:
+  targetRefs:
+    - kind: HTTPRoute
+      name: my-route
+  circuitBreaker:
+    maxConnections: 50
+```
+
+In this example `my-route` and `my-gateway` would both affect the route. However, since Policy 2 targets the route directly while Policy 1 targets the gateway, Policy 2's configuration (`maxConnections: 50`) will take precedence for that specific route.
+
+Lastly, it's important to note that even when you apply a policy to a Gateway, the policy's effects are tracked separately for each backend service referenced in your routes. For example, if you set up circuit breaking on a Gateway with multiple backend services, each backend service will have its own independent circuit breaker counter. This ensures that issues with one backend service don't affect the others.
+
+## Related Resources
+
+- [Circuit Breakers](../../../tasks/traffic/circuit-breaker.md)
+- [Failover](../../../tasks/traffic/failover)
+- [Fault Injection](../../../tasks/traffic/fault-injection)
+- [Global Rate Limit](../../../tasks/traffic/global-rate-limit)
+- [Local Rate Limit](../../../tasks/traffic/local-rate-limit)
+- [Load Balancing](../../../tasks/traffic/load-balancing)
+- [Response Compression](../../../tasks/traffic/response-compression)
+- [Response Override](../../../tasks/traffic/response-override)
+- [BackendTrafficPolicy API Reference](../../../api/extension_types#backendtrafficpolicy)

site/content/en/latest/concepts/introduction/gateway_api_extensions/client-traffic-policy.md

@@ -0,0 +1,88 @@
+---
+title: "ClientTrafficPolicy"
+---
+## Before you Begin
+- [Gateway API Extensions](_index.md)
+
+## Overview
+
+`ClientTrafficPolicy` is an extension to the Kubernetes Gateway API that allows system administrators to configure how the Envoy Proxy server behaves with downstream clients. It is a policy attachment resource that can be applied to Gateway resources and holds settings for configuring the behavior of the connection between the downstream client and Envoy Proxy listener.
+
+Think of `ClientTrafficPolicy` as a set of rules for your Gateway's entry points, it lets you configure specific behaviors for each listener in your Gateway, with more specific rules taking precedence over general ones.
+
+## Use Cases
+
+`ClientTrafficPolicy` is particularly useful in scenarios where you need to:
+
+1. **Enforce TLS Security**
+   Configure TLS termination, mutual TLS (mTLS), and certificate validation at the edge.
+
+2. **Manage Client Connections**
+   Control TCP keepalive behavior and connection timeouts for optimal resource usage.
+
+3. **Handle Client Identity**
+   Configure trusted proxy chains to correctly resolve client IPs for logging and access control.
+
+4. **Normalize Request Paths**
+   Sanitize incoming request paths to ensure compatibility with backend routing rules.
+
+5. **Tune HTTP Protocols**
+   Configure HTTP/1, HTTP/2, and HTTP/3 settings for compatibility and performance.
+
+6. **Monitor Listener Health**
+   Set up health checks for integration with load balancers and failover mechanisms.
+
+## ClientTrafficPolicy in Envoy Gateway
+
+`ClientTrafficPolicy` is part of the Envoy Gateway API suite, which extends the Kubernetes Gateway API with additional capabilities. It's implemented as a Custom Resource Definition (CRD) that you can use to configure how Envoy Gateway manages incoming client traffic. 
+
+You can attach it to Gateway API resources in two ways:
+
+1. Using `targetRefs` to directly reference specific Gateway resources
+2. Using `targetSelectors` to match Gateway resources based on labels
+
+The policy applies to all Gateway resources that match either targeting method. When multiple policies target the same resource, the most specific configuration wins.
+
+For example, consider these policies targeting the same Gateway Listener:
+
+```yaml
+# Policy A: Targets a specific listener in the gateway
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: ClientTrafficPolicy
+metadata:
+  name: listener-specific-policy
+spec:
+  targetRefs:
+    - kind: Gateway
+      name: my-gateway
+      sectionName: https-listener  # Targets specific listener
+  timeout:
+    http:
+      idleTimeout: 30s
+
+---
+# Policy B: Targets the entire gateway
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: ClientTrafficPolicy
+metadata:
+  name: gateway-wide-policy
+spec:
+  targetRefs:
+    - kind: Gateway
+      name: my-gateway  # Targets all listeners
+  timeout:
+    http:
+      idleTimeout: 60s
+```
+
+In this case:
+- Policy A will be applied/attached to the specific Listener defined in the `targetRef.SectionName`
+- Policy B will be applied to the remaining Listeners within the Gateway. Policy B will have an additional status condition Overridden=True.
+
+## Related Resources
+
+- [Connection Limit](../../../tasks/traffic/connection-limit.md)
+- [HTTP Request Headers](../../../tasks/traffic/http-request-headers)
+- [HTTP/3](../../../tasks/traffic/http3)
+- [Mutual TLS: External Clients to the Gateway](../../../tasks/security/mutual-tls.md)
+- [ClientTrafficPolicy API Reference](../../../api/extension_types#clienttrafficpolicy)