docs: Attach EnvoyProxy to Gateway (envoyproxy#4020)

guydc · Aug 10, 2024 · eeb62c8 · eeb62c8
1 parent bd26a41
commit eeb62c8
Show file tree

Hide file tree

Showing 5 changed files with 302 additions and 94 deletions.
diff --git a/site/content/en/docs/boilerplates/prerequisites.md b/site/content/en/docs/boilerplates/prerequisites.md
@@ -0,0 +1,24 @@
+---
+---
+
+Follow the steps from the [Quickstart](../tasks/quickstart) task to install Envoy Gateway and the example manifest.
+Before proceeding, you should be able to query the example backend using HTTP.
+
+Verify the Gateway status:
+
+{{< tabpane text=true >}}
+{{% tab header="kubectl" %}}
+
+```shell
+kubectl get gateway/eg -o yaml
+```
+
+{{% /tab %}}
+{{% tab header="egctl (experimental)" %}}
+
+```shell
+egctl x status gateway -v
+```
+
+{{% /tab %}}
+{{< /tabpane >}}
diff --git a/site/content/en/docs/tasks/operations/customize-envoyproxy.md b/site/content/en/docs/tasks/operations/customize-envoyproxy.md
@@ -3,15 +3,68 @@ title: "Customize EnvoyProxy"
 ---
 
 Envoy Gateway provides an [EnvoyProxy][] CRD that can be linked to the ParametersRef
-in GatewayClass, allowing cluster admins to customize the managed EnvoyProxy Deployment and
+in a Gateway and GatewayClass, allowing cluster admins to customize the managed EnvoyProxy Deployment and
 Service. To learn more about GatewayClass and ParametersRef, please refer to [Gateway API documentation][].
 
 ## Prerequisites
 
-Follow the steps from the [Quickstart](../../quickstart) to install Envoy Gateway and the example manifest.
-Before proceeding, you should be able to query the example backend using HTTP.
+{{< boilerplate prerequisites >}}
 
-Before you start, you need to add `ParametersRef` in GatewayClass, and refer to EnvoyProxy Config:
+Before you start, you need to add `Infrastructure.ParametersRef` in Gateway, and refer to EnvoyProxy Config:
+**Note**: `MergeGateways` cannot be set to `true` in your EnvoyProxy config if attaching to the Gateway.
+
+{{< tabpane text=true >}}
+{{% tab header="Apply from stdin" %}}
+
+```shell
+cat <<EOF | kubectl apply -f -
+apiVersion: gateway.networking.k8s.io/v1
+kind: Gateway
+metadata:
+  name: eg
+spec:
+  gatewayClassName: eg
+  infrastructure:
+    parametersRef:
+      group: gateway.envoyproxy.io
+      kind: EnvoyProxy
+      name: custom-proxy-config
+  listeners:
+    - name: http
+      protocol: HTTP
+      port: 80
+EOF
+```
+
+{{% /tab %}}
+{{% tab header="Apply from file" %}}
+Save and apply the following resource to your cluster:
+
+```yaml
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: Gateway
+metadata:
+  name: eg
+spec:
+  gatewayClassName: eg
+  infrastructure:
+    parametersRef:
+      group: gateway.envoyproxy.io
+      kind: EnvoyProxy
+      name: custom-proxy-config
+  listeners:
+    - name: http
+      protocol: HTTP
+      port: 80
+```
+
+{{% /tab %}}
+{{< /tabpane >}}
+
+You can also attach the EnvoyProxy resource to the GatewayClass using the `parametersRef` field.
+This configuration is discouraged if you plan on creating multiple Gateways linking to the same
+GatewayClass and would like different infrastructure configurations for each of them.
 
 {{< tabpane text=true >}}
 {{% tab header="Apply from stdin" %}}
@@ -28,7 +81,7 @@ spec:
     group: gateway.envoyproxy.io
     kind: EnvoyProxy
     name: custom-proxy-config
-    namespace: envoy-gateway-system
+    namespace: default
 EOF
 ```
 
@@ -48,7 +101,7 @@ spec:
     group: gateway.envoyproxy.io
     kind: EnvoyProxy
     name: custom-proxy-config
-    namespace: envoy-gateway-system
+    namespace: default
 ```
 
 {{% /tab %}}
@@ -67,7 +120,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: custom-proxy-config
-  namespace: envoy-gateway-system
+  namespace: default
 spec:
   provider:
     type: Kubernetes
@@ -87,7 +140,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: custom-proxy-config
-  namespace: envoy-gateway-system
+  namespace: default
 spec:
   provider:
     type: Kubernetes
@@ -119,7 +172,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: custom-proxy-config
-  namespace: envoy-gateway-system
+  namespace: default
 spec:
   provider:
     type: Kubernetes
@@ -140,7 +193,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: custom-proxy-config
-  namespace: envoy-gateway-system
+  namespace: default
 spec:
   provider:
     type: Kubernetes
@@ -168,7 +221,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: custom-proxy-config
-  namespace: envoy-gateway-system
+  namespace: default
 spec:
   provider:
     type: Kubernetes
@@ -191,7 +244,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: custom-proxy-config
-  namespace: envoy-gateway-system
+  namespace: default
 spec:
   provider:
     type: Kubernetes
@@ -221,7 +274,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: custom-proxy-config
-  namespace: envoy-gateway-system
+  namespace: default
 spec:
   provider:
     type: Kubernetes
@@ -248,7 +301,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: custom-proxy-config
-  namespace: envoy-gateway-system
+  namespace: default
 spec:
   provider:
     type: Kubernetes
@@ -280,7 +333,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: custom-proxy-config
-  namespace: envoy-gateway-system
+  namespace: default
 spec:
   provider:
     type: Kubernetes
@@ -305,7 +358,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: custom-proxy-config
-  namespace: envoy-gateway-system
+  namespace: default
 spec:
   provider:
     type: Kubernetes
@@ -339,7 +392,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: custom-proxy-config
-  namespace: envoy-gateway-system
+  namespace: default
 spec:
   provider:
     type: Kubernetes
@@ -368,7 +421,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: custom-proxy-config
-  namespace: envoy-gateway-system
+  namespace: default
 spec:
   provider:
     type: Kubernetes
@@ -404,7 +457,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: custom-proxy-config
-  namespace: envoy-gateway-system
+  namespace: default
 spec:
   provider:
     type: Kubernetes
@@ -426,7 +479,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: custom-proxy-config
-  namespace: envoy-gateway-system
+  namespace: default
 spec:
   provider:
     type: Kubernetes
@@ -459,7 +512,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: custom-proxy-config
-  namespace: envoy-gateway-system
+  namespace: default 
 spec:
   bootstrap:
     type: Replace
@@ -547,7 +600,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: custom-proxy-config
-  namespace: envoy-gateway-system
+  namespace: default
 spec:
   bootstrap:
     type: Replace
@@ -649,7 +702,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: custom-proxy-config
-  namespace: envoy-gateway-system
+  namespace: default 
 spec:
   provider:
     type: Kubernetes
@@ -677,7 +730,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: custom-proxy-config
-  namespace: envoy-gateway-system
+  namespace: default 
 spec:
   provider:
     type: Kubernetes
@@ -713,7 +766,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: custom-proxy-config
-  namespace: envoy-gateway-system
+  namespace: default 
 spec:
   extraArgs:
     - --disable-extensions envoy.access_loggers/envoy.access_loggers.wasm 
@@ -730,7 +783,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: custom-proxy-config
-  namespace: envoy-gateway-system
+  namespace: default 
 spec:
   extraArgs:
     - --disable-extensions envoy.access_loggers/envoy.access_loggers.wasm 
@@ -756,7 +809,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: eg
-  namespace: envoy-gateway-system
+  namespace: default 
 spec:
   provider:
     type: Kubernetes
@@ -792,7 +845,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: eg
-  namespace: envoy-gateway-system
+  namespace: default
 spec:
   provider:
     type: Kubernetes
@@ -835,7 +888,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: eg
-  namespace: envoy-gateway-system
+  namespace: default
 spec:
   provider:
     type: Kubernetes
@@ -860,7 +913,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: eg
-  namespace: envoy-gateway-system
+  namespace: default
 spec:
   provider:
     type: Kubernetes
@@ -918,7 +971,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: custom-proxy-config
-  namespace: envoy-gateway-system
+  namespace: default
 spec:
   filterOrder:
     - name: envoy.filters.http.wasm
@@ -938,7 +991,7 @@ apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: EnvoyProxy
 metadata:
   name: custom-proxy-config
-  namespace: envoy-gateway-system
+  namespace: default
 spec:
   filterOrder:
     - name: envoy.filters.http.wasm