PUBLIC RabbitMQ Service SAP SE or an SAP affiliate company. All rights reserved. THE BEST RUN

Transcription

1 PUBLIC SAP SE or an SAP affiliate company. All rights reserved. THE BEST RUN

2 Content 1 Overview The RabbitMQ Cluster Access the Service Use the Service Binding Supported Plug-ins Major version upgrade from RabbitMQ 3.6 to Tutorial Build Your Application Data Protection and Privacy Frequently Asked Questions P U B L I C Content

3 1 Overview RabbitMQ is an open-source message broker service available on SAP Cloud Platform. This service enables robust messaging between applications. It supports asynchronous messaging. It is a free service with limited resources and available for development purposes. The cluster layout of the service ensures high availability. The key capabilities of RabbitMQ are: Provides robust messaging between applications Supports High Availability (HA) using clustering Enables direct connectivity between applications written in different programming languages The benefits of using RabbitMQ are: Scale up your application by connecting to several applications RabbitMQ implements the Advanced Message Queuing Protocol (AMQP), the open standard for passing business messages between applications. It connects systems, feeds business processes with the information they need and reliably transmits onward the instructions that achieve their goals. Get support from a large open-source community 1.1 The RabbitMQ Cluster All service plans that are intended for productive usage are dedicated high available cluster deployments. The RabbitMQ services of all the plans have two load balancers. They are configured for automatically routing connections in case of a failover. Both load balancers limit the number of connections to Clients randomly connect to a load balancer and ensure that the connections are equally distributed between the load balancers. The figure below shows the service connected to the load balancer: Overview P U B L I C 3

4 Only the xsmall service plan of RabbitMQ 3.6 version contains a RabbitMQ cluster with three nodes. The message consumer and producer connects to one of the three nodes directly. Clients may randomize the Advanced Message Queue Protocol (AMQP) to load balance the amount of connections per node. We provide high availability policy that creates one master and two slaves per queue. You may create different policies with a higher priority to increase the message throughput at the cost of high availability. It is not recommended to use two similar policies as this may cause unavailability of specific queues during a cluster update. For more information, see the official RabbitMQ documentation 4 P U B L I C Overview

5 1.2 Access the Service This procedure helps you to access the RabbitMQ service. Context The service is listed in the Service marketplace as RabbitMQ. You can view the service using the following steps: Procedure 1. Log on to SAP Cloud Platform. 2. Choose an Org. 3. Choose a space within the Org. 4. In the navigation area on the right, choose Services Service Marketplace. The RabbitMQ service appears in the list. 1.3 Use the Service To use the RabbitMQ service, you need to create an instance of the service and bind the service with your application. Context You can use the command line interface to carry out the task. Procedure 1. Check the Service Marketplace to see if the RabbitMQ service is listed using the command: cf marketplace 2. Create an instance of the service using the command:cf create-service rabbitmq <service plan name> <instance name> Overview P U B L I C 5

6 3. Bind the service instance to the application using the command: cf bind-service <application name> <instance name> -c '{"read_permission":"blue.*", "write_permission": "blue.*","configure_permission": "blue.*", "role":"management"}' For more information about binding, see the Binding [page 6] topic. 4. Check if the instance is successfully bound to the application using the command: cf env <application name> Note If the instance is successfully bound you will find the RabbitMQ details along with its credentials in the VCAP_SERVICES environment variable. 5. Restage your application to use the binding credentials using the command: cf restage <application name> 1.4 Binding You can bind the RabbitMQ service to an application using only the mandatory information such as the application name and the service name. The service uses default values for the read, write, or configure privileges. These privileges allow the application to read or write and configure any AMQP resource. In addition, the user generated for a binding is tagged with policy maker. The application bound to the service will use the administration API to define RabbitMQ policies. For more information, see If you need to change the default values during service binding, specify read, write, and configure privileges during the binding. Additionally, choose one of the following tags to specify the access privileges for the management API: (None) No access to the management plug-in management policymaker monitoring 1.5 Supported Plug-ins The following plugins are supported by RabbitMQ on SAP Cloud Platform: rabbitmq-management rabbitmq_jms_topic_exchange rabbitmq_stomp rabbitmq_web_stomp rabbitmq_mqtt rabbitmq_web_mqtt 6 P U B L I C Overview

