expand explanations for the get started guide (#3226)

Author: lena-larionova

app/_how-tos/knep/get-started-with-event-gateway.md

@@ -22,12 +22,12 @@ description: Use this tutorial to get started with {{site.event_gateway}}.
 tldr: 
   q: How can I get started with {{site.event_gateway}}?
   a: | 
-    Get started with {{site.event_gateway}} by setting up a {{site.konnect_short_name}} control plane and data plane, then configuring a backend cluster, virtual cluster, listener, and policy with the {{site.event_gateway}} API.
+    Get started with {{site.event_gateway}} by setting up a {{site.konnect_short_name}} control plane and data plane, then configuring a backend cluster, virtual cluster, listener, and policies with the {{site.event_gateway}} API.
 
     {:.info}
     > **Note:**
     > This quickstart runs a pre-configured demo Docker container to explore {{ site.base_gateway }}'s capabilities. 
-    If you want to run {{ site.base_gateway }} as a part of a production-ready platform, start with the [Install](/event-gateway/#install) page.
+    If you want to run {{ site.base_gateway }} as a part of a production-ready platform, set up your control plane and data planes through the [{{site.konnect_short_name}} UI](/event-gateway/?tab=konnect-ui#install-event-gateway), or using [Terraform](/terraform/).
 
 tools:
     - konnect-api
@@ -65,7 +65,7 @@ faqs:
       * Ensure that `acl_mode` is set to `passthrough` in the virtual cluster. If set to `enforce_on_gateway`, you won't see any topics listed without an ACL policy.
 ---
 
-{{site.event_gateway}} lets you configure virtual clusters, which act as a proxy interface between the client and the Kafka cluster.
+{{site.event_gateway}} lets you configure virtual clusters, which act as a proxy interface between the Kafka client and the Kafka cluster.
 With virtual clusters, you can:
 * Apply transformations, filtering, and custom policies
 * Route messages based on specific rules to different Kafka clusters
@@ -92,11 +92,14 @@ Copy and paste this into your terminal to configure your session.
 
 {:.info}
 > This quickstart script is meant for demo purposes only, therefore it runs locally with default parameters and a small number of exposed ports.
-If you want to run {{ site.base_gateway }} as a part of a production-ready platform, start with the [Install](/event-gateway/#install) page.
+If you want to run {{ site.base_gateway }} as a part of a production-ready platform, set up your control plane and data planes through the [{{site.konnect_short_name}} UI](/event-gateway/?tab=konnect-ui#install-event-gateway), or using [Terraform](/terraform/).
 
 ## Add a backend cluster
 
-Run the following command to create a new backend cluster linked to the local Kafka server we created in the [prerequisites](#start-a-local-kafka-server):
+[Backend clusters](/event-gateway/entities/backend-cluster/) are abstractions of your real Kafka clusters, and they store connection and configuration details required for {{site.event_gateway}} to proxy traffic to Kafka.
+You need at least one backend cluster.
+
+Run the following command to create a new backend cluster linked to the local Kafka server we created in the [prerequisites](#start-a-local-kafka-cluster):
 <!--vale off-->
 {% konnect_api_request %}
 url: /v1/event-gateways/$EVENT_GATEWAY_ID/backend-clusters
@@ -116,13 +119,25 @@ body:
 {% endkonnect_api_request %}
 <!--vale on-->
 
+In this example configuration:
+* `bootstrap_servers`: Points the backend cluster to the three bootstrap servers that we launched in the prerequisites. 
+* `authentication` and `insecure_allow_anonymous_virtual_cluster_auth`: For demo purposes, we're allowing insecure `anonymous` connections, which means no authentication required. 
+* `tls`: TLS is disabled so that we can easily test the connection.
+
 Export the backend cluster ID to your environment:
 ```sh
 export BACKEND_CLUSTER_ID="YOUR-BACKEND-CLUSTER-ID"
 ```
 
 ## Add a virtual cluster
 
+[Virtual clusters](/event-gateway/entities/virtual-cluster/) are the connection point for Kafka clients. 
+Instead of connecting clients directly to your Kafka cluster, you can set up virtual clusters to customize how clients connect, and what requirements they need to have.
+From the client's point of view, they're just connecting to a regular Kafka cluster.
+
+Virtual clusters provide environment isolation and let you enforce policies, manage authentication, and more.
+Each virtual cluster can connect to one backend cluster, though a backend cluster can have many virtual clusters connected to it.
+
 Run the following command to create a new virtual cluster associated with our backend cluster:
 <!--vale off-->
 {% konnect_api_request %}
@@ -140,13 +155,22 @@ body:
 {% endkonnect_api_request %}
 <!--vale on-->
 
+In this example:
+* `authentication`: Allows anonymous authentication.
+* `acl_mode`: The setting `passthrough` means that all clients are allowed and don't have to match a defined ACL. 
+In a production environment, you would set this to `enforce_on_gateway` and define an ACL policy.
+* `name` is an internal name for the configuration object, while the `dns_label` is necessary for SNI routing.
+
 Export the virtual cluster ID to your environment:
 ```sh
 export VIRTUAL_CLUSTER_ID="YOUR-VIRTUAL-CLUSTER-ID"
 ```
 
 ## Add a listener
 
+A [listener](/event-gateway/entities/listener/) represents hostname-port or IP-port combinations that connect to TCP sockets.
+In this example, we're going to use port mapping, so we need to expose a range of ports.
+
 Run the following command to create a new listener:
 <!--vale off-->
 {% konnect_api_request %}
@@ -169,7 +193,11 @@ export LISTENER_ID="YOUR-LISTENER-ID"
 
 ## Add a listener policy
 
-Run the following command to add a listener policy that forwards messages to our virtual cluster:
+The listener needs a policy to tell it how to process requests and what to do with them.
+In this example, we're going to use the [Forward to Virtual Cluster](/event-gateway/policies/forward-to-virtual-cluster/) policy, 
+which will forward requests based on a defined mapping to our virtual cluster.
+
+Run the following command to add the listener policy:
 
 <!--vale off-->
 {% konnect_api_request %}
@@ -187,10 +215,14 @@ body:
 {% endkonnect_api_request %}
 <!--vale on-->
 
+For demo purposes, we're using port mapping, which assigns each Kafka broker to a dedicated port on the {{site.event_gateway_short}}. 
+In production, we recommend using [SNI routing](/event-gateway/architecture/#hostname-mapping) instead.
 
 ## Add a virtual cluster policy
 
-Run the following command to add a consume policy that adds a new header on the virtual cluster:
+Now, let's add a policy the virtual cluster so we can test our proxy. 
+For this example, let's add a [Modify Headers](/event-gateway/policies/modify-headers/) policy, which lets you set or remove headers on requests:
+
 <!--vale off-->
 {% konnect_api_request %}
 url: /v1/event-gateways/$EVENT_GATEWAY_ID/virtual-clusters/$VIRTUAL_CLUSTER_ID/consume-policies
@@ -207,9 +239,13 @@ body:
 {% endkonnect_api_request %}
 <!--vale on-->
 
+This policy configuration sets the custom header `My-New-Header: header_value` on all requests proxied by this virtual cluster.
+
 ## Configure the Kafka cluster
 
-Set up the `kafkactl` config file for your Kafka cluster:
+Now that we've configured the proxy, let's make sure the Kafka cluster is ready.
+
+In your local environment, set up the `kafkactl.yaml` config file for your Kafka cluster:
 
 ```shell
 cat <<EOF > kafkactl.yaml
@@ -224,7 +260,12 @@ contexts:
       - localhost:19092
 EOF
 ```
-This file defines two configuration profiles. We're going to switch between these profiles as we test different features.
+This file defines two configuration profiles:
+* `direct`: Connection addresses to all of the bootstrap servers you launched in the prerequisites, and configured in the backend cluster. 
+Accessing the `direct` context will bypass the {{site.event_gateway}} proxy and connect directly to your Kafka cluster.
+* `vc`: Connection to the virtual cluster. Accessing the `vc` context will pass requests through the virtual cluster.
+
+We're going to switch between these profiles as we test different features.
 
 ## Validate the cluster
 

app/event-gateway/entities/virtual-cluster.md

@@ -40,7 +40,7 @@ breadcrumbs:
 
 ## What is a virtual cluster?
 
-Virtual clusters are the primary way clients interact with the {{site.event_gateway_short}} proxy.q
+Virtual clusters are the primary way clients interact with the {{site.event_gateway_short}} proxy.
 They allow you to isolate clients from each other when connecting to the same [backend cluster](/event-gateway/entities/backend-cluster/),
 and provide each client with modified view while still appearing as a standard Kafka cluster.
 
@@ -110,10 +110,6 @@ You will need to increase the number of virtual clusters if you want to create m
 
 Here are some common patterns:
 
-* **Environment isolation**: You can create isolated `dev`, `test`, and `prod` namespaces on top of the same physical Kafka cluster.
-If you have a topic named `orders` in each virtual cluster, this will map transparently to different backend topics: `dev-orders`, `test-orders`, and `prod-orders`. 
-This provides isolation and automatic name resolution per environment.
-
 * **Environment isolation**: You can create isolated `dev`, `test`, and `prod` namespaces on top of the same physical Kafka cluster.
 If you have a topic named `orders` in each virtual cluster, this will map transparently to different backend topics: `dev-orders`, `test-orders`, and `prod-orders`. 
 This provides isolation and automatic name resolution per environment.