Docs: update Kafka Bridge to HTTP Bridge (#1032)

documentation/assemblies/assembly-http-bridge-config.adoc

@@ -0,0 +1,19 @@
+// This assembly is included in the following assemblies:
+//
+// bridge.adoc
+
+[id='assembly-http-bridge-config-{context}']
+= HTTP Bridge configuration
+
+[role="_abstract"]
+Configure a deployment of the HTTP Bridge with Kafka-related properties and specify the HTTP connection details needed to be able to interact with Kafka.
+Additionally, enable metrics in Prometheus format using either the https://github.com/prometheus/jmx_exporter[Prometheus JMX Exporter] or the https://github.com/strimzi/metrics-reporter[Strimzi Metrics Reporter].
+You can also use configuration properties to enable and use distributed tracing with the HTTP Bridge.
+Distributed tracing allows you to track the progress of transactions between applications in a distributed system.
+
+NOTE: Use the `KafkaBridge` resource to configure properties when you are xref:overview-components-running-http-bridge-cluster-{context}[running the HTTP Bridge on Kubernetes].
+
+include::modules/proc-configuring-http-bridge.adoc[leveloffset=+1]
+include::modules/proc-configuring-http-bridge-jmx-metrics.adoc[leveloffset=+1]
+include::modules/proc-configuring-http-bridge-smr-metrics.adoc[leveloffset=+1]
+include::modules/proc-configuring-http-bridge-tracing.adoc[leveloffset=+1]

documentation/assemblies/assembly-http-bridge-overview.adoc

@@ -0,0 +1,29 @@
+// This assembly is included in the following assemblies:
+//
+// bridge.adoc
+
+[id='assembly-http-bridge-overview-{context}']
+= HTTP Bridge overview
+
+[role="_abstract"]
+Use the HTTP Bridge to make HTTP requests to a Kafka cluster.
+
+You can use the HTTP Bridge to integrate HTTP client applications with your Kafka cluster.
+
+.HTTP client integration
+
+image:kafka-bridge.png[Internal and external HTTP producers and consumers exchange data with the Kafka brokers through the HTTP Bridge]
+
+include::modules/con-overview-running-http-bridge.adoc[leveloffset=+1]
+
+include::modules/con-overview-components-http-bridge.adoc[leveloffset=+1]
+
+include::modules/con-overview-open-api-spec-http-bridge.adoc[leveloffset=+1]
+
+include::modules/con-securing-http-bridge.adoc[leveloffset=+1]
+
+include::modules/con-securing-http-interface.adoc[leveloffset=+1]
+
+include::modules/con-requests-http-bridge.adoc[leveloffset=+1]
+
+include::modules/con-loggers-http-bridge.adoc[leveloffset=+1]

documentation/assemblies/assembly-kafka-bridge-quickstart.adoc → documentation/assemblies/assembly-http-bridge-quickstart.adoc

@@ -2,16 +2,16 @@
 //
 // bridge.adoc
 
-[id='assembly-kafka-bridge-quickstart-{context}']
-= Kafka Bridge quickstart
+[id='assembly-http-bridge-quickstart-{context}']
+= HTTP Bridge quickstart
 
 [role="_abstract"]
-Use this quickstart to try out the Kafka Bridge in your local development environment.
+Use this quickstart to try out the HTTP Bridge in your local development environment.
 
 You will learn how to do the following:
 
 * Produce messages to topics and partitions in your Kafka cluster
-* Create a Kafka Bridge consumer
+* Create a KafHTTPka Bridge consumer
 * Perform basic consumer operations, such as subscribing the consumer to topics and retrieving the messages that you produced
 
 In this quickstart, HTTP requests are formatted as curl commands that you can copy and paste to your terminal.
@@ -24,13 +24,13 @@ In this quickstart, you will produce and consume messages in JSON format.
 
 * A Kafka cluster is running on the host machine.
 
-include::modules/proc-downloading-kafka-bridge.adoc[leveloffset=+1]
+include::modules/proc-downloading-http-bridge.adoc[leveloffset=+1]
 
-include::modules/proc-installing-kafka-bridge.adoc[leveloffset=+1]
+include::modules/proc-installing-http-bridge.adoc[leveloffset=+1]
 
 include::modules/proc-producing-messages-from-bridge-topics-partitions.adoc[leveloffset=+1]
 
-include::modules/proc-creating-kafka-bridge-consumer.adoc[leveloffset=+1]
+include::modules/proc-creating-http-bridge-consumer.adoc[leveloffset=+1]
 
 include::modules/proc-bridge-subscribing-consumer-topics.adoc[leveloffset=+1]
 

documentation/book/api/snippet/consumers/{groupid}/POST/http-response.adoc

@@ -15,7 +15,7 @@
 ----
 {
   "error_code" : 409,
-  "message" : "A consumer instance with the specified name already exists in the Kafka Bridge."
+  "message" : "A consumer instance with the specified name already exists in the HTTP Bridge."
 }
 ----
 

documentation/book/bridge.adoc

@@ -3,13 +3,13 @@ include::common/attributes.adoc[]
 :context: bridge
 
 [id='using_book-{context}']
-= Using the Strimzi Kafka Bridge
+= Using the Strimzi HTTP Bridge
 
-include::assemblies/assembly-kafka-bridge-overview.adoc[leveloffset=+1]
+include::assemblies/assembly-http-bridge-overview.adoc[leveloffset=+1]
 
-include::assemblies/assembly-kafka-bridge-quickstart.adoc[leveloffset=+1]
+include::assemblies/assembly-http-bridge-quickstart.adoc[leveloffset=+1]
 
-include::assemblies/assembly-kafka-bridge-config.adoc[leveloffset=+1]
+include::assemblies/assembly-http-bridge-config.adoc[leveloffset=+1]
 
 [id='api_reference-{context}']
 include::api/index.adoc[leveloffset=+1]

documentation/modules/con-loggers-kafka-bridge.adoc → documentation/modules/con-loggers-http-bridge.adoc

@@ -1,14 +1,14 @@
 // Module included in the following assemblies:
 //
-// assembly-kafka-bridge-overview.adoc
+// assembly-http-bridge-overview.adoc
 
-[id='con-loggers-kafka-bridge-{context}']
+[id='con-loggers-http-bridge-{context}']
 
 [role="_abstract"]
-= Configuring loggers for the Kafka Bridge
+= Configuring loggers for the HTTP Bridge
 
 [role="_abstract"]
-You can set a different log level for each operation that is defined by the Kafka Bridge OpenAPI specification.
+You can set a different log level for each operation that is defined by the HTTP Bridge OpenAPI specification.
 
 Each operation has a corresponding API endpoint through which the bridge receives requests from HTTP clients.
 You can change the log level on each endpoint to produce more or less fine-grained logging information about the incoming and outgoing HTTP requests.

documentation/modules/con-overview-components-kafka-bridge.adoc → documentation/modules/con-overview-components-http-bridge.adoc

@@ -1,18 +1,18 @@
 // Module included in the following assemblies:
 //
-// assembly-kafka-bridge-overview.adoc
+// assembly-http-bridge-overview.adoc
 
-[id="overview-components-kafka-bridge_{context}"]
-= Kafka Bridge interface
+[id="overview-components-http-bridge_{context}"]
+= HTTP Bridge interface
 
 [role="_abstract"]
-The Kafka Bridge provides a RESTful interface that allows HTTP-based clients to interact with a Kafka cluster. 
+The HTTP Bridge provides a RESTful interface that allows HTTP-based clients to interact with a Kafka cluster. 
 It offers the advantages of a web API connection to Strimzi, without the need for client applications to interpret the Kafka protocol.
 
-The API has two main resources — `consumers` and `topics` — that are exposed and made accessible through endpoints to interact with consumers and producers in your Kafka cluster. The resources relate only to the Kafka Bridge, not the consumers and producers connected directly to Kafka.
+The API has two main resources — `consumers` and `topics` — that are exposed and made accessible through endpoints to interact with consumers and producers in your Kafka cluster. The resources relate only to the HTTP Bridge, not the consumers and producers connected directly to Kafka.
 
 == HTTP requests
-The Kafka Bridge supports HTTP requests to a Kafka cluster, with methods to:
+The HTTP Bridge supports HTTP requests to a Kafka cluster, with methods to:
 
 * Send messages to a topic.
 * Retrieve messages from topics.
@@ -32,4 +32,4 @@ Clients can produce and consume messages without the requirement to use the nati
 
 [role="_additional-resources"]
 .Additional resources
-* xref:api_reference-{context}[Kafka Bridge API reference]
+* xref:api_reference-{context}[HTTP Bridge API reference]

documentation/modules/con-overview-open-api-spec-kafka-bridge.adoc → documentation/modules/con-overview-open-api-spec-http-bridge.adoc

@@ -1,16 +1,16 @@
 // This assembly is included in the following assemblies:
 //
-// assembly-kafka-bridge-overview.adoc
+// assembly-http-bridge-overview.adoc
 
-[id='overview-open-api-spec-kafka-bridge-{context}']
-= Kafka Bridge OpenAPI specification
+[id='overview-open-api-spec-http-bridge-{context}']
+= HTTP Bridge OpenAPI specification
 
 [role="_abstract"]
-Kafka Bridge APIs use the OpenAPI Specification (OAS).
+HTTP Bridge APIs use the OpenAPI Specification (OAS).
 OAS provides a standard framework for describing and implementing HTTP APIs.
 
-The Kafka Bridge OpenAPI specification is in JSON format.
-You can find the OpenAPI JSON files in the `src/main/resources/` folder of the Kafka Bridge source download files.
+The HTTP Bridge OpenAPI specification is in JSON format.
+You can find the OpenAPI JSON files in the `src/main/resources/` folder of the HTTP Bridge source download files.
 The download files are available from the {ReleaseDownload}.
 
 You can also use the xref:openapi[`GET /openapi` method] to retrieve the OpenAPI v3 specification in JSON format.

documentation/modules/con-overview-running-http-bridge.adoc

@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+//
+// assembly-http-bridge-overview.adoc
+
+[id="overview-components-running-http-bridge-{context}"]
+= Running the HTTP Bridge
+
+[role="_abstract"]
+Install the HTTP Bridge to run in the same environment as your Kafka cluster.
+
+You can download and add the HTTP Bridge installation artifacts to your host machine.
+To try out the HTTP Bridge in your local environment, see the xref:assembly-http-bridge-quickstart-{context}[HTTP Bridge quickstart].
+
+It's important to note that each instance of the HTTP Bridge maintains its own set of in-memory consumers (and subscriptions) that connect to the Kafka Brokers on behalf of the HTTP clients.
+This means that each HTTP client must maintain affinity to the same HTTP Bridge instance in order to access any subscriptions that are created. 
+Additionally, when an instance of the HTTP Bridge restarts, the in-memory consumers and subscriptions are lost.
+**It is the responsibility of the HTTP client to recreate any consumers and subscriptions if the HTTP Bridge restarts.** 
+
+[id="overview-components-running-http-bridge-cluster-{context}"]
+== Running the HTTP Bridge on Kubernetes
+
+If you deployed Strimzi on Kubernetes, you can use the Strimzi Cluster Operator to deploy the HTTP Bridge to the Kubernetes cluster.
+Configure and deploy the HTTP Bridge as a `KafkaBridge` resource.
+You'll need a running Kafka cluster that was deployed by the Cluster Operator in a Kubernetes namespace.
+You can configure your deployment to access the HTTP Bridge outside the Kubernetes cluster.
+
+HTTP clients must maintain affinity to the same instance of the HTTP Bridge to access any consumers or subscriptions that they create. Hence, running multiple replicas of the HTTP Bridge per Kubernetes Deployment is not recommended.
+If the HTTP Bridge pod restarts (for instance, due to Kubernetes relocating the workload to another node), the HTTP client must recreate any consumers or subscriptions.
+
+For information on deploying and configuring the HTTP Bridge as a `KafkaBridge` resource, see the {BookURLConfiguring}.

documentation/modules/con-requests-kafka-bridge.adoc → documentation/modules/con-requests-http-bridge.adoc

@@ -1,12 +1,12 @@
 // Module included in the following assemblies:
 //
-// assembly-kafka-bridge-overview.adoc
+// assembly-http-bridge-overview.adoc
 
-[id='con-requests-kafka-bridge-{context}']
-= Requests to the Kafka Bridge
+[id='con-requests-http-bridge-{context}']
+= Requests to the HTTP Bridge
 
 [role="_abstract"]
-Specify data formats and HTTP headers to ensure valid requests are submitted to the Kafka Bridge.
+Specify data formats and HTTP headers to ensure valid requests are submitted to the HTTP Bridge.
 
 == Content Type headers
 
@@ -45,7 +45,7 @@ An empty body can be used to create a consumer with the default values.
 
 == Embedded data format
 
-The embedded data format is the format of the Kafka messages that are transmitted, over HTTP, from a producer to a consumer using the Kafka Bridge. Three embedded data formats are supported: JSON, binary and text.
+The embedded data format is the format of the Kafka messages that are transmitted, over HTTP, from a producer to a consumer using the HTTP Bridge. Three embedded data formats are supported: JSON, binary and text.
 
 When creating a consumer using the `/consumers/_groupid_` endpoint, the `POST` request body must specify an embedded data format of either JSON, binary or text. This is specified in the `format` field, for example:
 
@@ -132,15 +132,15 @@ For example, when retrieving records for a subscribed consumer using an embedded
 Accept: application/vnd.kafka.json.v2+json
 ----
 
-[id='con-requests-kafka-bridge-cors-{context}']
+[id='con-requests-http-bridge-cors-{context}']
 = CORS
 
 In general, it is not possible for an HTTP client to issue requests across different domains.
 
-For example, suppose the Kafka Bridge you deployed alongside a Kafka cluster is accessible using the `\http://my-bridge.io` domain.
-HTTP clients can use the URL to interact with the Kafka Bridge and exchange messages through the Kafka cluster.
+For example, suppose the HTTP Bridge you deployed alongside a Kafka cluster is accessible using the `\http://my-bridge.io` domain.
+HTTP clients can use the URL to interact with the HTTP Bridge and exchange messages through the Kafka cluster.
 However, your client is running as a web application in the `\http://my-web-application.io` domain.
-The client (source) domain is different from the Kafka Bridge (target) domain.
+The client (source) domain is different from the HTTP Bridge (target) domain.
 Because of same-origin policy restrictions, requests from the client fail.  
 You can avoid this situation by using Cross-Origin Resource Sharing (CORS).
 
@@ -155,9 +155,9 @@ and use non-standard headers.
 
 All requests require an _origins_ value in their header, which is the source of the HTTP request.
 
-CORS allows you to specify allowed methods and originating URLs for accessing the Kafka cluster in your Kafka Bridge HTTP configuration.
+CORS allows you to specify allowed methods and originating URLs for accessing the Kafka cluster in your HTTP Bridge HTTP configuration.
 
-.Example CORS configuration for Kafka Bridge
+.Example CORS configuration for HTTP Bridge
 [source,properties,subs="attributes+"]
 ----
 # ...
@@ -184,7 +184,7 @@ curl -v -X GET _HTTP-BRIDGE-ADDRESS_/consumers/my-group/instances/my-consumer/re
 -H 'content-type: application/vnd.kafka.v2+json'
 ----
 
-In the response from the Kafka Bridge, an `Access-Control-Allow-Origin` header is returned.
+In the response from the HTTP Bridge, an `Access-Control-Allow-Origin` header is returned.
 It contains the list of domains from where HTTP requests can be issued to the bridge.
 
 [source,http,subs=+quotes]
@@ -196,8 +196,8 @@ Access-Control-Allow-Origin: * <1>
 
 == Preflighted request
 
-An initial preflight request is sent to Kafka Bridge using an `OPTIONS` method.
-The _HTTP OPTIONS_ request sends header information to check that Kafka Bridge will allow the actual request.
+An initial preflight request is sent to HTTP Bridge using an `OPTIONS` method.
+The _HTTP OPTIONS_ request sends header information to check that HTTP Bridge will allow the actual request.
 
 Here the preflight request checks that a `POST` request is valid from `\http://my-web-application.io`.
 
@@ -208,7 +208,7 @@ Origin: http://my-web-application.io
 Access-Control-Request-Method: POST <1>
 Access-Control-Request-Headers: Content-Type <2>
 ----
-<1> Kafka Bridge is alerted that the actual request is a `POST` request.
+<1> HTTP Bridge is alerted that the actual request is a `POST` request.
 <2> The actual request will be sent with a `Content-Type` header.
 
 `OPTIONS` is added to the header information of the preflight request.
@@ -220,7 +220,7 @@ curl -v -X OPTIONS -H 'Origin: http://my-web-application.io' \
 -H 'content-type: application/vnd.kafka.v2+json'
 ----
 
-Kafka Bridge responds to the initial request to confirm that the request will be accepted.
+HTTP Bridge responds to the initial request to confirm that the request will be accepted.
 The response header returns allowed origins, methods and headers.
 
 [source,http,subs=+quotes]