7 rabbitmq_amqp1_0 (supported only with RabbitMQ 3.7 plans) Enablement of the plugins STOMP, MQTT and AMQP 1.0 plugins are not enabled by default. To enable them, provide the following configuration parameters respectively during instance create or update calls: STOMP: c { stomp_enabled : true}' MQTT: c { mqtt_enabled : true}' AMQP: c { amqp1_0_enabled : true}' Note cf create-service rabbitmq v3.6-small rmq_cluster c { stomp_enabled : true} cf create-service rabbitmq v3.7-small rmq_cluster c { mqtt_enabled : true} cf create-service rabbitmq v3.7-small rmq_cluster c { amqp1_0_enabled : true} Note All the above plugins are enabled by default in dev plan for trial. Overview P U B L I C 7

8 2 Major version upgrade from RabbitMQ 3.6 to 3.7 The community edition of RabbitMQ 3.6 version has reached end of life. There are no more features, bug fixes, or security fixes provided for the 3.6 version. On the SAP Cloud platform, RabbitMQ 3.6 version reaches end of life by September Support for upgrading existing 3.6 to 3.7 is now available. When the upgrade is triggered, existing 3.6 instances are upgraded from 3.6 to 3.7 version. Please note that there will be a downtime during this upgrade. Upgrade recommendations All nodes in the cluster should be healthy. About 60% of free disk space should be available for the major version upgrade to succeed. (For example: XSMALL plan - Total Disk Size: 10 GB, Free Disk Space before Major Version Upgrade: 6 GB). If there is no enough disk space, please wait for the consumer application to consume the messages before proceeding with the upgrade. You trigger the upgrade on RabbitMQ 3.6 instance using cf update-service command. cf update-service <service_instance_name> -p <3.7_plan_name> For example: cf update-service my-rabbitmq-instance -p v3.7-xsmall If you have any test instances, we recommend that you perform upgrade on test instances first to verify that the upgrade is successful and your applications work as expected. Note There is no support for upgrading dev plans from 3.6 to 3.7. Delete any existing 3.6 dev instances, instead use 3.7 dev instances. In 3.7-xsmall plan, the load balancers are introduced. So when a 3.6-xsmall plan is upgraded to 3.7-* plan, restaging is required for the applications to use the load balancers. For any other plan, no restaging is required. How long will the upgrade take to finish? The actual time taken for the upgrade depends on the amount of messages available in the rabbitmq instance. Given below are approximate times taken per plan with disks filled up to capacity: Given below are approximate times taken per plan with disks filled up to capacity: 8 P U B L I C Major version upgrade from RabbitMQ 3.6 to 3.7

9 Plan Messages size in instance Time taken xsmall 1.5 GB ~ 3 minutes 40 seconds small medium large Is there a downtime involved? Yes, there is a downtime involved when major version upgrade is triggered. We recommend that you plan the upgrade of your production instances within a maintenance window to avoid any potential issues. For any issues that you face during upgrades, create a ticket on the component BC-NEO-BS-RABBITMQ. Major version upgrade from RabbitMQ 3.6 to 3.7 P U B L I C 9

10 3 Tutorial This tutorial summarizes the basic steps for sending and receiving messages using RabbitMQ service. Prerequisites You have downloaded Cloud Foundry CLI available at Github. You have installed a JDK 1.8 available on the Oracle Download page. You have downloaded Maven 3.0 available on the Apache Maven Project Download page. You have downloaded Git available on the Git Download page. Procedure 1. Clone the project from github. git clone 2. Log on to the Cloud Foundry and navigate to the organization and space you have access to. cf api api.cf.<host information> cf login Note For more information about the host specific to your region, see Regions and Hosts. 3. Create a service instance. cf create-service rabbitmq v3.6-dev rabbitmq-service Tip The version of the RabbitMQ service changes on a regular basis. To check the version, use the cf marketplace command. 4. Build the sample project. For more information, see the section More Details: How the Application Is Built. cd hcp-cloud-foundry-tutorials/hcp-cf-rabbitmq-tutorial mvn package 5. Modify the manifest.yml, change the host to something unique so that the application push does not fail, and then push the project. cf push 10 P U B L I C Tutorial

