From 6fada156277a21556af8d08fd7e88eda9d1318f2 Mon Sep 17 00:00:00 2001 From: Leonard Goodell Date: Wed, 17 Aug 2022 17:13:04 -0700 Subject: [PATCH] feat: Add documentation of the EdgeX MessageBus closes #744, #808 Signed-off-by: Leonard Goodell --- .../general/messagebus diagram.drawio | 1 + .../general/messagebus diagram.jpg | Bin 0 -> 70700 bytes docs_src/microservices/general/messagebus.md | 190 ++++++++++++++++++ mkdocs.yml | 3 +- 4 files changed, 193 insertions(+), 1 deletion(-) create mode 100644 docs_src/microservices/general/messagebus diagram.drawio create mode 100644 docs_src/microservices/general/messagebus diagram.jpg create mode 100644 docs_src/microservices/general/messagebus.md diff --git a/docs_src/microservices/general/messagebus diagram.drawio b/docs_src/microservices/general/messagebus diagram.drawio new file mode 100644 index 0000000000..f2dac8c89a --- /dev/null +++ b/docs_src/microservices/general/messagebus diagram.drawio @@ -0,0 +1 @@ +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 \ No newline at end of file diff --git a/docs_src/microservices/general/messagebus diagram.jpg b/docs_src/microservices/general/messagebus diagram.jpg new file mode 100644 index 0000000000000000000000000000000000000000..d17736516bba4cb65c5afcf1e22e297ac203bc80 GIT binary patch literal 70700 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

