docs(filters): illustrate and describe the filterRef array in the VKC resource (kroxylicious#3219)

* docs(filters): illustrate and describe the filterRef array in the VKC resource.

Signed-off-by: Keith Wall <kwall@apache.org>

* Apply suggestions from code review

Co-authored-by: PaulRMellor <47596553+PaulRMellor@users.noreply.github.com>
Signed-off-by: Keith Wall <kwall@apache.org>

* word smithing

Signed-off-by: Keith Wall <kwall@apache.org>

---------

Signed-off-by: Keith Wall <kwall@apache.org>
Co-authored-by: PaulRMellor <47596553+PaulRMellor@users.noreply.github.com>

Author: k-wall

kroxylicious-docs/docs/_modules/configuring/con-virtualkafkacluster-overview.adoc

@@ -15,12 +15,16 @@ The virtual cluster references the following resources, which must be in the sam
 * A `KafkaProxy` resource that the proxy is part of.
 * One or more `KafkaProxyIngress` resources that expose the virtual cluster to Kafka clients and provide virtual-cluster-specific configuration to the ingress (such as TLS certificates and other parameters).
 * A `KafkaService` resource that defines the backend Kafka cluster.
-* Zero or more `KafkaProtocolFilter` resources that apply filters to the Kafka protocol traffic passing between clients and the backend Kafka cluster.
+* One or more `KafkaProtocolFilter` resources that filter the Kafka protocol traffic between clients and the backend Kafka cluster.
+The order of the filters in the `filterRefs` array defines the order that the filters are applied.
+Client requests pass through the filters starting at index `0`, then `1`, and continuing to index `n`.
+Broker responses pass through the same filters in the reverse order.
+If the `filterRefs` array is empty (or null), the traffic will pass through the cluster unchanged.
 
-This example shows a `VirtualKafkaCluster`, exposing it to Kafka clients running on the same Kubernetes cluster.
-It uses plain TCP (as opposed to TLS) as the transport protocol.
+The following example shows configuration for a `VirtualKafkaCluster` that is exposed it to Kafka clients running on the same Kubernetes cluster.
+Protocol traffic is filtered by the `my-filter` filter.
 
-.Example `VirtualKafkaCluster` configuration with single `clusterIP` ingress
+.Example `VirtualKafkaCluster` configuration with a single ingress and filter.
 [source,yaml]
 ----
 kind: VirtualKafkaCluster
@@ -36,16 +40,21 @@ spec:
   ingresses:
     - ingressRef: # <3>
         name: cluster-ip
+  filterRefs: # <4>
+    - name: my-filter
+
 ----
 <1> Identifies the `KafkaProxy` resource that this virtual cluster is part of.
-<2> The `KafkaService` that defines the Kafka cluster proxied by the virtual cluster.
-<3> Ingresses that expose the virtual cluster.
+<2> Specifies the `KafkaService` that defines the Kafka cluster proxied by the virtual cluster.
+<3> Defines the ingresses that expose the virtual cluster.
   Each ingress references a `KafkaProxyIngress` by name.
+<4> Specifies the list of filters applied to Kafka protocol traffic.
 
-This example shows a `VirtualKafkaCluster`, exposing it to Kafka clients running both on and off-cluster, both using TLS.
+The following example shows configuration for a `VirtualKafkaCluster` that is exposed to Kafka clients running both on and off the cluster, using TLS.
 Because TLS is used, the ingress configuration must reference a TLS server certificate.
+This example has two filters.
 
-.Example `VirtualKafkaCluster` configuration with two ingresses using TLS
+.Example `VirtualKafkaCluster` configuration with two TLS-enabled ingresses
 [source,yaml]
 ----
 kind: VirtualKafkaCluster
@@ -69,9 +78,12 @@ spec:
         certificateRef:
           name: 'external-server-cert' # <2>
           kind: Secret
+  filterRefs:
+    - name: my-filter-1
+    - name: my-filter-2
 ----
-<1> Reference to a secret containing the server certificate for the `clusterIP` ingress.
-<2> Reference to a secret containing the server certificate for the `loadBalancer` ingress.
+<1> References a secret containing the server certificate for the `clusterIP` ingress.
+<2> References a secret containing the server certificate for the `loadBalancer` ingress.
 
 include::./con-virtualkafkacluster-clusterip-generate-tls-certificates.adoc[leveloffset=+1]
 include::./con-virtualkafkacluster-loadbalancer-generate-tls-certificates.adoc[leveloffset=+1]