docs: Add documentation about the new config format (#1247) (#1257)

* docs: Add documentation about the new config format (#1247)

* chore: Doc formatting

* chore: Remove default values

config/400-config-istio.yaml

@@ -41,25 +41,62 @@ data:
     # this example block and unindented to be in the data block
     # to actually change the configuration.
 
-    # A gateway and Istio service to serve external traffic.
-    # The configuration format should be
-    # `gateway.{{gateway_namespace}}.{{gateway_name}}: "{{ingress_name}}.{{ingress_namespace}}.svc.cluster.local"`.
-    # The {{gateway_namespace}} is optional; when it is omitted, the system will search for
-    # the gateway in the serving system namespace `knative-serving`
+
+    # external-gateways defines a gateway and Istio service to serve external traffic.
+    # It is the new and preferred way to define the configuration.
+    # The format is as follow:
+    # ```
+    # external-gateways: |
+    #   - name: {{gateway_name}}
+    #     namespace: {{gateway_namespace}}
+    #     service: {{ingress_name}}.{{ingress_namespace}}.svc.cluster.local
+    # ```
+    # name, namespace & service are mandatory and can't be empty.
+    external-gateways: |
+      - name: knative-ingress-gateway
+        namespace: knative-serving
+        service: istio-ingressgateway.istio-system.svc.cluster.local
+    #
+    #
+    # The old format has the following pattern:
+    # ```
+    # gateway.{{gateway_namespace}}.{{gateway_name}}: "{{ingress_name}}.{{ingress_namespace}}.svc.cluster.local"
+    # ```
+    # Please use the new configuration format `external-gateways` for future compatibility.
+    # This configuration format is ignored if either `external-gateways` or `local-gateways` is defined.
     gateway.knative-serving.knative-ingress-gateway: "istio-ingressgateway.istio-system.svc.cluster.local"
 
-    # A cluster local gateway to allow pods outside of the mesh to access
-    # Services and Routes not exposing through an ingress.  If the users
+
+    # local-gateways defines a cluster local gateway to allow pods outside of the mesh to access
+    # Services and Routes not exposing through an ingress. If the users
     # do have a service mesh setup, this isn't required and can be removed.
     #
     # An example use case is when users want to use Istio without any
-    # sidecar injection (like Knative's istio-ci-no-mesh.yaml).  Since every pod
-    # is outside of the service mesh in that case, a cluster-local  service
+    # sidecar injection (like Knative's istio-ci-no-mesh.yaml). Since every pod
+    # is outside of the service mesh in that case, a cluster-local service
     # will need to be exposed to a cluster-local gateway to be accessible.
-    # The configuration format should be `local-gateway.{{local_gateway_namespace}}.
-    # {{local_gateway_name}}: "{{cluster_local_gateway_name}}.
-    # {{cluster_local_gateway_namespace}}.svc.cluster.local"`. The
-    # {{local_gateway_namespace}} is optional; when it is omitted, the system
-    # will search for the local gateway in the serving system namespace
-    # `knative-serving`
+    #
+    # It is the new and preferred way to define the configuration.
+    # The format is as follow:
+    # ```
+    # local-gateways: |
+    #   - name: {{local_gateway_name}}
+    #     namespace: {{local_gateway_namespace}}
+    #     service: {{cluster_local_gateway_name}}.{{cluster_local_gateway_namespace}}.svc.cluster.local
+    # ```
+    # name, namespace & service are mandatory and can't be empty.
+    # Only one local gateway can be specified.
+    local-gateways: |
+      - name: knative-local-gateway
+        namespace: knative-serving
+        service: knative-local-gateway.istio-system.svc.cluster.local
+    #
+    #
+    # The old format has the following pattern:
+    # ```
+    # local-gateway.{{local_gateway_namespace}}.{{local_gateway_name}}:
+    # "{{cluster_local_gateway_name}}.{{cluster_local_gateway_namespace}}.svc.cluster.local"
+    # ```
+    # Please use the new configuration format `local-gateways` for future compatibility.
+    # This configuration format is ignored if either `external-gateways` or `local-gateways` is defined.
     local-gateway.knative-serving.knative-local-gateway: "knative-local-gateway.istio-system.svc.cluster.local"