11 It is possible that the application push might fail with the following error: Server error, status code: 400, error code: , message: The host is taken: Just change the host value in the manifest.yml file to something unique. Now the push should work. 6. Run the project in your Web browser using the URL that was created after you pushed the application. Build Your Application The procedure explains how to build your application. 1. Create the java maven project: mvn archetype:generate -DgroupId=hcp-cf-redis-tutorial -DartifactId=hcp-cfrabbitmq-tutorial -DinteractiveMode=false 2. Once the project has been created, edit your pom.xml file to put all the relevant dependencies. It should look similar to this pom.xml sample file. 3. Create a manifest.yml file, which contains the cf configuration details and looks similar to this manifest.xml sample file. To prevent an application push from failing because the host has already been assigned, make sure that your host value is unique. 4. Setup a Spring Boot starter class, which starts the application and should look similar to this HCPWebApplication.java sample file. For more information about Spring Boot, see the Spring Boot page. 5. Also setup an important class is the controller class, which is responsible for HTTP request mapping. The class should look like this RootController.java sample file. 6. Check the important aspect of controller class as explained: The codeblock shows the class structure that includes an important part of the database connection from the bound service. The tells you that it is a controller tells you that this class is called when the root URL of the app is hit. onrootaccess() is the method that handles the GET request, which is pointed to by = RequestMethod.GET) annotation. We have a redisconnectionfactory field that Therefore, a Redis connection can be created when parsing the service instance bound to this application. The tutorial uses the redisconnectionfactory to access Redis directly. package com.sap.hcp.cf.tutorials.rabbitmq; import java.util.arraylist; import java.util.list; import org.slf4j.logger; import org.slf4j.loggerfactory; import org.springframework.amqp.core.queue; import org.springframework.amqp.rabbit.core.rabbittemplate; import org.springframework.beans.factory.annotation.autowired; import org.springframework.context.annotation.bean; import org.springframework.stereotype.controller; import org.springframework.web.bind.annotation.requestmapping; import org.springframework.web.bind.annotation.requestmethod; import org.springframework.web.bind.annotation.responsebody; import com.sap.hcp.cf.tutorials.rabbitmq.model.rabbitmessage; public class RootController { Tutorial P U BL IC 11

12 private static final Logger log = private RabbitTemplate template; private static final String QUEUE_NAME = "amqp-test"; private static final String MESSAGE = Queue queue() { return new Queue(QUEUE_NAME, false); = RequestMethod.GET) Result onrootaccess() { RabbitMessage rabbitmessage = new RabbitMessage(); log.info("sending message: " + MESSAGE); template.convertandsend(queue_name, MESSAGE); rabbitmessage.setproducedmessage(message); log.info("receiving message: "); String msg = (String) template.receiveandconvert(queue_name); rabbitmessage.setconsumedmessage(msg); Result result = new Result(); result.setstatus("successfully connected to rabbit and produced a message and consumed the same message"); List<RabbitMessage> rabbitmessages = new ArrayList<RabbitMessage>(); rabbitmessages.add(rabbitmessage); result.setrabbitmessages(rabbitmessages); return result; } } Now this application is ready to be deployed. To push this newly created application to Cloud Foundry and run it, repeat the steps 2-5 of this tutorial. 12 P U B L I C Tutorial

