Checkpoint

Lightstreamer · Mar 5, 2024 · 2241ad3 · 2241ad3
1 parent 3c856dd
commit 2241ad3
Show file tree

Hide file tree

Showing 7 changed files with 110 additions and 47 deletions.
diff --git a/examples/quickstart-confluent-cloud/README.md b/examples/quickstart-confluent-cloud/README.md
@@ -0,0 +1,66 @@
+# Quick Start with Confluent Cloud
+
+This folder contains a variant of the [_Quick Start_](../quickstart-ssl/README.md#quick-start-ssl) app configured to use _Confluent Cloud_ as the target Kafka cluster.
+
+The [docker-compose.yml](docker-compose.yml) file has been revised to realize the integration with Confluent Cloud:
+
+- Removal of the _broker_ service, because replaced by the remote Kafka cluster, as follows:
+
+- _kafka-connector_
+  - Definition of new environment variables to configure the remote endpoint and credentials in the `adapters.xml` trough the _variable-expansion_ feature of Lightstreamer.
+    ```yaml
+    ...
+    environment:
+      - bootstrap_server=${bootstrap_server}
+      - api_key=${api_key}
+      - secret=${secret}
+    ...
+    ```
+  - Adaption of [`adapters.xml`](./adapters.xml) to include:
+    - New Kafka cluster address retrieved from the environment variable `bootstrap_server`:
+      ```xml
+      <param name="bootstrap.servers">$env.bootstrap_server</param>
+      ```
+
+    - Encryption settings:
+      ```xml
+      <param name="encryption.enable">true</param>
+      <param name="encryption.protocol">TLSv1.2</param>
+      <param name="encryption.hostname.verification.enable">true</param>
+      ```
+
+    - Authentication settings, with credentials retrieved from environment variables `api_key` and `secret`:
+      ```xml
+      <param name="authentication.enable">true</param>
+      <param name="authentication.mechanism">PLAIN</param>
+      <param name="authentication.username">$env.api_key</param>
+      <param name="authentication.password">$env.secret</param>
+      ```
+
+- _producer_
+
+   Provisioning of the `producer.properties` configuration file to enable `SASL/PLAN` over TLS, with username and password retrieved from the environment variables `api_key` and `secret`:
+
+    ```yaml
+    # Configure SASL/PLAIN mechanism
+    sasl.mechanism=PLAIN
+    # Enable SSL encryption
+    security.protocol=SASL_SSL
+    # JAAS configuration
+    sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username="${api_key}" password="${secret}";
+    ```  
+
+## Run
+
+From this directory, run follow the command:
+
+```sh
+api_key=<API.key> secret=<secret> bootstrap_server=<bootstrap_server> ./start.sh 
+```
+
+where 
+- `API.key` and `secret` are the credentials generated on the _Confluent CLI_ or from the _Confluent Cloud Console_.
+- `bootstrap_server` is the Kafla cluster address.
+
+Then, point your browser to [http://localhost:8080/QuickStart](http://localhost:8080/QuickStart).
+
diff --git a/examples/quickstart-confluent-cloud/adapters.xml b/examples/quickstart-confluent-cloud/adapters.xml
@@ -1,14 +1,5 @@
 <?xml version="1.0"?>
 
-<!--
-    This is the configuration file of the Lightstreamer Kafka Connector pluggable into Lightstreamer Server.
-
-
-    A very simple variable-expansion feature is available; see
-    <enable_expansion_for_adapters_config> in the Server's main configuration file.
--->
-
-<!-- Mandatory. Define the Kafka Connector Adapter Set and its unique ID. -->
 <adapters_conf id="KafkaConnector">
     <metadata_provider>
         <adapter_class>com.lightstreamer.kafka_connector.adapters.pub.KafkaConnectorMetadataAdapter</adapter_class>
@@ -18,32 +9,36 @@
      <data_provider name="QuickStart">
         <adapter_class>com.lightstreamer.kafka_connector.adapters.KafkaConnectorDataAdapter</adapter_class>
 
-        <param name="bootstrap.servers">pkc-z9doz.eu-west-1.aws.confluent.cloud:9092</param>
+        <!-- <param name="bootstrap.servers">pkc-z9doz.eu-west-1.aws.confluent.cloud:9092</param> -->
+        <param name="bootstrap.servers">$env.bootstrap_server</param>
+
         <param name="group.id">quick-start-group</param>
 
+        <!-- Encryption settings -->
         <param name="encryption.enable">true</param>
         <param name="encryption.protocol">TLSv1.2</param>
         <param name="encryption.hostname.verification.enable">true</param>
 
+        <!-- Authentication settings -->
         <param name="authentication.enable">true</param>
         <param name="authentication.mechanism">PLAIN</param>
         <param name="authentication.username">$env.api_key</param>
         <param name="authentication.password">$env.secret</param>
 
+        <!-- Topics mapping -->
         <param name="item-template.stock">stock-#{index=KEY}</param>
         <param name="map.topic_0.to">item-template.stock</param>
 
+        <!-- Record consumption settings -->
+        <param name="consumer.auto.offset.reset">earliest</param>
         <param name="key.evaluator.type">INTEGER</param>
         <param name="value.evaluator.type">JSON</param>
-        <param name="consumer.auto.offset.reset">earliest</param>
 
-        <!-- FIELDS MAPPING SECTION -->
+        <!-- Fields mapping settings -->
         <param name="field.ts">#{TIMESTAMP}</param>
         <param name="field.topic">#{TOPIC}</param>
         <param name="field.offset">#{OFFSET}</param>
         <param name="field.partition">#{PARTITION}</param>
-
-        <!-- Extraction of the record offset mapped to the field "offset". -->
         <param name="field.timestamp">#{VALUE.timestamp}</param>
         <param name="field.time">#{VALUE.time}</param>
         <param name="field.stock_name">#{VALUE.name}</param>

diff --git a/examples/quickstart-confluent-cloud/docker-compose.yml b/examples/quickstart-confluent-cloud/docker-compose.yml
@@ -5,10 +5,12 @@ services:
     container_name: kafka-connector
     image: lightstreamer-kafka-connector-${version}
     depends_on:
+      - broker
       - producer
     ports:
       - 8080:8080
     environment:
+      - bootstrap_server=${bootstrap_server}
       - api_key=${api_key}
       - secret=${secret}
     volumes:
@@ -17,6 +19,8 @@ services:
 
   producer:
     container_name: producer
+    depends_on:
+      - broker
     build:
       context: ../compose-templates
       dockerfile: Dockerfile.producer
@@ -25,11 +29,14 @@ services:
     configs:
       - source: producer.properties
         target: /usr/app/producer.properties
-    command: ["--bootstrap-servers", "pkc-z9doz.eu-west-1.aws.confluent.cloud:9092", "--topic", "topic_0", "--config-file", "/usr/app/producer.properties"]
+    command: ["--bootstrap-servers", "${bootstrap_server}", "--topic", "topic_0", "--config-file", "/usr/app/producer.properties"]
 
 configs:
   producer.properties:
     content: |
+      # Configure SASL/PLAIN mechanism
+      sasl.mechanism=PLAIN
+      # Enable SSL encryption
       security.protocol=SASL_SSL
+      # JAAS configuration
       sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username="${api_key}" password="${secret}";
-      sasl.mechanism=PLAIN
diff --git a/examples/quickstart-schema-registry/README.md b/examples/quickstart-schema-registry/README.md
@@ -2,15 +2,13 @@
 
 This folder contains a variant of the [_Quick Start SSL_](../quickstart-ssl/README.md#quick-start-ssl) app configured to use the _Confluent Schema Registry_.
 
-The [docker-compose.yml](docker-compose.yml) has been revised to configure the integration with [_Confluent Docker Image for Schema Registry_](https://hub.docker.com/r/confluentinc/cp-schema-registry):
+The [docker-compose.yml](docker-compose.yml) file has been revised to configure the integration with [_Confluent Docker Image for Schema Registry_](https://hub.docker.com/r/confluentinc/cp-schema-registry) as follows:
 
-- _schema-registry_
-
-  The added service, pointing to the mentioned Docker image, with full configuration of the security settings.
+- New service _schema-registry_, pulled from mentioned Docker image and configured with security settings.
 
 - _kafka-connector_
-
-  The new version of the [`adapters.xml`](./adapters.xml) includes:
+  
+  Adaption of [`adapters.xml`](./adapters.xml) to include:
   - Enabling of the Schema Registry:
     ```xml
     <param name="value.evaluator.schema.registry.enable">true</param>
@@ -37,10 +35,10 @@ The [docker-compose.yml](docker-compose.yml) has been revised to configure the i
 
 - _producer_
 
-   The `producer.properties` configuration file adds the settings required to communicate with the Schema Registry:
+   Extension of the `producer.properties` configuration file with the settings required to communicate with the Schema Registry:
 
     ```yaml
-    ..
+    ...
     # JSON deserializer with support for the Schema Registry
     value.serializer=io.confluent.kafka.serializers.json.KafkaJsonSchemaSerializer
     # Schema Registry URL

diff --git a/examples/quickstart-schema-registry/adapters.xml b/examples/quickstart-schema-registry/adapters.xml
@@ -4,7 +4,6 @@
     <metadata_provider>
         <adapter_class>com.lightstreamer.kafka_connector.adapters.pub.KafkaConnectorMetadataAdapter</adapter_class>
         <param name="logging.configuration.path">log4j.properties</param>
-
     </metadata_provider>
 
     <data_provider name="QuickStart">
@@ -13,7 +12,7 @@
         <param name="bootstrap.servers">broker:29094</param>
         <param name="group.id">quick-start-group</param>
 
-        <!-- Encryption Settings -->
+        <!-- Encryption settings -->
         <param name="encryption.enable">true</param>
         <param name="encryption.protocol">TLSv1.3</param>
         <param name="encryption.hostname.verification.enable">false</param>
@@ -24,14 +23,17 @@
         <param name="encryption.keystore.password">kafka-connector-password</param>
         <param name="encryption.keystore.key.password">kafka-connector-password</param>
 
+        <!-- Topics mapping -->
         <param name="item-template.stock">stock-#{index=KEY}</param>
         <param name="map.stocks.to">item-template.stock</param>
 
+        <!-- Record consumption settings -->
         <param name="consumer.auto.offset.reset">earliest</param>
         <param name="key.evaluator.type">INTEGER</param>
         <param name="value.evaluator.type">JSON</param>
         <param name="value.evaluator.schema.registry.enable">true</param>
 
+        <!-- Schema Registry settings -->
         <param name="schema.registry.url">https://schema-registry:8084</param>
         <param name="schema.registry.encryption.truststore.path">secrets/kafka-connector.truststore.jks</param>
         <param name="schema.registry.encryption.truststore.password">kafka-connector-truststore-password</param>
@@ -40,14 +42,11 @@
         <param name="schema.registry.encryption.keystore.password">kafka-connector-password</param>
         <param name="schema.registry.encryption.keystore.key.password">kafka-connector-password</param>
 
-
-        <!-- FIELDS MAPPING SECTION -->
+        <!-- Fields mapping settings -->
         <param name="field.ts">#{TIMESTAMP}</param>
         <param name="field.topic">#{TOPIC}</param>
         <param name="field.offset">#{OFFSET}</param>
         <param name="field.partition">#{PARTITION}</param>
-
-        <!-- Extraction of the record offset mapped to the field "offset". -->
         <param name="field.timestamp">#{VALUE.timestamp}</param>
         <param name="field.time">#{VALUE.time}</param>
         <param name="field.stock_name">#{VALUE.name}</param>

diff --git a/examples/quickstart-ssl/README.md b/examples/quickstart-ssl/README.md
@@ -2,11 +2,11 @@
 
 This folder contains all the resources needed to launch the [_Quick Start_](../../README.md#quick-start) app configured to establish a secure connection with the Kafka broker.
 
-The [docker-compose.yml](docker-compose.yml) has been revised to enable support for SSL:
+The [docker-compose.yml](docker-compose.yml) file has been revised to enable support for SSL, as follows:
 
 - _broker_
-  - SSL enabled on port 29094.
-  - New environment variables to configure keystore, truststore, client authentication, and secrets:
+  - Enabling of SSL enabled on port 29094.
+  - Definition of new environment variables to configure keystore, truststore, client authentication, and secrets:
     - `KAFKA_SSL_TRUSTSTORE_FILENAME`
     - `KAFKA_SSL_TRUSTSTORE_CREDENTIALS`
     - `KAFKA_SSL_KEYSTORE_FILENAME`
@@ -16,26 +16,26 @@ The [docker-compose.yml](docker-compose.yml) has been revised to enable support
 
 - _kafka-connector_
 
-  The new version of the [`adapters.xml`](./adapters.xml) includes:
-  - Parameter `boostrap.servers` pointing to the SSL endpoint (`broker:29094`).
+  Adaption of [`adapters.xml`](./adapters.xml) to include:
+  - New SSL endpoint (`broker:29094`):
     ```xml
     <param name="bootstrap.servers">broker:29094</param>
     ```
 
-  - Encryption enabled.
+  - Encryption settings:
     ```xml
     <param name="encryption.enable">true</param>
     <param name="encryption.protocol">TLSv1.2</param>
     <param name="encryption.hostname.verification.enable">false</param>
     ```
 
-  - Configuration of the truststore to authenticate the broker.
+  - Configuration of the truststore to authenticate the broker:
     ```xml
     <param name="encryption.truststore.path">secrets/kafka.connector.truststore.jks</param>
     <param name="encryption.truststore.password">kafka-connector-truststore-password</param>
     ```
 
-  - Configuration of the keystore for client authentication with the broker.
+  - Configuration of the keystore for client authentication with the broker:
     ```xml
     <param name="encryption.keystore.enable">true</param>
     <param name="encryption.keystore.path">secrets/kafka-connector.keystore.jks</param>
@@ -44,8 +44,8 @@ The [docker-compose.yml](docker-compose.yml) has been revised to enable support
     ```
 
 - _producer_
-  - The new `producer.properties` configuration file enables SSL support:
-    
+  - New SSL endpoint (`broker:29094`).
+  - Provisioning of the `producer.properties` configuration file to enable SSL support:
     ```yaml
     # Enable SSL
     security.protocol=SSL
@@ -59,7 +59,6 @@ The [docker-compose.yml](docker-compose.yml) has been revised to enable support
     # Disable host name verification
     ssl.endpoint.identification.algorithm=
     ```  
-  - Changed target broker to new SSL endpoint (`broker:29094`).
 
 In addition, all services reference the local [`secrets`](../compose-templates/secrets/) folder to retrieve their secrets:
 

diff --git a/examples/quickstart-ssl/adapters.xml b/examples/quickstart-ssl/adapters.xml
@@ -4,7 +4,6 @@
     <metadata_provider>
         <adapter_class>com.lightstreamer.kafka_connector.adapters.pub.KafkaConnectorMetadataAdapter</adapter_class>
         <param name="logging.configuration.path">log4j.properties</param>
-
     </metadata_provider>
 
     <data_provider name="QuickStart">
@@ -13,7 +12,7 @@
         <param name="bootstrap.servers">broker:29094</param>
         <param name="group.id">quick-start-group</param>
 
-        <!-- Encryption Settings -->
+        <!-- Encryption settings -->
         <param name="encryption.enable">true</param>
         <param name="encryption.protocol">TLSv1.3</param>
         <param name="encryption.hostname.verification.enable">false</param>
@@ -24,20 +23,20 @@
         <param name="encryption.keystore.password">kafka-connector-password</param>
         <param name="encryption.keystore.key.password">kafka-connector-password</param>
 
+        <!-- Topics mapping -->
         <param name="item-template.stock">stock-#{index=KEY}</param>
         <param name="map.stocks.to">item-template.stock</param>
 
+        <!-- Record consumption settings -->
+        <param name="consumer.auto.offset.reset">earliest</param>
         <param name="key.evaluator.type">INTEGER</param>
         <param name="value.evaluator.type">JSON</param>
-        <param name="consumer.auto.offset.reset">earliest</param>
 
-        <!-- FIELDS MAPPING SECTION -->
+        <!-- Fields mapping settings -->
         <param name="field.ts">#{TIMESTAMP}</param>
         <param name="field.topic">#{TOPIC}</param>
         <param name="field.offset">#{OFFSET}</param>
         <param name="field.partition">#{PARTITION}</param>
-
-        <!-- Extraction of the record offset mapped to the field "offset". -->
         <param name="field.timestamp">#{VALUE.timestamp}</param>
         <param name="field.time">#{VALUE.time}</param>
         <param name="field.stock_name">#{VALUE.name}</param>