Enterprise Service Bus (ESB)
The CloudCenter platorm provides a framework to enable enterprises to integrate the CCM with a messaging service bus (referred to as the Enterprise Service Bus, ESB) system interface using RabbitMQ, an external AMQP Message Broker. The CCM works with service bus interface to accept message requests, and allows external consumers to listen to the CloudCenter logs and status messages.
CloudCenter's ESB feature provides the following benefits:
- Publish CloudCenter event logs via the ESB interface.
- Process (request and reply) messages generated via the ESB interface.
- Execute tasks as directed by messages. For example:
- User account management events
- Group and role management events
- Vendor account management events
- Application execution and launch control events
Be sure to configure RabbitMQ to perform any authentication using SSL certificates. This allows RabbitMQ to verify any enterprise client connecting to RabbitMQ.
Refer to the RabbitMQ documentation for additional details.
The ESB Functionality
As an alternative to using APIs to execute CloudCenter tasks, some enterprises may prefer to send a request message using the message bus and use the processed information at a later point (also using the message bus).
Each time CloudCenter receives a request on the service bus, CloudCenter performs a corresponding REST API call and submits the response as message back to the service bus.
CloudCenter uses RabbitMQ as the Opensource message broker to implement AMQP. As such, the CloudCenter platform provides message-oriented communication with message-delivery guarantee where each message is certain to be delivered asynchronously. RabbitMQ messages are sent in one direction over an established link. The ESB message can be simulated to be a request or a response. For example, if a task is going to take a long time to complete, the enterprise (client) submits the message (along with header properties that provides the reply location for the message) to the message bus and when the resource becomes available and/or the timing is right, then the message is processed. CloudCenter ESB provides a asynchronous response depending on how quickly the message is processed. The asynchronous nature of the message bus allows systems to proceed with their integrated workflows without waiting for a response (the notion of submit and forget for non-critical work).
Prerequisites to Use the ESB Functionality
To use the ESB functionality, follow these requirements:
- Open either or both these ports to use the ESB functionality:
- Port 15672: For two-way communication with the ESB AMQP module in the CCM. This port must be open if you need to establish access to the AMQP module from the AMQP UI.
- Port 5671: For two-way communication with the ESB AMQP module in the CCM. This port must be open if you need to establish programmatic access to the AMQP module.
Install the ESB module when you install the CCM component by manually editing the following properties in the ccm-response.xml file.
Be aware that the ESB module is optional and you must explicitly customize your CCM installation to include this option.
Response files allows you to provide system information during the installation as these files have a <userinput> tag that you can use to modify the deployment information. The following table explains the possible values that you can modify.
Response file option Value Notes <entry key="esb_enable" value="false"/> true = Enable ESB
false = Disable ESB (default)
You must Enable ESB!
- Configure the ESB settings in the CCM Wizard to communicate with the AMQP and CCM servers.
- Create two standard users (cliqruser and clientuser) and give them full privileges to access the CCM server.
- Configure cliqruser to be the Tenant Administrator.
- Before using the ESB functionality, retrieve the user information (one of three details: user name, user email, External ID) and the Tenant ID. This information is required for this user to submit messages to the ESB.
To send ESB messages, a user needs to be logged in and authenticated at two levels:
- To send a message using RabbitMQ, the client must use the credentials to connect to RabbitMQ and have the ability to exchange ESB messages.
- The client must have a valid service certificates to connect to Rabbit MQ.
- To submit a request, the client must provide the following information:
- Any one of the following user details:
- The tenant to which the user belongs – the tenant short name or Tenant ID. See Add Sub-Tenants > Tenant ID and Tenant Name Dependency for additional context).
CloudCenter Documentation Convention
CloudCenter documentation uses the following conventions:
- Name — Identifies a required CloudCenter attribute name required for each ESB message. For example, tenant.
- Value — Identifies a generated CloudCenter value required for each ESB message. For example, tenantId, is the actual value for the attribute and will be replaced by the ID (tenants/1 will indicated a tenant with the ID of 1).
Message Request Format
CloudCenter ESB messages have a header and a body requirement (similar to an API). The only difference between APIs and ESB messages is that ESB messages do not use URLs. CloudCenter's ESB implementation maps all request messages to CloudCenter REST APIs by inspecting the action header in the request message. If you know the REST API of the operation you want to perform then you can perform the same operation over the service bus by formatting the action header using following rules.
The ESB message request must use the following format:
Type: The ESB message type directly maps to the following HTTP methods:
HTTP Method Type of Request POST create PUT update GET get DELETE delete
- v1 APIs: The CloudCenter platform's support action header mapping to v1 apis (do not specify the version)
- Delimiter: ESB messages use . (period) as a path delimiter instead of the / (forward slash) as used in CloudCenter API calls. (always provide the delimiter)
- Query parameters:
- The notion of a REST URL with query paramters gets split into
actionparamheaders with the action containing the HTTP method and the URL path and the actionparam containing the query parameters.
- For query parameter support use
actionparamheader to contain the name/value key pair separated by & character (ignore the ? and always add the & and = exactly as you would in the HTTP URL)
- If using parameters to query the system, see the following table for an example.
- The notion of a REST URL with query paramters gets split into
Replace elements in italics, tenantId and contractId with the actual value of the resource. For example,
should be issued as
Message Request Examples
The following table lists some ESB message request examples using this format:
|CloudCenter API Request Format|
CloudCenter ESB Header
CloudCenter ESB Header
Each API displays a line item to identify the corresponding ESB Header for each API. See REST API v1.0 for CloudCenter 4.x to view list of available CloudCenter APIs. CloudCenter supports ESB message mapping to v1 APIs.
CloudCenter provides the following predefined properties for the message header.
Indicates the operation or action to perform on the message bus. See the Message Request Format section for additional information.
Query parameter string that should be used in the REST API calls to the CCM.
The CloudCenter user sending the ESB message.
Yes. Only one of these three properties is required.
The email for this CloudCenter user.
|externalID||The External ID for this CloudCenter user, if a SSO (or similar) setup|
|tenant||The tenant to which the user belongs – the tenant short name.||Yes|
Indicates the message format to use in the message request. Currently only JSON is supported (for example, application/json).
Used to parse the message body. If this header is not set then UTF-8 encoding will be used.
Reply destination for response – any response after the message is processed is sent to this location.
If this header is not set, then the message bus does not send a reply.
Clients must ensure that the reply exchange exists and are configured properly.
If the response message is not routable, RabbitMQ silently drops these messages.
|Yes – to receive a response|
A unique identifier generated by client to correlate requests and responses.
This property is useful if the same location is used to receive replies for multiple messages. If present in the request header, then the message listener echos it back as the header in the reply message.
This header does not affect message processing.
The ESB message body contains the request attributes in JSON format and is compatible with the message body provided in CloudCenter APIs (where applicable). See the relevant API documentation listed in the API section for additional context.
The following is an example of a ESB header request and message body.
The CloudCenter platform provides the following predefined properties for the response header.
This is set to OK if request was successfully processed or ERROR if these was any error in processing the request.
If a correlationId was provided in the message request then it is echoed back in response header.
Indicates the message format to use in the response body. Currently only JSON is supported (for example, application/json).
If the CloudCenter platform is unable to send a response due to a programmatic error (internal server error) or if an application has crashed or if a reply destination is not set, then these message fail to process and the CloudCenter platform routes them to the error exchange.
For messages that are routed to the error exchange, clients can configure the following additional headers (in addition to the headers sent by the client).
Original exchange of the message.
Original routing key of the message.
A human readable error message.
The CCM additionally generates notification messages (in addition to request and response messages) that enterprises can access on the message bus. Clients can subscribe to and receive notifications from the notifications server. The notifications server forwards these messages as RabbitMQ messages.
Notifications are sent to cliqr.notifications.exchange, a Topic Exchange and dispatches the messages where the routing key matches the queue (based on the queue binding key).
Notifications are sent for the following actions:
- VM actions:
- Launching a VM
- Terminating a VM
- Action APIs:
- Create (POST) APIs
- Update (PUT) APIs
Suspend and Resume Jobs
Be aware of the following nuances:
- The message in the response queue displays the latest action.
- You can retrieve the status of asynchronous APIs by issuing a get.jobs.jobId request.
Each notification message from the CloudCenter platform contains the following routing key format:
|Routing Key Property||Options and Description|
|cliqr||This property is required and does not have any options|
This keyword is replaced by one of these options:
|resource_id||This keyword is replace by a unique identifier for the resource on which an action was performed.|
|action||This keyword is replace by the action performed on the service.|
The severity keyword is replace by one of these options:
- No labels