13 4 Data Protection and Privacy Governments place legal requirements on industry to protect data and privacy. We provide features and functions to help you meet these requirements. Note SAP does not provide legal advice in any form. SAP software supports data protection compliance by providing security features and data protection-relevant functions, such as blocking and deletion of personal data. In many cases, compliance with applicable data protection and privacy laws is not covered by a product feature. Furthermore, this information should not be taken as advice or a recommendation regarding additional features that would be required in specific IT environments. Decisions related to data protection must be made on a case-by-case basis, taking into consideration the given system landscape and the applicable legal requirements. Definitions and other terms used in this documentation are not taken from a specific legal source. The following sections provide information about the RabbitMQ service. For the central data protection and privacy statement for SAP Cloud Platform, see Data protection and Privacy User Consent We assume that software operators, such as SAP customers, collect and store the consent of data subjects, before collecting personal data from data subjects. A data privacy specialist can later determine whether data subjects have granted, withdrawn, or denied consent. The RabbitMQ service does not provide any support for collecting and storing the consent of data subjects for applications built on SAP Cloud Platform. It is the responsibility of your applications to provide such support. Read-Access Logging and Change Log Read-access logging (RAL) is used to monitor and log read access to sensitive data. Data may be categorized as sensitive by law, by external company policy, or by internal company policy. Read-access logging enables you to answer questions about who accessed certain data within a specified time frame. For auditing purposes or for legal requirements, changes made to personal data should be logged, enabling the monitoring of what changes were made and when. The audit log entries are forwarded to the Audit Log service and stored there for a defined period of time. For more information on how to request your audit logs, see Request Extraction of Audit Logs. Data Protection and Privacy P U BL IC 13

14 Erasure When handling personal data, consider the legislation in the different countries where your organization operates. After the data has passed the end of purpose, regulations may require you to delete the data. However, additional regulations may require you to keep the data longer. During this period you must block access to the data by unauthorized persons until the end of the retention period, when the data is finally deleted. You can delete your RabbitMQ service instance, and therefore, all the definitions and the data stored in your RabbitMQ server. To do so, navigate to your sub account using the procedure Navigate to Global Accounts, Subaccounts, Orgs, and Spaces in the Cockpit and delete the service from the Overview page. Glossary Term Definition Consent Deletion Personal data Retention period The action of the data subject confirming that the usage of his or her personal data shall be allowed for a given purpose. A consent functionality allows the storage of a consent record in relation to a specific purpose and shows if a data subject has granted, withdrawn, or denied consent. Deletion of personal data so that the data is no longer available. Any information relating to an identified or identifiable natural person ("data subject"). An identifiable natural person is one who can be identified, directly or indirectly, in particular by reference to an identifier such as a name, an identification number, location data, an online identifier or to one or more factors specific to the physical, physiological, genetic, mental, economic, cultural, or social identity of that natural person The period of time between the end of the last business activity involving a specific object (for example, a business partner) and the deletion of the corresponding data, subject to applicable laws. The retention period is a combination of the residence period and the blocking period. 14 P U B L I C Data Protection and Privacy

15 Term Definition Sensitive personal data A category of personal data that usually includes the following type of information: Special categories of personal data, such as data revealing racial or ethnic origin, political opinions, religious or philosophical beliefs, trade union membership, genetic data, biometric data, data concerning health or sex life or sexual orientation, or personal data concerning bank and credit accounts. Personal data subject to professional secrecy Personal data relating to criminal or administrative offenses Personal data concerning insurances and bank or credit card accounts Data Protection and Privacy P U BL IC 15

16 5 Frequently Asked Questions In this section you will find answers to all your basic queries about RabbitMQ on SAP Cloud Platform in Cloud Foundry environment. What is the latest version that is supported? On the SAP Cloud platform, RabbitMQ supports two major versions 3.6 and 3.7. However, the 3.6 version will reach end of life by September Support for upgrading existing 3.6 to 3.7 is now available. When the upgrade is triggered, existing 3.6 instances are upgraded from 3.6 to 3.7 version. Where can I find the upgrade procedure? If you are using RabbitMQ 3.6 version, you must upgrade your service instance to 3.7. Check the details here [page 8]. What are the available service plans? There is a range of managed plans available to cater to your requirements: x-small, small, medium, large. You can check the details here. What is the maximum number of DB connections possible per plan? The maximum number of DB connections possible for each RabbitMQ plans (xsmall, small, medium, large) is What protocols are supported? RabbitMQ implements the Advanced Message Queuing Protocol (AMQP), the open standard for passing business messages between applications. It connects systems, feeds business processes with the information they need and reliably transmits onward the instructions that achieve their goals. 16 P U B L I C Frequently Asked Questions

