docs(managing-ingress): rewrite Gateway page to Managing Ingress Traffic

app/_data/docs_nav_kuma_dev.yml

@@ -189,13 +189,23 @@ items:
               url: "/policies/service-health-probes/#kubernetes"
             - text: Universal probes
               url: "/policies/service-health-probes/#universal-probes"
-      - text: Gateway # This will change a lot with upcoming "managing ingress traffic PR"
-        url: /explore/gateway/
+      - title: Managing incoming traffic with gateways
+        group: true
         items:
-          - text: Delegated
-            url: "/explore/gateway/#delegated"
-          - text: Builtin
-            url: "/explore/gateway/#builtin"
+          - text: How ingress works in Kuma
+            url: "/using-mesh/managing-ingress-traffic/overview/"
+          - text: Delegated gateways
+            url: "/using-mesh/managing-ingress-traffic/delegated/"
+          - text: Built-in gateways
+            url: "/using-mesh/managing-ingress-traffic/builtin/"
+          - text: Running built-in gateway pods on Kubernetes
+            url: "/using-mesh/managing-ingress-traffic/builtin-k8s/"
+          - text: Configuring built-in listeners
+            url: "/using-mesh/managing-ingress-traffic/builtin-listeners/"
+          - text: Configuring built-in routes
+            url: "/using-mesh/managing-ingress-traffic/builtin-routes/"
+          - text: Using the Kubernetes Gateway API
+            url: "/using-mesh/managing-ingress-traffic/gateway-api/"
       - text: Observability
         url: /explore/observability/
         items:
@@ -255,24 +265,6 @@ items:
         url: /policies/applying-policies/
       - text: Understanding TargetRef policies
         url: "/policies/targetref"
-      - text: MeshGateway
-        url: /policies/meshgateway/
-        items:
-          - text: TLS Termination
-            url: "/policies/meshgateway/#tls-termination"
-      - text: MeshGatewayRoute
-        url: /policies/meshgatewayroute/
-        items:
-          - text: Listener tags
-            url: "/policies/meshgatewayroute/#listener-tags"
-          - text: Matching
-            url: "/policies/meshgatewayroute/#matching"
-          - text: Filters
-            url: "/policies/meshgatewayroute/#filters"
-          - text: Reference
-            url: "/policies/meshgatewayroute/#reference"
-      - text: MeshGatewayInstance
-        url: /policies/meshgatewayinstance/
       - text: MeshAccessLog
         url: /policies/meshaccesslog/
         items:
@@ -442,6 +434,8 @@ items:
             url: /policies/rate-limit/
           - text: Virtual Outbound
             url: /policies/virtual-outbound/
+          - text: MeshGatewayRoute
+            url: /policies/meshgatewayroute/
   - title: Guides
     group: true
     items:

app/_src/policies/meshgateway.md

@@ -2,7 +2,7 @@
 title: MeshGateway
 ---
 
