CliQr is now part of Cisco Learn More About Cisco

Enterprise Service Bus (ESB)

Overview

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

Advanced Security

Icon

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:

  1. Open either or both these ports to use the ESB functionality:
    1. 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.
    2. 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.
      ESB Image
  2. Install the ESB module when you install the CCM component by manually editing the following properties in the ccm-response.xml file.

    Icon

    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 optionValueNotes
    <entry key="esb_enable" value="false"/>true = Enable ESB
    false = Disable ESB (default)

    You must Enable ESB!

  3. Configure the ESB settings in the CCM Wizard to communicate with the AMQP and CCM servers.
  4. Create two standard users (cliqruser and clientuser) and give them full privileges to access the CCM server.
  5. Configure cliqruser to be the Tenant Administrator.
  6. 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.

ESB Authentication

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 CloudCenter user name (see Create Standard Users for additional context).
      • The user email for this CloudCenter user (see Create Standard Users for additional context).
      • The user's External Id – if in a SSO setup (see SAML SSO for additional context)
    • 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 MethodType of Request
    POSTcreate
    PUTupdate
    GETget
    DELETEdelete
  • 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 action and actionparam headers with the action containing the HTTP method and the URL path and the actionparam containing the query parameters.
    • For query parameter support use actionparam header 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.
  • Replace elements in italics, tenantId and contractId with the actual value of the resource. For example,
    create.tenants.tenantId.contracts
    should be issued as
    create.tenants.1.contracts

Message Request Examples

The following table lists some ESB message request examples using this format:

CloudCenter API Request Format

CloudCenter ESB Header

action

CloudCenter ESB Header

actionparam

POST /v1/tenants/tenantId
/contracts
create.tenants.tenantId.contractsNone
PUT /v1/tenants/tenantId
/contracts/contractId
update.tenants.tenantId.contracts.contractIdNone
DELETE /v1/tenants/tenantId
/contracts/contractId
delete.tenants.tenantId.contracts.contractIdNone
GET /v1/tenants/tenantId
/contracts/contractId
get.tenants.tenantId.contracts.contractIdNone
GET v1/cloudProperties
/regionName?
propertyType=propertyType&
depEnv=depEnvId&
cloudAccount=cloudAccountid
cloudProperties.regionNamepropertyType=propertyType&
depEnv=depEnvId&
cloudAccount=cloudAccountid
Icon

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.

Message Header

CloudCenter provides the following predefined properties for the message header.

Header PropertiesDescriptionRequired?

action

Indicates the operation or action to perform on the message bus. See the Message Request Format section for additional information. 

Yes

actionparam

Query parameter string that should be used in the REST API calls to the CCM.

 

username

The CloudCenter user sending the ESB message.

 

Yes. Only one of these three properties is required.

email

The email for this CloudCenter user.

externalIDThe External ID for this CloudCenter user, if a SSO (or similar) setup
tenantThe tenant to which the user belongs – the tenant short name.Yes

contentType

Indicates the message format to use in the message request. Currently only JSON is supported (for example, application/json).

No

contentEncoding

Used to parse the message body. If this header is not set then UTF-8 encoding will be used.

 

reply_to

Reply destination for response – any response after the message is processed is sent to this location.

Icon

 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.

Icon

If the response message is not routable, RabbitMQ silently drops these messages.

Yes – to receive a response

correlation_Id

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.

 

Message Body

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.

Header

Value

username

cliqradmin

tenant

company1

action

create.users

correlation_id

1

statusOK
Message Body

Response Headers

The CloudCenter platform provides the following predefined properties for the response header.

PropertyDescription

status

This is set to OK if request was successfully processed or ERROR if these was any error in processing the request.

correlationId

If a correlationId was provided in the message request then it is echoed back in response header.

contentType

Indicates the message format to use in the response body. Currently only JSON is supported (for example, application/json).

Error Exchange

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).

PropertyDescription

x-original-exchange

Original exchange of the message.

x-original-routingKey

Original routing key of the message.

x-exception-message

A human readable error message.

Notification Messages

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

Icon

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 PropertyOptions and Description
cliqrThis property is required and does not have any options
service

This keyword is replaced by one of these options:

  • user = user management
  • tenant = tenant management
  • app = application management
  • depmgmt = deployment management
  • cloudmgmt = cloud management
resource_idThis keyword is replace by a unique identifier for the resource on which an action was performed.
actionThis keyword is replace by the action performed on the service.
severity

The severity keyword is replace by one of these options:

  • debug
  • info
  • warn
  • error

 

 

  • No labels