17 What are the supported plugins? rabbitmq-management rabbitmq_jms_topic_exchange rabbitmq_stomp rabbitmq_web_stomp rabbitmq_mqtt rabbitmq_web_mqtt rabbitmq_amqp1_0 (supported only with RabbitMQ 3.7 plans) For more information on enabling the plugins, see Supported Plug-ins [page 6] What are the regions in which RabbitMQ is available? Infrastructure Region AWS Europe (Frankfurt) US East (VA) Brazil (São Paulo) Japan (Tokyo) GCP Azure US Central (IA) US West (CA) (BETA), Europe (Netherlands) How is Near Zero downtime maintained? To maintain near-zero downtime when applications face issues such as losing connection or losing consumer acknowledgments due to regular bi-weekly updates of RabbitMQ instances or network glitches, see. How to save consumer acknowledgments? First of all, make sure that the manual acknowledgments are sent by clients after receiving messages. Acknowledgments lost because of network glitches/rabbitmq updates should be resent. Some retry implementation should be in place so that if sending manual acknowledgments fails, they are resent. With failover logic in place, when retry is triggered, manual acknowledgments are sent to a healthy RabbitMQ node. The message will be removed from the queue and it would not hold up in queue forever. Frequently Asked Questions P U BL IC 17

18 Is multiple vhosts supported? Currently it not supported. I'm facing some technical problem. How do I seek support? For any technical issues, please create a ticket in the component BC-NEO-BS-RABBITMQ. 18 P U B L I C Frequently Asked Questions

19 Important Disclaimers and Legal Information Hyperlinks Some links are classified by an icon and/or a mouseover text. These links provide additional information. About the icons: Links with the icon : You are entering a Web site that is not hosted by SAP. By using such links, you agree (unless expressly stated otherwise in your agreements with SAP) to this: The content of the linked-to site is not SAP documentation. You may not infer any product claims against SAP based on this information. SAP does not agree or disagree with the content on the linked-to site, nor does SAP warrant the availability and correctness. SAP shall not be liable for any damages caused by the use of such content unless damages have been caused by SAP's gross negligence or willful misconduct. Links with the icon : You are leaving the documentation for that particular SAP product or service and are entering a SAP-hosted Web site. By using such links, you agree that (unless expressly stated otherwise in your agreements with SAP) you may not infer any product claims against SAP based on this information. Beta and Other Experimental Features Experimental features are not part of the officially delivered scope that SAP guarantees for future releases. This means that experimental features may be changed by SAP at any time for any reason without notice. Experimental features are not for productive use. You may not demonstrate, test, examine, evaluate or otherwise use the experimental features in a live operating environment or with data that has not been sufficiently backed up. The purpose of experimental features is to get feedback early on, allowing customers and partners to influence the future product accordingly. By providing your feedback (e.g. in the SAP Community), you accept that intellectual property rights of the contributions or derivative works shall remain the exclusive property of SAP. Example Code Any software coding and/or code snippets are examples. They are not for productive use. The example code is only intended to better explain and visualize the syntax and phrasing rules. SAP does not warrant the correctness and completeness of the example code. SAP shall not be liable for errors or damages caused by the use of example code unless damages have been caused by SAP's gross negligence or willful misconduct. Gender-Related Language We try not to use gender-specific word forms and formulations. As appropriate for context and readability, SAP may use masculine word forms to refer to all genders. Important Disclaimers and Legal Information P U BL IC 19

20 SAP SE or an SAP affiliate company. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP SE or an SAP affiliate company. The information contained herein may be changed without prior notice. Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors. National product specifications may vary. These materials are provided by SAP SE or an SAP affiliate company for informational purposes only, without representation or warranty of any kind, and SAP or its affiliated companies shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP or SAP affiliate company products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty. SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE (or an SAP affiliate company) in Germany and other countries. All other product and service names mentioned are the trademarks of their respective companies. Please see for additional trademark information and notices. THE BEST RUN