Repository: envoyproxy/gateway
Pull request #5934 (2025-05-06 06:11:29)

chore: clean up BTP status
fixes: #5931

Errors from the EnvoyProxy TLS settings should not be reflected in the BackendTLSPolicy status.

Instead, the BackendTLSPolicy should be accepted, since its configuration is valid.

The EnvoyProxy TLS error is already reported in the HTTPRoute status, as shown in the following yaml snippet:

```
  status:
    parents:
    - conditions:
      - lastTransitionTime: null
        message: Route is accepted
        reason: Accepted
        status: "True"
        type: Accepted
      - lastTransitionTime: null
        message: 'Failed to process route rule 0 backendRef 0: failed to locate TLS
          secret for client auth: envoy-gateway-system/client-auth-not-found specified
          in EnvoyProxy envoy-gateway-system/test.'
        reason: InvalidBackendTLS
        status: "False"
        type: ResolvedRefs
      controllerName: gateway.envoyproxy.io/gatewayclass-controller
```

codecov[bot]: ## [Codecov](https://app.codecov.io/gh/envoyproxy/gateway/pull/5934?dropdown=coverage&src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=envoyproxy) Report
All modified and coverable lines are covered by tests :white_check_mark:
> Project coverage is 65.29%. Comparing base [(`95b4f97`)](https://app.codecov.io/gh/envoyproxy/gateway/commit/95b4f9757817bd6211158251cad6b3a9d663701d?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=envoyproxy) to head [(`fd8866b`)](https://app.codecov.io/gh/envoyproxy/gateway/commit/fd8866b5eb650a08cb41eca86f7d9339bd103f2a?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=envoyproxy).

<details><summary>Additional details and impacted files</summary>


```diff
@@            Coverage Diff             @@
##             main    #5934      +/-   ##
==========================================
+ Coverage   65.26%   65.29%   +0.02%     
==========================================
  Files         216      216              
  Lines       35912    35907       -5     
==========================================
+ Hits        23438    23444       +6     
+ Misses      11019    11011       -8     
+ Partials     1455     1452       -3     
```

</details>

[:umbrella: View full report in Codecov by Sentry](https://app.codecov.io/gh/envoyproxy/gateway/pull/5934?dropdown=coverage&src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=envoyproxy).   
:loudspeaker: Have feedback on the report? [Share it here](https://about.codecov.io/codecov-pr-comment-feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=envoyproxy).

<details><summary> :rocket: New features to boost your workflow: </summary>

- :snowflake: [Test Analytics](https://docs.codecov.com/docs/test-analytics): Detect flaky tests, report on failures, and find test suite problems.
</details>

Patch:
diff --git a/internal/gatewayapi/backendtlspolicy.go b/internal/gatewayapi/backendtlspolicy.go
index c6bc0b8bb..143bc749f 100644
--- a/internal/gatewayapi/backendtlspolicy.go
+++ b/internal/gatewayapi/backendtlspolicy.go
@@ -44,19 +44,12 @@ func (t *Translator) applyBackendTLSSetting(
 		return t.applyEnvoyProxyBackendTLSSetting(tlsBundle, resources, envoyProxy)
 	}
 
-	upstreamConfig, policy, err := t.processBackendTLSPolicy(backendRef, backendNamespace, parent, resources)
+	upstreamConfig, err := t.processBackendTLSPolicy(backendRef, backendNamespace, parent, resources)
 	if err != nil {
 		return nil, err
 	}
-	// TODO: zhaohuabing is it correct to surface the EnvoyProxy TLS error to the policy?
-	// We probably should just remove this, the TLS error is already reported in the route status as "InvalidBackendTLS",
-	// and the BackendTLSPolicy is configured correctly.
+
 	if tlsBundle, err = t.applyEnvoyProxyBackendTLSSetting(upstreamConfig, resources, envoyProxy); err != nil {
-		status.SetTranslationErrorForPolicyAncestors(&policy.Status,
-			[]gwapiv1a2.ParentReference{parent},
-			t.GatewayControllerName,
-			policy.Generation,
-			status.Error2ConditionMsg(err))
 		return nil, err
 	}
 	return tlsBundle, nil
@@ -101,10 +94,10 @@ func (t *Translator) processBackendTLSPolicy(
 	backendNamespace string,
 	parent gwapiv1a2.ParentReference,
 	resources *resource.Resources,
-) (*ir.TLSUpstreamConfig, *gwapiv1a3.BackendTLSPolicy, error) {
+) (*ir.TLSUpstreamConfig, error) {
 	policy := getBackendTLSPolicy(resources.BackendTLSPolicies, backendRef, backendNamespace, resources)
 	if policy == nil {
-		return nil, nil, nil
+		return nil, nil
 	}
 
 	tlsBundle, err := getBackendTLSBundle(policy, resources)
@@ -118,11 +111,11 @@ func (t *Translator) processBackendTLSPolicy(
 			policy.Generation,
 			status.Error2ConditionMsg(err),
 		)
-		return nil, nil, err
+		return nil, err
 	}
 
 	status.SetAcceptedForPolicyAncestors(&policy.Status, ancestorRefs, t.GatewayControllerName)
-	return tlsBundle, policy, nil
+	return tlsBundle, nil
 }
 
 func (t *Translator) applyEnvoyProxyBackendTLSSetting(tlsConfig *ir.TLSUpstreamConfig, resources *resource.Resources, ep *egv1a1.EnvoyProxy) (*ir.TLSUpstreamConfig, error) {
diff --git a/site/content/en/v1.3/boilerplates/kind-cluster.md b/site/content/en/v1.3/boilerplates/kind-cluster.md
new file mode 100644
index 000000000..643bb28cb
--- /dev/null
+++ b/site/content/en/v1.3/boilerplates/kind-cluster.md
@@ -0,0 +1,6 @@
+Envoy Gateway is typically deployed in a Kubernetes cluster.
+If you don’t have one yet, you can use `kind` to create a local cluster for testing purposes.
+
+{{% alert title="Developer Guide" color="primary" %}}
+Refer to the [Developer Guide](../../contributions/develop) to learn more.
+{{% /alert %}}
diff --git a/site/content/en/v1.3/boilerplates/open-ports.md b/site/content/en/v1.3/boilerplates/open-ports.md
new file mode 100644
index 000000000..f193c2d2d
--- /dev/null
+++ b/site/content/en/v1.3/boilerplates/open-ports.md
@@ -0,0 +1,22 @@
+## Open Ports
+
+These are the ports used by Envoy Gateway and the managed Envoy Proxy.
+
+### Envoy Gateway
+
+|     Envoy Gateway     |  Address  | Port  | Configurable |
+| :-------------------: | :-------: | :---: | :----------: |
+| Xds EnvoyProxy Server |  0.0.0.0  | 18000 |      No      |
+| Xds RateLimit Server  |  0.0.0.0  | 18001 |      No      |
+|     Admin Server      | 127.0.0.1 | 19000 |     Yes      |
+|    Metrics Server     |  0.0.0.0  | 19001 |      No      |
+|     Health Check      | 127.0.0.1 | 8081  |      No      |
+
+### EnvoyProxy
+
+|   Envoy Proxy    |  Address  | Port  |
+| :--------------: | :-------: | :---: |
+|   Admin Server   | 127.0.0.1 | 19000 |
+|      Stats       |  0.0.0.0  | 19001 |
+| Shutdown Manager |  0.0.0.0  | 19002 |
+|    Readiness     |  0.0.0.0  | 19003 |
diff --git a/site/content/en/v1.3/install/install-argocd.md b/site/content/en/v1.3/install/install-argocd.md
new file mode 100644
index 000000000..b04ec5126
--- /dev/null
+++ b/site/content/en/v1.3/install/install-argocd.md
@@ -0,0 +1,128 @@
++++
+title = "Install with Argo CD"
+weight = -99
++++
+
+[Argo CD](https://argo-cd.readthedocs.io) is a declarative, GitOps continuous delivery tool for Kubernetes.
+Argo CD can be used to manage the deployment of Envoy Gateway on Kubernetes clusters.
+
+## Before you begin
+
+{{% alert title="Compatibility Matrix" color="warning" %}}
+Refer to the [Version Compatibility Matrix](/news/releases/matrix) to learn more.
+{{% /alert %}}
+
+{{< boilerplate kind-cluster >}}
+
+Argo CD must be installed in your Kubernetes cluster, and the argocd CLI must be available on your local machine.
+If you haven’t set it up yet, you can follow the [official installation guide](https://argo-cd.readthedocs.io/en/stable/operator-manual/installation/) to install Argo CD.
+
+## Install with Argo CD
+
+Create a new Argo CD Application that pulls the Envoy Gateway Helm chart as its source.
+
+```shell
+cat <<EOF | kubectl apply -f -
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: envoy-gateway
+  namespace: argocd
+spec:
+  project: default
+  source:
+    chart: gateway-helm
+    repoURL: docker.io/envoyproxy
+    targetRevision: {{< helm-version >}}
+  destination:
+    namespace: envoy-gateway-system
+    server: https://kubernetes.default.svc
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true
+    - ServerSideApply=true
+    automated:
+      prune: true
+      selfHeal: true
+EOF
+```
+
+**Note**:
+
+* Set `ServerSideApply` to `true` to enable Kubernetes [server-side apply](https://kubernetes.io/docs/reference/using-api/server-side-apply/). This helps avoid the 262,144-byte annotation size limit.
+* For simplicity, we apply the Application resource directly to the cluster.
+In a production environment, it’s recommended to store this configuration in a Git repository and manage it using another Argo CD Application that uses Git as its source — following a GitOps workflow.
+
+Wait for Envoy Gateway to become available:
+
+```shell
+kubectl wait --timeout=5m -n envoy-gateway-system deployment/envoy-gateway --for=condition=Available
+```
+
+Install the GatewayClass, Gateway, HTTPRoute and example app:
+
+```shell
+kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/{{< yaml-version >}}/quickstart.yaml -n default
+```
+
+**Note**: [`quickstart.yaml`] defines that Envoy Gateway will listen for
+traffic on port 80 on its globally-routable IP address, to make it easy to use
+browsers to test Envoy Gateway. When Envoy Gateway sees that its Listener is
+using a privileged port (<1024), it will map this internally to an
+unprivileged port, so that Envoy Gateway doesn't need additional privileges.
+It's important to be aware of this mapping, since you may need to take it into
+consideration when debugging.
+
+[`quickstart.yaml`]: https://github.com/envoyproxy/gateway/releases/download/{{< yaml-version >}}/quickstart.yaml
+
+
+## Helm chart customizations
+
+You can customize the Envoy Gateway installation by using the Helm chart values.
+
+{{% alert title="Helm Chart Values" color="primary" %}}
+If you want to know all the available fields inside the values.yaml file, please see the [Helm Chart Values](./gateway-helm-api).
+{{% /alert %}}
+
+Below is an example of how to customize the Envoy Gateway installation by using the `valuesObject` field in the Argo CD Application.
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: envoy-gateway
+  namespace: argocd
+spec:
+  project: default
+  source:
+    helm:
+      valuesObject:
+        deployment:
+          envoyGateway:
+            resources:
+              limits:
+                cpu: 700m
+                memory: 256Mi
+    chart: gateway-helm
+    path: gateway-helm
+    repoURL: docker.io/envoyproxy
+    targetRevision: {{< helm-version >}}
+  destination:
+    namespace: envoy-gateway-system
+    server: https://kubernetes.default.svc
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true
+    - ServerSideApply=true
+    automated:
+      prune: true
+      selfHeal: true
+```
+
+Argo CD supports multiple ways of specifying Helm chart values, you can find more details in the [Argo CD documentation](https://argo-cd.readthedocs.io/en/stable/user-guide/helm/#helm).
+
+{{< boilerplate open-ports >}}
+
+{{% alert title="Next Steps" color="warning" %}}
+Envoy Gateway should now be successfully installed and running.  To experience more abilities of Envoy Gateway, refer to [Tasks](../tasks).
+{{% /alert %}}
diff --git a/site/content/en/v1.3/install/install-helm.md b/site/content/en/v1.3/install/install-helm.md
index d146194d3..7fb15b708 100644
--- a/site/content/en/v1.3/install/install-helm.md
+++ b/site/content/en/v1.3/install/install-helm.md
@@ -3,7 +3,7 @@ title = "Install with Helm"
 weight = -100
 +++
 
-[Helm](https://helm.sh) is a package manager for Kubernetes that automates the release and management of software on Kubernetes. 
+[Helm](https://helm.sh) is a package manager for Kubernetes that automates the release and management of software on Kubernetes.
 
 Envoy Gateway can be installed via a Helm chart with a few simple steps, depending on if you are deploying for the first time, upgrading Envoy Gateway from an existing installation, or migrating from Envoy Gateway.
 
@@ -13,6 +13,8 @@ Envoy Gateway can be installed via a Helm chart with a few simple steps, dependi
 Refer to the [Version Compatibility Matrix](/news/releases/matrix) to learn more.
 {{% /alert %}}
 
+{{< boilerplate kind-cluster >}}
+
 The Envoy Gateway Helm chart is hosted by DockerHub.
 
 It is published at `oci://docker.io/envoyproxy/gateway-helm`.
@@ -25,12 +27,6 @@ You can visit [Envoy Gateway Helm Chart](https://hub.docker.com/r/envoyproxy/gat
 
 ## Install with Helm
 
-Envoy Gateway is typically deployed to Kubernetes from the command line. If you don't have Kubernetes, you should use `kind` to create one.
-
-{{% alert title="Developer Guide" color="primary" %}}
-Refer to the [Developer Guide](../../contributions/develop) to learn more.
-{{% /alert %}}
-
 Install the Gateway API CRDs and Envoy Gateway:
 
 ```shell
@@ -63,7 +59,7 @@ consideration when debugging.
 
 [Helm](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/#some-caveats-and-explanations) does not update CRDs
 that live in the `/crds` folder in the Helm Chart. So you will manually need to update the CRDs.
-Follow the steps outlined in [this](./install-yaml/#upgrading-from-v1.2) section if you're upgrading from a previous version.
+Follow the steps outlined in [this](./install-yaml/#upgrading-from-a-previous-version) section if you're upgrading from a previous version.
 
 ## Helm chart customizations
 
@@ -124,28 +120,7 @@ You can use the below command to install the envoy gateway using values.yaml fil
 helm install eg oci://docker.io/envoyproxy/gateway-helm --version {{< helm-version >}} -n envoy-gateway-system --create-namespace -f values.yaml
 ```
 
-## Open Ports
-
-These are the ports used by Envoy Gateway and the managed Envoy Proxy.
-
-### Envoy Gateway
-
-|     Envoy Gateway     |  Address  | Port  | Configurable |
-| :-------------------: | :-------: | :---: | :----------: |
-| Xds EnvoyProxy Server |  0.0.0.0  | 18000 |      No      |
-| Xds RateLimit Server  |  0.0.0.0  | 18001 |      No      |
-|     Admin Server      | 127.0.0.1 | 19000 |     Yes      |
-|    Metrics Server     |  0.0.0.0  | 19001 |      No      |
-|     Health Check      | 127.0.0.1 | 8081  |      No      |
-
-### EnvoyProxy
-
-|   Envoy Proxy    |  Address  | Port  |
-| :--------------: | :-------: | :---: |
-|   Admin Server   | 127.0.0.1 | 19000 |
-|      Stats       |  0.0.0.0  | 19001 |
-| Shutdown Manager |  0.0.0.0  | 19002 |
-|    Readiness     |  0.0.0.0  | 19003 |
+{{< boilerplate open-ports >}}
 
 {{% alert title="Next Steps" color="warning" %}}
 Envoy Gateway should now be successfully installed and running.  To experience more abilities of Envoy Gateway, refer to [Tasks](../tasks).
diff --git a/site/content/en/v1.3/install/install-yaml.md b/site/content/en/v1.3/install/install-yaml.md
index eac18063e..1fa0fcc29 100644
--- a/site/content/en/v1.3/install/install-yaml.md
+++ b/site/content/en/v1.3/install/install-yaml.md
@@ -1,6 +1,6 @@
 +++
 title = "Install with Kubernetes YAML"
-weight = -99
+weight = -98
 +++
 
 This task walks you through installing Envoy Gateway in your Kubernetes cluster.
@@ -11,22 +11,13 @@ installation, it is recommended that you use helm.
 
 ## Before you begin
 
-Envoy Gateway is designed to run in Kubernetes for production. The most essential requirements are:
-
-* Kubernetes 1.28 or later
-* The `kubectl` command-line tool
-
 {{% alert title="Compatibility Matrix" color="warning" %}}
 Refer to the [Version Compatibility Matrix](/news/releases/matrix) to learn more.
 {{% /alert %}}
 
-## Install with YAML
+{{< boilerplate kind-cluster >}}
 
-Envoy Gateway is typically deployed to Kubernetes from the command line. If you don't have Kubernetes, you should use `kind` to create one.
-
-{{% alert title="Developer Guide" color="primary" %}}
-Refer to the [Developer Guide](../../contributions/develop) to learn more.
-{{% /alert %}}
+## Install with YAML
 
 1. In your terminal, run the following command:
 
@@ -38,9 +29,9 @@ Refer to the [Developer Guide](../../contributions/develop) to learn more.
 
    Envoy Gateway should now be successfully installed and running, but in order to experience more abilities of Envoy Gateway, you can refer to [Tasks](/latest/tasks).
 
-## Upgrading from v1.2
+## Upgrading from a previous version
 
-Some manual migration steps are required to upgrade Envoy Gateway to v1.3.
+Some manual migration steps are required to upgrade Envoy Gateway.
 
 1. Update Gateway-API and Envoy Gateway CRDs:
 
@@ -55,3 +46,9 @@ kubectl apply --force-conflicts --server-side -f ./gateway-helm/crds/generated
 ```shell
 helm upgrade eg oci://docker.io/envoyproxy/gateway-helm --version {{< yaml-version >}} -n envoy-gateway-system
 ```
+
+{{< boilerplate open-ports >}}
+
+{{% alert title="Next Steps" color="warning" %}}
+Envoy Gateway should now be successfully installed and running.  To experience more abilities of Envoy Gateway, refer to [Tasks](../tasks).
+{{% /alert %}}


Test patch:
diff --git a/internal/gatewayapi/testdata/envoyproxy-tls-settings-invalid-ns.out.yaml b/internal/gatewayapi/testdata/envoyproxy-tls-settings-invalid-ns.out.yaml
index 7c872f644..98a08206a 100644
--- a/internal/gatewayapi/testdata/envoyproxy-tls-settings-invalid-ns.out.yaml
+++ b/internal/gatewayapi/testdata/envoyproxy-tls-settings-invalid-ns.out.yaml
@@ -20,11 +20,9 @@ backendTLSPolicies:
         namespace: envoy-gateway
       conditions:
       - lastTransitionTime: null
-        message: 'ClientCertificateRef Secret is not located in the same namespace
-          as Envoyproxy. Secret namespace: envoy-gateway-user-ns does not match Envoyproxy
-          namespace: envoy-gateway-system.'
-        reason: Invalid
-        status: "False"
+        message: Policy has been accepted.
+        reason: Accepted
+        status: "True"
         type: Accepted
       controllerName: gateway.envoyproxy.io/gatewayclass-controller
 gateways:
diff --git a/internal/gatewayapi/testdata/envoyproxy-tls-settings-invalid.out.yaml b/internal/gatewayapi/testdata/envoyproxy-tls-settings-invalid.out.yaml
index d4224abd7..775ff2586 100644
--- a/internal/gatewayapi/testdata/envoyproxy-tls-settings-invalid.out.yaml
+++ b/internal/gatewayapi/testdata/envoyproxy-tls-settings-invalid.out.yaml
@@ -20,10 +20,9 @@ backendTLSPolicies:
         namespace: envoy-gateway
       conditions:
       - lastTransitionTime: null
-        message: 'Failed to locate TLS secret for client auth: envoy-gateway-system/client-auth-not-found
-          specified in EnvoyProxy envoy-gateway-system/test.'
-        reason: Invalid
-        status: "False"
+        message: Policy has been accepted.
+        reason: Accepted
+        status: "True"
         type: Accepted
       controllerName: gateway.envoyproxy.io/gatewayclass-controller
 gateways:
diff --git a/site/content/en/latest/boilerplates/kind-cluster.md b/site/content/en/latest/boilerplates/kind-cluster.md
new file mode 100644
index 000000000..643bb28cb
--- /dev/null
+++ b/site/content/en/latest/boilerplates/kind-cluster.md
@@ -0,0 +1,6 @@
+Envoy Gateway is typically deployed in a Kubernetes cluster.
+If you don’t have one yet, you can use `kind` to create a local cluster for testing purposes.
+
+{{% alert title="Developer Guide" color="primary" %}}
+Refer to the [Developer Guide](../../contributions/develop) to learn more.
+{{% /alert %}}
diff --git a/site/content/en/latest/boilerplates/open-ports.md b/site/content/en/latest/boilerplates/open-ports.md
new file mode 100644
index 000000000..f193c2d2d
--- /dev/null
+++ b/site/content/en/latest/boilerplates/open-ports.md
@@ -0,0 +1,22 @@
+## Open Ports
+
+These are the ports used by Envoy Gateway and the managed Envoy Proxy.
+
+### Envoy Gateway
+
+|     Envoy Gateway     |  Address  | Port  | Configurable |
+| :-------------------: | :-------: | :---: | :----------: |
+| Xds EnvoyProxy Server |  0.0.0.0  | 18000 |      No      |
+| Xds RateLimit Server  |  0.0.0.0  | 18001 |      No      |
+|     Admin Server      | 127.0.0.1 | 19000 |     Yes      |
+|    Metrics Server     |  0.0.0.0  | 19001 |      No      |
+|     Health Check      | 127.0.0.1 | 8081  |      No      |
+
+### EnvoyProxy
+
+|   Envoy Proxy    |  Address  | Port  |
+| :--------------: | :-------: | :---: |
+|   Admin Server   | 127.0.0.1 | 19000 |
+|      Stats       |  0.0.0.0  | 19001 |
+| Shutdown Manager |  0.0.0.0  | 19002 |
+|    Readiness     |  0.0.0.0  | 19003 |
diff --git a/site/content/en/latest/install/install-argocd.md b/site/content/en/latest/install/install-argocd.md
new file mode 100644
index 000000000..b04ec5126
--- /dev/null
+++ b/site/content/en/latest/install/install-argocd.md
@@ -0,0 +1,128 @@
++++
+title = "Install with Argo CD"
+weight = -99
++++
+
+[Argo CD](https://argo-cd.readthedocs.io) is a declarative, GitOps continuous delivery tool for Kubernetes.
+Argo CD can be used to manage the deployment of Envoy Gateway on Kubernetes clusters.
+
+## Before you begin
+
+{{% alert title="Compatibility Matrix" color="warning" %}}
+Refer to the [Version Compatibility Matrix](/news/releases/matrix) to learn more.
+{{% /alert %}}
+
+{{< boilerplate kind-cluster >}}
+
+Argo CD must be installed in your Kubernetes cluster, and the argocd CLI must be available on your local machine.
+If you haven’t set it up yet, you can follow the [official installation guide](https://argo-cd.readthedocs.io/en/stable/operator-manual/installation/) to install Argo CD.
+
+## Install with Argo CD
+
+Create a new Argo CD Application that pulls the Envoy Gateway Helm chart as its source.
+
+```shell
+cat <<EOF | kubectl apply -f -
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: envoy-gateway
+  namespace: argocd
+spec:
+  project: default
+  source:
+    chart: gateway-helm
+    repoURL: docker.io/envoyproxy
+    targetRevision: {{< helm-version >}}
+  destination:
+    namespace: envoy-gateway-system
+    server: https://kubernetes.default.svc
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true
+    - ServerSideApply=true
+    automated:
+      prune: true
+      selfHeal: true
+EOF
+```
+
+**Note**:
+
+* Set `ServerSideApply` to `true` to enable Kubernetes [server-side apply](https://kubernetes.io/docs/reference/using-api/server-side-apply/). This helps avoid the 262,144-byte annotation size limit.
+* For simplicity, we apply the Application resource directly to the cluster.
+In a production environment, it’s recommended to store this configuration in a Git repository and manage it using another Argo CD Application that uses Git as its source — following a GitOps workflow.
+
+Wait for Envoy Gateway to become available:
+
+```shell
+kubectl wait --timeout=5m -n envoy-gateway-system deployment/envoy-gateway --for=condition=Available
+```
+
+Install the GatewayClass, Gateway, HTTPRoute and example app:
+
+```shell
+kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/{{< yaml-version >}}/quickstart.yaml -n default
+```
+
+**Note**: [`quickstart.yaml`] defines that Envoy Gateway will listen for
+traffic on port 80 on its globally-routable IP address, to make it easy to use
+browsers to test Envoy Gateway. When Envoy Gateway sees that its Listener is
+using a privileged port (<1024), it will map this internally to an
+unprivileged port, so that Envoy Gateway doesn't need additional privileges.
+It's important to be aware of this mapping, since you may need to take it into
+consideration when debugging.
+
+[`quickstart.yaml`]: https://github.com/envoyproxy/gateway/releases/download/{{< yaml-version >}}/quickstart.yaml
+
+
+## Helm chart customizations
+
+You can customize the Envoy Gateway installation by using the Helm chart values.
+
+{{% alert title="Helm Chart Values" color="primary" %}}
+If you want to know all the available fields inside the values.yaml file, please see the [Helm Chart Values](./gateway-helm-api).
+{{% /alert %}}
+
+Below is an example of how to customize the Envoy Gateway installation by using the `valuesObject` field in the Argo CD Application.
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: envoy-gateway
+  namespace: argocd
+spec:
+  project: default
+  source:
+    helm:
+      valuesObject:
+        deployment:
+          envoyGateway:
+            resources:
+              limits:
+                cpu: 700m
+                memory: 256Mi
+    chart: gateway-helm
+    path: gateway-helm
+    repoURL: docker.io/envoyproxy
+    targetRevision: {{< helm-version >}}
+  destination:
+    namespace: envoy-gateway-system
+    server: https://kubernetes.default.svc
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true
+    - ServerSideApply=true
+    automated:
+      prune: true
+      selfHeal: true
+```
+
+Argo CD supports multiple ways of specifying Helm chart values, you can find more details in the [Argo CD documentation](https://argo-cd.readthedocs.io/en/stable/user-guide/helm/#helm).
+
+{{< boilerplate open-ports >}}
+
+{{% alert title="Next Steps" color="warning" %}}
+Envoy Gateway should now be successfully installed and running.  To experience more abilities of Envoy Gateway, refer to [Tasks](../tasks).
+{{% /alert %}}
diff --git a/site/content/en/latest/install/install-helm.md b/site/content/en/latest/install/install-helm.md
index d146194d3..34b640c83 100644
--- a/site/content/en/latest/install/install-helm.md
+++ b/site/content/en/latest/install/install-helm.md
@@ -3,7 +3,7 @@ title = "Install with Helm"
 weight = -100
 +++
 
-[Helm](https://helm.sh) is a package manager for Kubernetes that automates the release and management of software on Kubernetes. 
+[Helm](https://helm.sh) is a package manager for Kubernetes that automates the release and management of software on Kubernetes.
 
 Envoy Gateway can be installed via a Helm chart with a few simple steps, depending on if you are deploying for the first time, upgrading Envoy Gateway from an existing installation, or migrating from Envoy Gateway.
 
@@ -13,6 +13,8 @@ Envoy Gateway can be installed via a Helm chart with a few simple steps, dependi
 Refer to the [Version Compatibility Matrix](/news/releases/matrix) to learn more.
 {{% /alert %}}
 
+{{< boilerplate kind-cluster >}}
+
 The Envoy Gateway Helm chart is hosted by DockerHub.
 
 It is published at `oci://docker.io/envoyproxy/gateway-helm`.
@@ -25,12 +27,6 @@ You can visit [Envoy Gateway Helm Chart](https://hub.docker.com/r/envoyproxy/gat
 
 ## Install with Helm
 
-Envoy Gateway is typically deployed to Kubernetes from the command line. If you don't have Kubernetes, you should use `kind` to create one.
-
-{{% alert title="Developer Guide" color="primary" %}}
-Refer to the [Developer Guide](../../contributions/develop) to learn more.
-{{% /alert %}}
-
 Install the Gateway API CRDs and Envoy Gateway:
 
 ```shell
@@ -59,11 +55,11 @@ consideration when debugging.
 
 [`quickstart.yaml`]: https://github.com/envoyproxy/gateway/releases/download/{{< yaml-version >}}/quickstart.yaml
 
-## Upgrading from a previous version
+## Upgrading from the previous version
 
 [Helm](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/#some-caveats-and-explanations) does not update CRDs
 that live in the `/crds` folder in the Helm Chart. So you will manually need to update the CRDs.
-Follow the steps outlined in [this](./install-yaml/#upgrading-from-v1.2) section if you're upgrading from a previous version.
+Follow the steps outlined in [this](./install-yaml/#upgrading-from-a-previous-version) section if you're upgrading from a previous version.
 
 ## Helm chart customizations
 
@@ -124,28 +120,7 @@ You can use the below command to install the envoy gateway using values.yaml fil
 helm install eg oci://docker.io/envoyproxy/gateway-helm --version {{< helm-version >}} -n envoy-gateway-system --create-namespace -f values.yaml
 ```
 
-## Open Ports
-
-These are the ports used by Envoy Gateway and the managed Envoy Proxy.
-
-### Envoy Gateway
-
-|     Envoy Gateway     |  Address  | Port  | Configurable |
-| :-------------------: | :-------: | :---: | :----------: |
-| Xds EnvoyProxy Server |  0.0.0.0  | 18000 |      No      |
-| Xds RateLimit Server  |  0.0.0.0  | 18001 |      No      |
-|     Admin Server      | 127.0.0.1 | 19000 |     Yes      |
-|    Metrics Server     |  0.0.0.0  | 19001 |      No      |
-|     Health Check      | 127.0.0.1 | 8081  |      No      |
-
-### EnvoyProxy
-
-|   Envoy Proxy    |  Address  | Port  |
-| :--------------: | :-------: | :---: |
-|   Admin Server   | 127.0.0.1 | 19000 |
-|      Stats       |  0.0.0.0  | 19001 |
-| Shutdown Manager |  0.0.0.0  | 19002 |
-|    Readiness     |  0.0.0.0  | 19003 |
+{{< boilerplate open-ports >}}
 
 {{% alert title="Next Steps" color="warning" %}}
 Envoy Gateway should now be successfully installed and running.  To experience more abilities of Envoy Gateway, refer to [Tasks](../tasks).
diff --git a/site/content/en/latest/install/install-yaml.md b/site/content/en/latest/install/install-yaml.md
index eac18063e..578e5036d 100644
--- a/site/content/en/latest/install/install-yaml.md
+++ b/site/content/en/latest/install/install-yaml.md
@@ -1,6 +1,6 @@
 +++
 title = "Install with Kubernetes YAML"
-weight = -99
+weight = -98
 +++
 
 This task walks you through installing Envoy Gateway in your Kubernetes cluster.
@@ -11,22 +11,13 @@ installation, it is recommended that you use helm.
 
 ## Before you begin
 
-Envoy Gateway is designed to run in Kubernetes for production. The most essential requirements are:
-
-* Kubernetes 1.28 or later
-* The `kubectl` command-line tool
-
 {{% alert title="Compatibility Matrix" color="warning" %}}
 Refer to the [Version Compatibility Matrix](/news/releases/matrix) to learn more.
 {{% /alert %}}
 
-## Install with YAML
+{{< boilerplate kind-cluster >}}
 
-Envoy Gateway is typically deployed to Kubernetes from the command line. If you don't have Kubernetes, you should use `kind` to create one.
-
-{{% alert title="Developer Guide" color="primary" %}}
-Refer to the [Developer Guide](../../contributions/develop) to learn more.
-{{% /alert %}}
+## Install with YAML
 
 1. In your terminal, run the following command:
 
@@ -38,9 +29,9 @@ Refer to the [Developer Guide](../../contributions/develop) to learn more.
 
    Envoy Gateway should now be successfully installed and running, but in order to experience more abilities of Envoy Gateway, you can refer to [Tasks](/latest/tasks).
 
-## Upgrading from v1.2
+## Upgrading from the previous version
 
-Some manual migration steps are required to upgrade Envoy Gateway to v1.3.
+Some manual migration steps are required to upgrade Envoy Gateway.
 
 1. Update Gateway-API and Envoy Gateway CRDs:
 
@@ -55,3 +46,9 @@ kubectl apply --force-conflicts --server-side -f ./gateway-helm/crds/generated
 ```shell
 helm upgrade eg oci://docker.io/envoyproxy/gateway-helm --version {{< yaml-version >}} -n envoy-gateway-system
 ```
+
+{{< boilerplate open-ports >}}
+
+{{% alert title="Next Steps" color="warning" %}}
+Envoy Gateway should now be successfully installed and running.  To experience more abilities of Envoy Gateway, refer to [Tasks](../tasks).
+{{% /alert %}}