GEOMESA-3420 Kafka - readiness endpoint docs (#3239)

docs/user/kafka/geoserver.rst

@@ -21,4 +21,20 @@ plugin JARs into in the right directory and restart GeoServer.
 On the "Add Store" page, select "Kafka (GeoMesa)", and fill out the
 parameters. The parameters are described in :ref:`kafka_parameters`.
 
-Click "Save", and GeoServer will search Zookeeper for any GeoMesa-managed feature types.
+Click "Save", and GeoServer will search Zookeeper for any GeoMesa-managed feature types.
+
+.. _kafka_readiness_gs:
+
+Kafka Layer Readiness Endpoint
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When a Kafka data store is configured with a read-back (``kafka.consumer.read-back``), it may take some time before layers
+are available for querying. GeoMesa provides an endpoint that can be used to track the status of the consumer read-back.
+When installed, GeoServer will expose an endpoint at ``rest/kafka`` (e.g. ``localhost:8080/geoserver/rest/kafka``) that can
+be used in a readiness probe, returning HTTP status code ``200`` when all layers are loaded, and ``503`` when layers are not
+yet available. See :ref:`install_kafka_readiness_gs` for installation instructions.
+
+.. warning::
+
+    ``kafka.consumer.start-on-demand`` must be set to false (unchecked) in order for layers to be automatically loaded when
+    GeoServer starts up.

docs/user/kafka/install.rst

@@ -12,7 +12,8 @@ Installing GeoMesa Kafka
     .. parsed-literal::
 
         $ export TAG="|release_version|"
-        $ export VERSION="|scala_binary_version|-${TAG}" # note: |scala_binary_version| is the Scala build version
+        $ export SCALA_VERSION="|scala_binary_version|" # note: |scala_binary_version| is the Scala build version
+        $ export VERSION="${SCALA_VERSION}-${TAG}"
 
 Installing from the Binary Distribution
 ---------------------------------------
@@ -153,3 +154,17 @@ to match the target environment, and then run the script:
     Ensure that the Scala version of both GeoMesa and Kafka match to avoid compatibility errors.
 
 Restart GeoServer after the JARs are installed.
+
+.. _install_kafka_readiness_gs:
+
+Installing the GeoMesa Kafka Readiness Endpoint
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+GeoMesa provides a :ref:`kafka_readiness_gs` that can provide status on layer loading progress. To install the endpoint,
+add the ``geomesa-gs-kafka-status-endpoint`` JAR to GeoServer's lib directory:
+
+.. code-block:: bash
+
+    $ export MAVEN_URL="https://search.maven.org/remotecontent?filepath=org/geomesa/geoserver"
+    $ wget "${MAVEN_URL}/geomesa-gs-kafka-status-endpoint_${SCALA_VERSION}/${TAG}/geomesa-gs-kafka-status-endpoint_${VERSION}.jar" \
+      -O /path/to/geoserver/webapps/geoserver/WEB-INF/lib/geomesa-gs-kafka-status-endpoint_${VERSION}.jar