-`MeshGateway` is a policy used to configure [{{site.mesh_product_name}}'s builtin gateway](/docs/{{ page.version }}/explore/gateway#builtin).
+`MeshGateway` is a policy used to configure {% if_version gte:2.6.x %}[{{site.mesh_product_name}}'s builtin gateway](/docs/{{ page.version }}/using-mesh/managing-ingress-traffic/builtin){% endif_version %}{% if_version lte:2.5.x %}[{{site.mesh_product_name}}'s builtin gateway](/docs/{{ page.version }}/explore/gateway#builtin){% endif_version %}.
 It is used in combination with [`MeshGatewayRoute`](/docs/{{ page.version }}/policies/meshgatewayroute).
 
 A builtin gateway `Dataplane` with no additional configuration does nothing.

app/_src/policies/meshgatewayinstance.md

@@ -2,7 +2,7 @@
 title: MeshGatewayInstance
 ---
 
-`MeshGatewayInstance` is a Kubernetes-only resource for deploying [{{site.mesh_product_name}}'s builtin gateway](/docs/{{ page.version }}/explore/gateway#builtin).
+`MeshGatewayInstance` is a Kubernetes-only resource for deploying {% if_version gte:2.6.x %}[{{site.mesh_product_name}}'s builtin gateway](/docs/{{ page.version }}/using-mesh/managing-ingress-traffic/builtin){% endif_version %}{% if_version lte:2.5.x %}[{{site.mesh_product_name}}'s builtin gateway](/docs/{{ page.version }}/explore/gateway#builtin){% endif_version %}.
 
 `MeshGateway` and `MeshGatewayRoute` allow specifying builtin gateway
 listener and route configuration but don't handle deploying `kuma-dp`

app/_src/policies/meshgatewayroute.md

@@ -7,13 +7,13 @@ New to Kuma? Don't use this, check the [`MeshHTTPRoute` policy](/docs/{{ page.ve
 {% endwarning %}
 {% endif_version %}
 
-`MeshGatewayRoute` is a policy used to configure [{{site.mesh_product_name}}'s builtin gateway](/docs/{{ page.version }}/explore/gateway#builtin).
-It is used in combination with [`MeshGateway`](/docs/{{ page.version }}/policies/meshgateway).
+`MeshGatewayRoute` is a policy used to configure {% if_version gte:2.6.x %}[{{site.mesh_product_name}}'s builtin gateway](/docs/{{ page.version }}/using-mesh/managing-ingress-traffic/builtin){% endif_version %}{% if_version lte:2.5.x %}[{{site.mesh_product_name}}'s builtin gateway](/docs/{{ page.version }}/explore/gateway#builtin){% endif_version %}.
+It is used in combination with {% if_version gte:2.6.x %}[`MeshGateway`](/docs/{{ page.version }}/using-mesh/managing-ingress-traffic/builtin-listeners){% endif_version %}{% if_version lte:2.5.x %}[`MeshGateway`](/docs/{{ page.version }}/policies/meshgateway){% endif_version %}.
 
 `MeshGatewayRoute` is a new {{site.mesh_product_name}} dataplane policy that replaces TrafficRoute for {{site.mesh_product_name}} Gateway.
 It configures how a gateway should process network traffic.
 At the moment, it targets HTTP routing use cases.
-`MeshGatewayRoutes` are attached to gateways by matching their selector to the [`MeshGateway`](/docs/{{ page.version }}/policies/meshgateway) listener tags. This requires the `kuma.io/service` tag and, optionally, additional tags to match specific `MeshGateway` listeners.
+`MeshGatewayRoutes` are attached to gateways by matching their selector to the {% if_version gte:2.6.x %}[`MeshGateway`](/docs/{{ page.version }}/using-mesh/managing-ingress-traffic/builtin-listeners){% endif_version %}{% if_version lte:2.5.x %}[`MeshGateway`](/docs/{{ page.version }}/policies/meshgateway){% endif_version %} listener tags. This requires the `kuma.io/service` tag and, optionally, additional tags to match specific `MeshGateway` listeners.
 
 The following `MeshGatewayRoute` routes traffic to the `backend` service and attaches to any listeners tagged with `vhost=foo.example.com` that attach to builtin gateways with `kuma.io/service: edge-gateway`.
 

app/_src/production/deployment/multi-zone.md

@@ -55,7 +55,7 @@ a DNS entry with the format `<kuma.io/service>.mesh`, and will listen for traffi
 [`VirtualOutbounds`](/docs/{{ page.version }}/policies/virtual-outbound)s enable you to customize the listening port and how the DNS name for these services looks.
 
 {% tip %}
-A zone ingress is not an API gateway. It is only used for cross-zone communication within a mesh. API gateways are supported in {{site.mesh_product_name}} [gateway mode](/docs/{{ page.version }}/explore/gateway) and can be deployed in addition to zone ingresses.
+A zone ingress is not an API gateway. It is only used for cross-zone communication within a mesh. API gateways are supported in {{site.mesh_product_name}} {% if_version gte:2.6.x %}[gateway mode](/docs/{{ page.version }}/using-mesh/managing-ingress-traffic/overview){% endif_version %}{% if_version lte:2.5.x %}[gateway mode](/docs/{{ page.version }}/explore/gateway){% endif_version %} and can be deployed in addition to zone ingresses.
 {% endtip %}
 
 ## Components of a multi-zone deployment

app/_src/production/mesh.md

@@ -26,7 +26,7 @@ Besides the ability of being able to create virtual service mesh, a `Mesh` resou
 * {% if_version lte:2.1.x %}[Zone Egress](/docs/{{ page.version }}/explore/zoneegress){% endif_version %}{% if_version gte:2.2.x %}[Zone Egress](/docs/{{ page.version }}/production/cp-deployment/zoneegress/){% endif_version %}, to setup if `ZoneEgress` should be used for cross zone and external service communication.
 * [Non-mesh traffic](/docs/{{ page.version }}/networking/non-mesh-traffic), to setup if `passthrough` mode should be used for the non-mesh traffic.
 
-When [Mutual TLS](/docs/{{ page.version }}/policies/mutual-tls/) is enabled in `builtin` mode, each `Mesh` will provision its own CA root certificate and key unless we explicitly decide to use the same CA by sharing the same certificate and key across multiple meshes. When the CAs of our Meshes are different, data plane proxies from one `Mesh` will not be able to consume data plane proxies belonging to another `Mesh` and an intermediate API Gateway must be used in order to enable cross-mesh communication. {{site.mesh_product_name}} supports a [gateway mode](/docs/{{ page.version }}/explore/gateway) to make this happen.
+When [Mutual TLS](/docs/{{ page.version }}/policies/mutual-tls/) is enabled in `builtin` mode, each `Mesh` will provision its own CA root certificate and key unless we explicitly decide to use the same CA by sharing the same certificate and key across multiple meshes. When the CAs of our Meshes are different, data plane proxies from one `Mesh` will not be able to consume data plane proxies belonging to another `Mesh` and an intermediate API Gateway must be used in order to enable cross-mesh communication. {{site.mesh_product_name}} supports a {% if_version gte:2.6.x %}[{{site.mesh_product_name}}'s builtin gateway](/docs/{{ page.version }}/using-mesh/managing-ingress-traffic/overview){% endif_version %}{% if_version lte:2.5.x %}[{{site.mesh_product_name}}'s builtin gateway](/docs/{{ page.version }}/explore/gateway){% endif_version %}. to make this happen.
 
 ## Usage
 

app/_src/using-mesh/managing-ingress-traffic/builtin-k8s.md

@@ -0,0 +1,100 @@
+---
+title: Running built-in gateway pods on Kubernetes
+---
+
+`MeshGatewayInstance` is a Kubernetes-only resource for deploying [{{site.mesh_product_name}}'s builtin gateway](/docs/{{ page.version }}/using-mesh/managing-ingress-traffic/builtin).
+
+[`MeshGateway`](/docs/{{ page.version }}/using-mesh/managing-ingress-traffic/builtin-listeners) and [MeshHTTPRoute](/docs/{{ page.version }}/policies/meshhttproute)/[MeshTCPRoute](/docs/{{ page.version }}/policies/meshtcproute) allow specifying builtin gateway
+listener and route configuration but don't handle deploying `kuma-dp`
+instances that listen and serve traffic.
+
+Kuma offers `MeshGatewayInstance` to manage a Kubernetes `Deployment` and `Service`
+that together provide service capacity for the `MeshGateway` with the matching `kuma.io/service` tag.
+
+{% tip %}
+If you're not using the `default` `Mesh`, you'll need to _label_ the
+`MeshGatewayInstance` using `kuma.io/mesh`.
+{% endtip %}
+
+Consider the following example:
+
+```yaml
+apiVersion: kuma.io/v1alpha1
+kind: MeshGatewayInstance
+metadata:
+  name: edge-gateway
+  namespace: default
+  labels:
+    kuma.io/mesh: default # only necessary if not using default Mesh
+spec:
+  replicas: 2
+  serviceType: LoadBalancer
+  tags:
+    kuma.io/service: edge-gateway
+```
+
+Once a `MeshGateway` exists with `kuma.io/service: edge-gateway`, the control plane creates a new `Deployment` in the `default` namespace.
+This `Deployment` deploys 2 replicas of `kuma-dp` and corresponding builtin gateway `Dataplane` running with `kuma.io/service: edge-gateway`.
+The control plane also creates a new `Service` to send network traffic to the builtin `Dataplane` pods.
+The `Service` is of type `LoadBalancer`, and its ports are automatically adjusted to match the listeners on the corresponding `MeshGateway`.
+
+## Customization
+
+Additional customization of the generated `Service` or `Pods` is possible via `spec.serviceTemplate` and `spec.podTemplate`.
+For example, you can add annotations and/or labels to the generated objects:
+
+```yaml
+spec:
+  replicas: 1
+  serviceType: LoadBalancer
+  tags:
+    kuma.io/service: edge-gateway
+  resources:
+    limits: ...
+    requests: ...
+  serviceTemplate:
+    metadata:
+      annotations:
+        service.beta.kubernetes.io/aws-load-balancer-internal: "true"
+    spec:
+      loadBalancerIP: ...
+  podTemplate:
+    metadata:
+      labels:
+        app-name: my-app
+        ...
+```
+
+You can also modify several security-related parameters for the generated `Pods` or specify a `loadBalancerIP` for the `Service`:
+
+```yaml
+spec:
+  replicas: 1
+  serviceType: LoadBalancer
+  tags:
+    kuma.io/service: edge-gateway
+  resources:
+    limits: ...
+    requests: ...
+  serviceTemplate:
+    metadata:
+      labels:
+        svc-id: "19-001"
+    spec:
+      loadBalancerIP: ...
+  podTemplate:
+    metadata:
+      annotations:
+        app-monitor: "false"
+    spec:
+      serviceAccountName: my-sa
+      securityContext:
+        fsGroup: ...
+      container:
+        securityContext:
+          readOnlyRootFilesystem: true
+```
+
+## Schema
+
+{% json_schema kuma.io_meshgatewayinstances type=crd %}