Add documentation on Gateway customization (#16368)

* Add documentation on Gateway customization

docs for https://github.com/istio/istio/pull/55283

* fix lint & tests

---------

Co-authored-by: Craig Box <craig.box@gmail.com>

content/en/docs/tasks/traffic-management/ingress/gateway-api/index.md

@@ -189,22 +189,13 @@ In the example above, you did not need to install an ingress gateway `Deployment
 In the default configuration, a gateway `Deployment` and `Service` is automatically provisioned based on the `Gateway` configuration.
 For advanced use cases, manual deployment is still allowed.
 
-### Automated Deployment
+### Automated deployment
 
-By default, each `Gateway` will automatically provision a `Service` and `Deployment` of the same name.
+By default, each `Gateway` will automatically provision a `Service` and `Deployment`.
+These will be named `<Gateway name>-<GatewayClass name>` (with the exception of the `istio-waypoint` `GatewayClass`, which does not append a suffix).
 These configurations will be updated automatically if the `Gateway` changes (for example, if a new port is added).
 
-These resources can be customized in a few ways:
+These resources can be customized by using the `infrastructure` field:
-
-* Annotations and labels on the `Gateway` will be copied to the `Service` and `Deployment`.
-  This allows configuring things such as [Internal load balancers](https://kubernetes.io/docs/concepts/services-networking/service/#internal-load-balancer) that read from these fields.
-* Istio offers an additional annotation to configure the generated resources:
-
-    |Annotation|Purpose|
-    |----------|-------|
-    |`networking.istio.io/service-type`|Controls the `Service.spec.type` field. For example, set to `ClusterIP` to not expose the service externally. The default is `LoadBalancer`.|
-
-* The `Service.spec.loadBalancerIP` field can be explicit set by configuring the `addresses` field:
 
 {{< text yaml >}}
 apiVersion: gateway.networking.k8s.io/v1
@@ -212,17 +203,94 @@ These resources can be customized in a few ways:
 metadata:
   name: gateway
 spec:
-      addresses:
+  infrastructure:
-      - value: 192.0.2.0
+    annotations:
-        type: IPAddress
+      some-key: some-value
-    ...
+    labels:
+      key: value
+    parametersRef:
+      group: ""
+      kind: ConfigMap
+      name: gw-options
+  gatewayClassName: istio
 {{< /text >}}
 
-Note: only one address may be specified.
+Key-value pairs under `labels` and `annotations` will be copied onto the generated resources.
+The `parametersRef` can be used to fully customize the generated resources.
+This must reference a `ConfigMap` in the same namespace as the `Gateway`.
 
-* (Advanced) The generated Pod configuration can be configured by [Custom Injection Templates](/docs/setup/additional-setup/sidecar-injection/#custom-templates-experimental).
+An example configuration:
 
-#### Resource Attachment and Scaling
+{{< text yaml >}}
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: gw-options
+data:
+  horizontalPodAutoscaler: |
+    spec:
+      minReplicas: 2
+      maxReplicas: 2
+
+  deployment: |
+    metadata:
+      annotations:
+      additional-annotation: some-value
+    spec:
+      replicas: 4
+      template:
+        spec:
+          containers:
+          - name: istio-proxy
+            resources:
+              requests:
+                cpu: 1234m
+
+  service: |
+    spec:
+      ports:
+      - "\$patch": delete
+        port: 15021
+{{< /text >}}
+
+These configurations will be overlaid on top of the generated resources using a [Strategic Merge Patch](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-api-machinery/strategic-merge-patch.md) strategy.
+The following keys are valid:
+* `service`
+* `deployment`
+* `serviceAccount`
+* `horizontalPodAutoscaler`
+* `podDisruptionBudget`
+
+{{< tip >}}
+A `HorizontalPodAutoscaler` and `PodDisruptionBudget` are not created by default.
+However, if the corresponding field is present in the customization, they will be created.
+{{< /tip >}}
+
+#### GatewayClass defaults
+
+Defaults for all `Gateway`s can be configured for each `GatewayClass`.
+This is done by a `ConfigMap` with the label `gateway.istio.io/defaults-for-class: <gateway class name>`.
+This `ConfigMap` must be in the [root namespace](/docs/reference/config/istio.mesh.v1alpha1/#MeshConfig-root_namespace) (typically, `istio-system`).
+Only one `ConfigMap` per `GatewayClass` is allowed.
+This `ConfigMap` takes the same format as the `ConfigMap` for a `Gateway`.
+
+Customization may be present on both a `GatewayClass` and a `Gateway`.
+If both are present, the `Gateway` customization applies after the `GatewayClass` customization.
+
+This `ConfigMap` can also be created at installation time. For example:
+
+{{< text yaml >}}
+kind: IstioOperator
+spec:
+  values:
+    gatewayClasses:
+      istio:
+        deployment:
+          spec:
+            replicas: 2
+{{< /text >}}
+
+#### Resource attachment and scaling
 
 Resources can be *attached* to a `Gateway` to customize it.
 However, most Kubernetes resources do not currently support attaching directly to a `Gateway`, but they can be attached to the corresponding generated `Deployment` and `Service` instead.
@@ -282,7 +350,7 @@ spec:
       gateway.networking.k8s.io/gateway-name: gateway
 {{< /text >}}
 
-### Manual Deployment
+### Manual deployment
 
 If you do not want to have an automated deployment, a `Deployment` and `Service` can be [configured manually](/docs/setup/additional-setup/gateway/).
 

content/en/docs/tasks/traffic-management/ingress/gateway-api/snips.sh

@@ -147,10 +147,59 @@ kind: Gateway
 metadata:
   name: gateway
 spec:
-  addresses:
+  infrastructure:
-  - value: 192.0.2.0
+    annotations:
-    type: IPAddress
+      some-key: some-value
-...
+    labels:
+      key: value
+    parametersRef:
+      group: ""
+      kind: ConfigMap
+      name: gw-options
+  gatewayClassName: istio
+ENDSNIP
+
+! IFS=$'\n' read -r -d '' snip_automated_deployment_2 <<\ENDSNIP
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: gw-options
+data:
+  horizontalPodAutoscaler: |
+    spec:
+      minReplicas: 2
+      maxReplicas: 2
+
+  deployment: |
+    metadata:
+      annotations:
+      additional-annotation: some-value
+    spec:
+      replicas: 4
+      template:
+        spec:
+          containers:
+          - name: istio-proxy
+            resources:
+              requests:
+                cpu: 1234m
+
+  service: |
+    spec:
+      ports:
+      - "\$patch": delete
+        port: 15021
+ENDSNIP
+
+! IFS=$'\n' read -r -d '' snip_gatewayclass_defaults_1 <<\ENDSNIP
+kind: IstioOperator
+spec:
+  values:
+    gatewayClasses:
+      istio:
+        deployment:
+          spec:
+            replicas: 2
 ENDSNIP
 
 ! IFS=$'\n' read -r -d '' snip_resource_attachment_and_scaling_1 <<\ENDSNIP