&jH&jI&WvCTdYqjQk7?cmXeHVhBP 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�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 literal 0 HcmV?d00001 diff --git a/docs_src/microservices/general/messagebus.md b/docs_src/microservices/general/messagebus.md new file mode 100644 index 0000000000..9372c5392f --- /dev/null +++ b/docs_src/microservices/general/messagebus.md @@ -0,0 +1,190 @@ +# EdgeX MessageBus + +## Introduction + +Edgex has an internal message bus referred to as the **EdgeX MessageBus** , which is used for internal communications between EdgeX services. An EdgeX Service is any Core/Support/App/Device Service from EdgeX or any custom Application or Device Service built with the EdgeX SDKs. + +![[Insert Image of EdgeX MessageBus]](./messagebus diagram.jpg) + +The EdgeX MessageBus is meant for internal EdgeX service to service communications. It is not meant as an entry point for external services to communicate with the internal EdgeX services. The eKuiper Rules Engine is an exception to this as it is tightly integrated with EdgeX. + +There are EdgeX services that are meant as external entry points, which are: + +- **REST API on all the EdgeX services**. + + Accessed directly in non-secure mode or via the [API Gateway](../../../security/Ch-APIGateway) when running in secure mode + +- **App Service using External MQTT Trigger** + + An App Service configured to use the [External MQTT Trigger](../../application/Triggers/#external-mqtt-trigger) will accept data from external services on an "external" MQTT connection + +- **App Service using HTTP Trigger** + + An App Service configured to use the [HTTP Trigger](../../application/Triggers/#http-trigger) will accept data from external services on an "external" REST connection. It is accessed in the same manner as other EdgeX REST APIs. + +Originally the EdgeX MessageBus was only used to send *Event/Readings* from Core Data to the Application Services layer. In recent V2 releases more services are now using the EdgeX MessageBus rather than REST for inner service communication. + +- Device Services now publish *Event/Readings* directly to the EdgeX MessageBus rather than sending the *Event/Readings* over REST to Core Data. +- [Service Metrics](../#service-metrics) are published to the EdgeX MessageBus +- [System Events](../../core/metadata/Ch-Metadata/#device-system-events) are published to the EdgeX MessageBus. + +This trend away from REST to the EdgeX MessageBus for inner service communication continues. The upcoming [North South Messaging](../../../design/adr/0023-North-South-Messaging) implementation will use the EdgeX MessageBus in Core Command and Device Services for command requests and responses. Core Command will also have an external MQTT connection to receive requests from external services. In the future, Device Services will receive Device System Events via the EdgeX MessageBus rather than the current REST callbacks used when devices are added/updated/deleted in Core Metadata. + +## Message Envelope + +All messages to be published to the EdgeX MessageBus are wrapped in a `MessageEnvelope`. This envelope contains metadata describing the message payload, such as the payload Content Type (JSON or CBOR) and Correlation Id. The upcoming [North South Messaging](../../../design/adr/0023-North-South-Messaging) implementation will add additional metadata items. + +!!! note + Unless noted below, the `MessageEnvelope` is JSON encode when publishing it to the EdgeX MessageBus. This does result in the `MessageEnvelope`'s payload being double encoded. + +## Implementations + +The EdgeX MessageBus is defined by the message bus abstraction implemented in [go-mod-messaging](https://github.com/edgexfoundry/go-mod-messaging). This module defines an abstract client API which currently has five implementations of the API for the different underlying message bus protocols. Each service that uses the EdgeX MessageBus has a configuration section which defines which implementation to use and how to connect and configure the specific underlying protocol client. This section is `[Trigger.EdgexMessageBus]` for [Application Services](../../application/GeneralAppServiceConfig) and`[MessageQueue]` for [Core Data](../../core/data/Ch-CoreData/#configuration-properties), [Core Metadata](../../core/metadata/Ch-Metadata/#configuration-properties) and [Device Services](../../device/Ch-DeviceServices/#configuration-properties). The `Type` setting specifies which of the following implementations to use. + +- **Redis Pub/Sub** (**default**) - `Type=redis` +- **MQTT 3.1** - `Type=mqtt` +- **NATS Core** - `Type=nats-core` +- **NATS JetStream** - `Type=nats-jetstream` +- **ZeroMQ** (**DEPRECATED**) - `Type=zero` + +!!! note + I general all EdgeX Services running in a deployment must be configured to use the same EdgeX MessageBus implementation. By default all services that use the EdgeX MessageBus are configured to use the Redis implementation. NATS does support a compatibility mode with MQTT. See the [NATS MQTT Mode](#nats-mqtt-mode) section below for details. + +### Redis Pub/Sub + +As stated above this is the default implementation that all EdgeX Services are configured to use. It takes advantage of the existing Redis DB instance for the broker. Redis Pub/Sub is a fire and forget protocol, so delivery is not guaranteed. There are no additional configuration options for this implementation. If more robustness is required, use the MQTT or NATS implementations. + +!!! example - "Example `MessageQueue` configuration from Core Data using `redis`" + ```toml + [MessageQueue] + Protocol = "redis" + Host = "localhost" + Port = 6379 + Type = "redis" + AuthMode = "usernamepassword" # required for redis messagebus (secure or insecure). + SecretName = "redisdb" + PublishTopicPrefix = "edgex/events/core" # /// will be added to this Publish Topic prefix + SubscribeEnabled = true + SubscribeTopic = "edgex/events/device/#" # required for subscribing to Events from MessageBus + ``` + +### MQTT 3.1 + +Robust message bus protocol, which has additional configuration options for robustness and requires an additional MQTT Broker to be running. See [MQTT Spec](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) for more details on this protocol. + +!!! example - "Example `MessageQueue` configuration from Core Data using `mqtt`" + ```toml + [MessageQueue] + Protocol = "mqtt" + Host = "localhost" + Port = 1883 + Type = "tcp" + AuthMode = "none" # Currently MQTT auth not supported + PublishTopicPrefix = "edgex/events/core" # // will be added to this Publish Topic prefix + SubscribeEnabled = true + SubscribeTopic = "edgex/events/device/#" # required for subscribing to Events from MessageBus + [MessageQueue.Optional] + # Default MQTT Specific options that need to be here to enable evnironment variable overrides of them + # Client Identifiers + ClientId ="core-data" + # Connection information + Qos = "0" # Quality of Sevice values are 0 (At most once), 1 (At least once) or 2 (Exactly once) + KeepAlive = "10" # Seconds (must be 2 or greater) + Retained = "false" + AutoReconnect = "true" + ConnectTimeout = "5" # Seconds + CleanSession = "false" + ``` + +#### Additional MQTT Options + +| Option | Description | +| -------------- | ------------------------------------------------------------ | +| ClientId | Unique name of the client connecting to the MQTT broker | +| Qos | Quality of Service level
0: At most once delivery
1: At least once delivery
2: Exactly once delivery
See the [MQTT QOS Spec](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718099) for more details | +| KeepAlive | Maximum time interval in seconds that is permitted to elapse between the point at which the client finishes transmitting one control packet and the point it starts sending the next. If exceeded, the broker will close the client connection | +| Retained | If true, Server MUST store the Application Message and its QoS, so that it can be delivered to future subscribers whose subscriptions match its topic name | +| AutoReconnect | If true, automatically attempts to reconnect to the broker when connection is lost | +| ConnectTimeout | Timeout in seconds for the connection to the broker to be successful | +| CleanSession | if true, Server MUST discard any previous Session and start a new one. This Session lasts as long as the Network Connection | + +### NATS + +Description TBD + +#### NATS Core + +Description TBD + +#### NATS JetStream + +Description TBD + +#### Additional NATS Options + +| Option | Description | +| ----------------------- | ------------------------------------------------------------ | +| ClientId | Unique name of the client connecting to the NATS Server | +| Format | Format of the actual message published. Valid values are:
- **nats** : Metadata from the `MessageEnvlope` are put into the NATS header and the payload from the `MessageEnvlope` is published as is. **Preferred format when all services are using NATS**
- **json** : JSON encodes the `MessageEnvelope` and publish it as the message. Use the for compatibility when other services using MQTT 3.1 and running NATS Server in MQTT mode. | +| Durable | Description TBD | +| AutoProvision | Description TBD | +| ConnectTimeout | Timeout in seconds for the connection to the broker to be successful | +| RetryOnFailedConnect | Description TBD | +| QueueGroup | Description TBD | +| Deliver | Description TBD | +| DefaultPubRetryAttempts | Description TBD | + +#### NATS MQTT Mode + +Description TBD + +### ZeroMQ (DEPRECATED) + +ZeroMQ is a broker-less TCP based message bus protocol. Since it is broker-less, there can only a be a single publisher and many subscribers. Once Device Services also started publishing to the EdgeX MessageBus, ZeroMQ became unusable, thus it has been deprecated and will be removed in the next major release. + +## Multi-level topics and wildcards + +The EdgeX MessageBus uses multi-level topics and wildcards to allow filtering of data via subscriptions and has standardized on a MQTT like scheme. See [MQTT multi-level topics and wildcards](https://www.hivemq.com/blog/mqtt-essentials-part-5-mqtt-topics-best-practices) for more information. + +The Redis implementation converts the Redis Pub/Sub multi-level topic scheme to one similar to MQTT. In Redis Pub/Sub the "**.**" is used as a level separator and the "*" is used as a wildcard. These are converted to "/" and "#" respectively, which are used by MQTT. MQTT additionally uses the "+" as a wildcard for single levels and the "#" for multi-level (only at the end). The Redis implementation uses the "#" for both the single and multi-level wildcard. + +!!! note + The inconsistency with how the Redis implementation handles multi-level topics and wildcards not being 100% compliant with the MQTT scheme will be resolved in the next major release. + +The NATS implementations convert the NATS multi-level topic scheme to match that of MQTT. In NATS "**.**" is used as a level separator, "*" is used as the single level wildcard and "**>**" is used for the multi-level wild card. These are converted to "/", "+" and "#" respectively, which are compliant with the MQTT scheme. + +!!! example - "Example Multi-level topics and wildcards for EdgeX MessageBus - *Redis implementation*" + - **edgex/events/#** + + All events coming from device services or core data for any device profile, device or source + + - **edgex/events/device/#** + + All events coming from device services for any device profile, device or source + + - **edgex/events/#/#/camera-001/#** + + Only events coming from device services or core data for any device profile, but only for the device "camera-001" and for any source + + - **edgex/events/device/onvif/#/status** + + Only events coming from device services for only the device profile "onvif", and any device and only for the source "status" + + + +!!! example - "Example Multi-level topics and wildcards for EdgeX MessageBus - *MQTT 3.1 and NATS implementations*" + - **edgex/events/#** + + All events coming from device services or core data for any device profile, device or source + + - **edgex/events/device/#** + + All events coming from device services for any device profile, device or source + + - **edgex/events/+/+/camera-001/#** + + Only events coming from device services or core data for any device profile, but only for the device "camera-001" and for any source + + - **edgex/events/device/onvif/+/status** + + Only events coming from device services for only the device profile "onvif", and any device and only for the source "status" diff --git a/mkdocs.yml b/mkdocs.yml index b778396c69..8623f30fd4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -66,6 +66,7 @@ nav: - './microservices/configuration/CommonEnvironmentVariables.md' - './microservices/configuration/ConfigurationAndRegistry.md' - './microservices/configuration/V2MigrationCommonConfig.md' + - './microservices/general/messagebus.md' - Core Services: - './microservices/core/Ch-CoreServices.md' - './microservices/core/data/Ch-CoreData.md' @@ -197,6 +198,6 @@ plugins: enabled: !ENV [ENABLED_HTMLPROOFER, False] raise_error: True raise_error_excludes: - 404: ['https://support.google.com/accounts/answer/185833?hl=en', + 404: ['https://support.google.com/accounts/answer/185833?hl=en', 'https://support.google.com/accounts/answer/6010255?hl=en'] 429: ['*']