Microgateway Configuration

A Microgateway allows a Solace PubSub+ event broker to act as an HTTP load balancer, or simple API gateway between a RESTful API Client and remote microservices. For more information, refer to Microgateways.

This section describes the various limitations of Microgateways and provides a list of the configuration parameters that are required before an event broker can act as a Microgateway.

To propagate REST requests through the event broker it must first be configured for basic Guaranteed Messaging. Refer to Guaranteed Messaging Configuration for more information. In addition, special consideration must be taken when configuring queues used in a Microgateway deployment. For more information refer to Configuring Queues for a Microgateway.

Limitations

Microgateways have the following limitations:

  • The HTTP CONNECT and TRACE methods are not supported.
  • The event broker does not support the ability to change the original HTTP method when the REST delivery point (RDP) delivers a message to the REST consumer.
  • The event broker does not support the ability to change the query parameters of messages when the RDP delivers a message to the REST consumer.
  • The event broker does not support eavesdropping applications over HTTP. The only applications that can receive requests over HTTP are the remote microservices. If you add an eavesdropping HTTP application, responses from both the microservices and the eavesdropping application result in a race condition for the originating REST client.
  • Many functions of API gateways are not provided with the Microgateway feature including:
    • Fan-out and response consolidation
    • Payload transformation
    • API lifecycle management
    • API version control

Configuring to Receive REST Requests

Follow the steps below to configure a Solace PubSub+ event broker to receive REST requests.

  1. Enable system level REST service for incoming REST connections (refer to REST Service Management).
  2. Configure incoming REST service for one or more Message VPNs (refer to Configuring Incoming Connections).
    1. Specify a dedicated listen port for the REST service (refer to Setting Listen Ports).
    2. Configure REST for either plain-text or SSL service (refer to Enabling REST Plain Text Service and Enabling REST SSL Service).
  3. Enable gateway mode for the Message VPNs (refer to Configuring the REST Message VPN Mode).
  4. Optionally, configure ACLs to control the URIs that REST clients have access to, and the HTTP methods they are allowed to use (refer to ACL Configuration).

Configuring to Publish REST Requests

Follow the steps below to configure a Solace PubSub+ event broker to publish REST requests.

  1. Enable system-level REST service for outgoing REST connections (refer to Enabling Outgoing REST Connections).
  2. Configure and enable a REST delivery point (RDP) within a REST-enable Message VPN (refer to Managing REST Delivery Points).
    1. Configure at least one queue binding for the RDP (refer to Managing REST Delivery Points).
    2. Optionally, configure how the event broker handles the authority value in outbound URIs (refer to Managing REST Delivery Points).
  3. Configure and enable a REST consumer (refer to Managing REST Delivery Points).
    1. Configure connection parameters for the REST consumer (refer to Managing REST Delivery Points).

Configuring the REST Message VPN Mode

By default, REST-enabled VPNs operate in messaging mode.

To configure the REST Message VPN mode, enter the following CONFIG command:

solace(configure/message-vpn/service/rest)# mode {gateway | messaging}

Where:

gateway configures the Message VPN to act as a Microgateway through which REST messages are propagated.

messaging configures the Message VPN to act as an event broker on which REST messages are queued.

The no version of the this command (no mode) returns the Message VPN to the default mode (messaging).

Configuring Queues for a Microgateway

Configuring a Message VPN to act as a Microgateway alters the way the event broker encodes incoming requests and responses for internal transportation. This change in processing requires careful consideration when creating queues for traffic management, or when adding eavesdropping applications to the deployment.

Configuring Queues for Traffic Management to Microservices

Message VPNs configured to act as Microgateways encode the HTTP method (POST, GET, DELETE) and path of incoming requests to Solace message topics for internal transportation. This enables the event broker to deliver each HTTP method to separate queues. You can use this functionality to configure traffic management to remote microservices.

To add a topic subscription to a queue used in a Microgateway deployment enter the following CONFIG command. 

solace(configure/message-spool/queue)# subscription topic <HTTP method>/<target-path>

For example, to add a subscription for all POST requests with a specific path:

solace(configure/message-spool/queue)# subscription topic POST/store/orders

To add a subscription for all HTTP requests with a specific path:

solace(configure/message-spool/queue)# subscription topic */store/account/orders

To add subscriptions for individual HTTP methods regardless of path:

solace(configure/message-spool/queue)# subscription topic POST/>
solace(configure/message-spool/queue)# subscription topic GET/>

For an example describing how to configure queues for traffic management to microservices, refer to Traffic Management to Microservices Example.

Configuring Queues for Eavesdropping Applications

In order for the eavesdropping application to receive requests and responses propagated by the Microgateway, you must add the following topic subscriptions to each corresponding queue:

  • One or more subscriptions that match existing subscriptions used to receive requests from REST clients.
  • One or more subscriptions that correspond with the reply-to topics generated by the event broker. These topics are generated according to the following format: #P2P/<virtual-router-name>/_rest-<tsid>/<request-method>/<request-path>.

For example, to add a topic subscription to a queue so that a corresponding eavesdropping application receives all responses from remote microservices:

solace(configure/message-spool/queue)# subscription topic #P2P/v:solace/_rest-*/>

For an example describing how to configure queues for eavesdropping applications, refer to Eavesdropping Application Example.

Passing OAuth Tokens to REST Consumers

In a REST/HTTP client connection, the event broker uses the Authorization: basic <b64_username_password> HTTP header field for its own authentication. In gateway mode, the broker passes any type of authorization header other than basic through to the REST consumer. You can use this mechanism to pass OAuth credentials through the broker to have the remote host handle the authorization.

To pass OAuth credentials through the broker, configure the REST clients to insert the OAuth token in a bearer type authorization header:

Authorization: bearer <oauth_bearer_access_token>

This header is passed through the broker and will be received unchanged by the remote server. Because the broker does not validate anything in the header, you must ensure that the OAuth token has not expired and will work as expected at the destination.

OAuth tokens can be very long. PubSub+ event brokers don't impose any limit on the size of an HTTP header field, except that the HTTP header fields must all fit into the overall message size limitations (approximately 30MB for guaranteed messages in most cases). In addition, although HTTP allows header field values to be split across multiple lines, we recommend using one line per HTTP header field.

In gateway mode, the PubSub+ event broker passes duplicate HTTP header fields through to the remote server. If a REST client sends multiple (non-basic) authorization headers, they are all passed unchanged through the event broker; the remote server is expected to handle these duplicate headers gracefully.