Apache Stratos (incubating) 4.0.0-M5 Installation Guide 1. Prerequisites 2. Product Configuration 2.1 Message Broker Configuration 2.2 Load Balancer Configuration 2.3 Cloud Controller Configuration 2.4 Stratos Controller Configuration 2.5 AutoScaler Configuration 2.6 Complex Event Processor (CEP) Configuration 3. Cartridge Creation 3.1 Prepare an Instance of an IaaS Image 3.2 Install Cartridge Agent Scripts, Event Publisher, Event Subscriber and Health Publisher 3.3 Create Cartridge Image 3.4 Sample Cartridge Images 4. Configuring HAProxy Load Balancer 5. Starting Apache Stratos
1. Prerequisites Apache Stratos Products Required: apache stratos autoscaler 4.0.0 SNAPSHOT (AutoScaler) apache stratos sc 4.0.0 SNAPSHOT (Stratos Controller) apache stratos cc 4.0.0 SNAPSHOT (Cloud Controller) apache stratos load balancer 4.0.0 SNAPSHOT (Load Balancer) apache stratos cartridge agent 4.0.0 SNAPSHOT (Cartridge Agent) Optional Apache Stratos Extensions: apache stratos haproxy extension 4.0.0 SNAPSHOT (HAProxy Extension) Download above Apache Stratos 4.0.0 M5 binary packages from the following location: https://dist.apache.org/repos/dist/dev/incubator/stratos/milestones/4.0.0 incubating m5/ Dependent Products Required: wso2cep 3.0.0 (Complex Event Processor) wso2mb 2.1.0 (Message Broker) Download above WSO2 products from the following location: http://wso2.com/products/complex event processor/ http://wso2.com/products/message broker/ Dependent Software Required: Java Runtime 1.6 MySQL Server 5.5 MySQL Connector for Java 2. Product Configuration 2.1 Message Broker Configuration The <mb home>/repository/conf/carbon.xml file needs to be updated in Message Broker (MB): <offset>5</offset> <! Port Offset > Update message broker port offset, default value would be 5. The resulting message broker port would be 5677. 2.2 Load Balancer Configuration
Load balancer is defined as a service from this milestone onwards. Therefore a load balancer cartridge needs to be created with the following configuration. Configuration parameters MB IP, MB PORT, CEP IP, CEP PORT and LB CLUSTER ID will be sent in the instance payload. 1. <lb home>/repository/conf/loadbalancer.conf loadbalancer # Default load balancing algorithm # Refer algorithm name from algorithms section. algorithm: round robin; # Enable/disable failover handling # If failover handling is enabled load balancer will retry requests on all members in a # given cluster if the selected member fails to respond. failover: true; # Enable/disable session affinity # If session affinity is enabled load balancer will track all outgoing sessions and delegate # incoming requests to members with same sessions. session affinity: true; # Session timeout in milli seconds session timeout: 90000; # Enable/disable topology event listener # If this property is set to true, load balancer will listen to topology events and build # the topology configuration accordingly. If not static configuration given in the services # section will be used. topology event listener enabled: true; # Message broker endpoint # Provide message broker ip address and port if topology_event_listener_enabled is set to true. mb ip: <message broker ip>; mb port: <message broker port>; # Topology service filter # Provide service names in a comma separated list to filter
incoming topology events if # topology_event_listener_enabled is set to true. This functionality could be used for hosting # dedicated load balancers for services. # topology service filter: service name1, service name2; # Topology cluster filter # Provide cluster ids in a comma separated list to filter incoming topology events if # topology_event_listener_enabled is set to true. This functionality could be used for hosting # dedicated load balancers for subscriptions. # topology cluster filter: cluster id1, cluster id2; # Topology member filter # Provide load balancer cluster ids in a comma separated list to filter incoming topology events if # topology_event_listener_enabled is set to true. This functionality could be used for allowing members # to join a given load balancer cluster. # topology member filter: lb cluster id=lb cluster id1; # Enable/disable cep statistics publisher cep stats publisher enabled: true; # Complex event processor endpoint # Provide CEP ip address and port if stats_publisher_enabled is set to true. cep ip: <cep ip>; cep port: <cep port>; # Load balancing algorithm class names. algorithms round robin # algorithm name class name: org.apache.stratos.load.balancer.algorithm.roundrobin; Update message broker ip and message broker port, cep ip, cep port and lb cluster id values from the payload parameters.
2. <lb home>/repository/conf/axis2/axis2.xml <transportreceiver name="http" class="class name"> <parameter name="port" locked="false">8280</parameter> </transportreceiver> <transportreceiver name="https" class="class name"> <parameter name="port" locked="false">8243</parameter> </transportreceiver> Update http and https ports if required. Default values would be http=8280, https=8243. Dedicated Load Balancing for Services Load balancer could be configured to manage a given set of services. This functionality could be used for hosting dedicated load balancers for separate services. Sample Scenario: Configure two load balancers to manage two different sets of services: Load Balancer L1: Services Managed: AppServer, ESB Update below property in <lb home>/repository/conf/loadbalancer.conf with the service names: AppServer, ESB: topology service filter: AppServer,ESB; Load Balancer L2: Services Managed: PHP Update below property in <lb home>/repository/conf/loadbalancer.conf with the service names: PHP: topology cluster filter: PHP; 2.3 Cloud Controller Configuration Following configuration files need to be updated in Cloud Controller (CC): 1. <cc home>/repository/conf/carbon.xml <offset>1</offset> <! Port Offset > Update cloud controller port offset, default value would be 1. The resulting cloud controller https port would be 9444. 2. <cc home>/repository/conf/cloud controller.xml
Define one of the below IaaS providers in cloud controller.xml file: <cloudcontroller>... <iaasprovider type="ec2" name="amazon EC2"> <classname>org.apache.stratos.cloud.controller.iaases.awsec2iaas</cla ssname> <provider>aws ec2</provider> <identity svns:secretalias="cloud.controller.ec2.identity">xxx</identity> <credential svns:secretalias="cloud.controller.ec2.credential">xxx</credential> <property name="jclouds.ec2.ami query" value="owner id=xxx;state=available;image type=machine"/> <property name="availabilityzone" value="xxx"/> <property name="securitygroups" value="xxx"/> <property name="keypair" value="xxx"/> <property name="autoassignip" value="true" /> <imageid>xxx</imageid> <! [optional] default cartridge id > </iaasprovider>... </cloudcontroller> Update identity, credential, owner id, availability zone, security groups, key pair name for the Amazon EC2 IaaS provider. <cloudcontroller>... <iaasprovider type="openstack" name="openstack"> <classname>org.apache.stratos.cloud.controller.iaases.openstackn ovaiaas</classname> <provider>openstack nova</provider> <identity svns:secretalias="cloud.controller.openstack.identity">xxx:xxx</ident ity> <credential svns:secretalias="cloud.controller.openstack.credential">xxx</credent ial> <property name="jclouds.endpoint" value="http://xxx:5000/" /> <property name="jclouds.openstack nova.auto create floating ips" value="false"/> <property name="jclouds.api version" value="2.0/" /> <property name="securitygroups" value="xxx"/>
<property name="keypair" value="xxx"/> <property name="autoassignip" value="true" /> <imageid>nova/xxx</imageid> <! [optional] default cartridge id > </iaasprovider>... </cloudcontroller> Update identity, credential, Openstack API URL (jclouds.endpoint), security groups and key pair name for the Openstack provider. 3. <cc home>/repository/conf/jndi.properties connectionfactoryname=topicconnectionfactory connectionfactory.topicconnectionfactory=amqp://admin:admin@carbon/ca rbon?brokerlist='tcp://<message broker ip>:<message broker port>' java.naming.factory.initial=org.wso2.andes.jndi.propertiesfileinitial ContextFactory Update message broker ip and message broker port values, default values would be message broker ip=localhost, message broker port=5677 2.4 Stratos Controller Configuration Following configuration files need to be updated in Stratos Controller (SC): 1. <sc home>/repository/conf/carbon.xml <offset>2</offset> <! Port Offset > Update stratos controller port offset, default value would be 2. The resulting https port would be 9445. 2. <sc home>/repository/conf/cartridge config.properties mb.ip=<message broker ip> mb.port=<message broker port> cep.ip=<cep ip> cep.port=<cep port> repository.info.epr = https://<stratos controller ip>:<stratos controller https port>/servi ces/repositoryinformationservice puppet.ip=<puppet master ip> sc.ip=<stratos controller ip> cloud.controller.service.url=https://<cloud controller ip>:<clou
d controller https port>/services/cloudcontrollerservice/ autoscaler.service.url=https://<autoscaler ip>:<autoscaler https port>/services/autoscalerservice/ adc.jdbc.url=jdbc:mysql:/localhost:3306/stratos_foundation adc.jdbc.username=root adc.jdbc.password=mysql adc.jdbc.driver=com.mysql.jdbc.driver Update message broker ip, message broker port, cep ip, cep port, stratos controller ip, puppet master ip, cloud controller ip, cloud controller https port, autoscaler ip, autoscaler https port and stratos controller https port. 3. <sc home>/repository/conf/jndi.properties connectionfactoryname=topicconnectionfactory connectionfactory.topicconnectionfactory=amqp://admin:admin@carbon/ca rbon?brokerlist='tcp://<message broker ip>:<message broker port>' java.naming.factory.initial=org.wso2.andes.jndi.propertiesfileinitial ContextFactory Update message broker ip and message broker port values, default values would be message broker ip=localhost, message broker port=5677 4. Create Databases: Create Userstore and Stratos Foundation databases in MySQL Database Server using userstore.sql and stratos_foundation.sql found at incubator stratos/tools/stratos installer/resources/ directory. 5. Update data source configurations: Update userstore data source in: <sc_home>/repository/conf/datasources/master datasources.xml <datasource> <name>wso2_carbon_db</name> <description>the datasource used for registry and user manager</description> <jndiconfig> <name>jdbc/wso2carbondb</name> </jndiconfig> <definition type="rdbms"> <configuration>
<url>jdbc:mysql://localhost:3306/userstore?autoreconnect=true</url> <username>root</username> <password>mysql</password> <driverclassname>com.mysql.jdbc.driver</driverclassname> <maxactive>50</maxactive> <maxwait>60000</maxwait> <testonborrow>true</testonborrow> <validationquery>select 1</validationQuery> <validationinterval>30000</validationinterval> </configuration> </definition> </datasource> 6. Copy the mysql connector jar to <sc_home>/repository/components/lib 2.5 AutoScaler Configuration Following configuration files need to be updated in AutoScaler: 1. <as home>/repository/conf/carbon.xml <offset>3</offset> <! Port Offset > Update autoscaler port offset, default value would be 3. The resulting https port would be 9446. 2. <as home>/repository/conf/jndi.properties connectionfactoryname=topicconnectionfactory connectionfactory.topicconnectionfactory=amqp://admin:admin@carbon/ca rbon?brokerlist='tcp://<message broker ip>:<message broker port>' java.naming.factory.initial=org.wso2.andes.jndi.propertiesfileinitial ContextFactory Update message broker ip and message broker port values, default values would be message broker ip=localhost, message broker port=5677 2.6 Complex Event Processor (CEP) Configuration Following configuration and artifact files needs to be updated in complex event processor: 1. <cep home>/repository/conf/carbon.xml
<offset>4</offset> <! Port Offset > Update CEP port offset, default value would be 4. The resulting thrift port would be 7615. 2. <cep home>/repository/conf Copy following file from incubator stratos/extensions/cep/artifacts/stream_definitions to <cep home>/repository/conf stream manager config.xml 3. <cep home>/repository/conf/jndi.properties # use the following property to configure the default connector connectionfactory.topicconnectionfactory = amqp://admin:admin@clientid/carbon?brokerlist='tcp://<message brokerip>:<message broker port>'&reconnect='true' # use the following property to specify the JNDI name of the connection factory connectionfactorynames = connectionfactory, topicconnectionfactory # register some topics in JNDI using the form # topic.[jndiname] = [physicalname] topic.lb stats = lb stats topic.instance stats = instance stats topic.summarized health stats = summarized health stats Update message broker ip and message broker port. 4. <cep home>/repository/conf/siddhi/siddhi.extension Add the following content to siddhi.extension org.apache.stratos.cep.extension.gradientfinderwindowprocessor org.apache.stratos.cep.extension.secondderivativefinderwindowprocesso r org.apache.stratos.cep.extension.faulthandlingwindowprocessor 5. <cep home>/repository/components/lib Build the project at <STRATOS_SOURCE_HOME>/extensions/cep/stratos cep extensions Copy org.apache.stratos.cep.extension 1.0.0 SNAPSHOT.jar to
<cep home>/repository/components/lib. 6. <cep home>/repository/deployment/server/eventbuilders Copy following files from incubator stratos/extensions/cep/artifacts/eventbuilders/ to <cep home>/repository/deployment/server/eventbuilders: HealthStatisticsEventBuilder.xml InstanceStatisticsEventBuilder.xml LoadBalancerStatisticsEventBuilder.xml 7. <cep home>/repository/deployment/server/inputeventadaptors Copy following files from incubator stratos/extensions/cep/artifacts/inputeventadaptors/ to <cep home>/repository/deployment/server/inputeventadaptors: DefaultWSO2EventInputAdaptor.xml 8. <cep home>/repository/deployment/server/outputeventadaptors Copy following files from incubator stratos/extensions/cep/artifacts/outputeventadaptors/ to <cep home>/repository/deployment/server/outputeventadaptors: DefaultWSO2EventOutputAdaptor.xml JMSOutputAdaptor.xml 9. <cep home>/repository/deployment/server/executionplans Copy following files from incubator stratos/extensions/cep/artifacts/executionplans/ to <cep home>/repository/deployment/server/executionplans: AverageHeathRequest.xml AverageInFlightRequestsFinder.xml GradientOfHealthRequest.xml GradientOfRequestsInFlightFinder.xml SecondDerivativeOfHealthRequest.xml SecondDerivativeOfRequestsInFlightFinder.xml 10. <cep home>/repository/deployment/server/eventformatters Copy following files from incubator stratos/extensions/cep/artifacts/eventformatters/ to <cep home>/repository/deployment/server/eventformatters: AverageInFlightRequestsEventFormatter.xml AverageLoadAverageEventFormatter.xml AverageMemoryConsumptionEventFormatter.xml FaultMessageEventFormatter.xml
GradientInFlightRequestsEventFormatter.xml GradientLoadAverageEventFormatter.xml GradientMemoryConsumptionEventFormatter.xml MemberAverageLoadAverageEventFormatter.xml MemberAverageMemoryConsumptionEventFormatter.xml MemberGradientLoadAverageEventFormatter.xml MemberGradientMemoryConsumptionEventFormatter.xml MemberSecondDerivativeLoadAverageEventFormatter.xml MemberSecondDerivativeMemoryConsumptionEventFormatter.xml SecondDerivativeInFlightRequestsEventFormatter.xml SecondDerivativeLoadAverageEventFormatter.xml SecondDerivativeMemoryConsumptionEventFormatter.xml 3. Cartridge Creation In Apache Stratos 4.0.0 M5 milestone there are two types of cartridge images: 1. Standard Cartridge Images 2. Puppet based Cartridge Images In this section you will find information on creating standard cartridge images. Please refer Apache Statos 4.0.0 M5 Puppet Guide document on information on creating Puppet based cartridge images. 3.1 Prepare a VM Instance Start a VM instance in an IaaS and install all required software. For an example to create an Apache Tomcat cartridge, Java Runtime and Apache Tomcat Server could be installed on an Ubuntu VM instance. 3.2 Install Cartridge Agent Upload Cartridge Agent binary package and Cartridge Agent scripts found at incubator stratos/products/cartridge agent/modules/scripts/ folder to the above virtual machine instance. Then extract the Cartridge Agent binary package to /opt/apache stratos cartridge agent/cartridge agent/ and copy the cartridge agent script files to /opt/apache stratos cartridge agent/ folder. Afterwards update /etc/rc.local file to trigger the cartridge agent.sh file at the virtual machine boot time. 3.3 Create Cartridge Image
Once the required software and configuration files are in place create an IaaS image from the above virtual machine instance and update the cartridge definition JSON file. 3.4 Sample Cartridge Images There are two sample cartridge images created in Amazon EC2, Asia Pacific (Singapore) region. Details are as follows: Puppet Base Image AMI ID: ap southeast 1/ami 2e0d5a7c AMI Name: apache stratos M5 base cartridge v2 Load Balancer Cartridge Image AMI ID: ap southeast 1/ami da297e88 AMI Name: apache stratos 4.0.0 m5 lb cartridge r25 debug 4. Configuring HAProxy Load Balancer Apache Stratos HAProxy Extension could be used for integrating HAProxy load balancer with Apache Stratos. Please follow below steps to proceed with the installation: 1. Download and extract HAProxy binary distribution to a desired location: <haproxy home>. 2. Extract apache stratos haproxy extension 4.0.0 SNAPSHOT bin.zip to a desired location: <haproxy extension home>. 3. Open <haproxy extension home>/bin/haproxy extension.sh file in a text editor and update following system properties: Dexecutable.file.path=<haproxy home>/haproxy # HAProxy executable file path Dthrift.receiver.ip=localhost # CEP IP Address Dthrift.receiver.port=7615 # CEP Port 4. Open <haproxy extension home>/conf/jndi.properties file in a text editor and update message broker information: connectionfactory.topicconnectionfactory=amqp://admin:admin@carbon/carbon?brokerlist='tcp: //<message broker ip>:<message broker port>' 5. If required default load balancer configuration could be updated in below template file: <haproxy extension home>/templates/haproxy.cfg.template 6. Run <haproxy extension home>/bin/haproxy extension.sh
5. Starting Apache Stratos Start products in the following order: 1. Message Broker 2. Cloud Controller 3. Complex Event Processor 4. Auto Scaler 5. Stratos Controller 6. Deploying Artifacts & Subscribing to Services File system based deployment methods for partitions, autoscaling policies, deployment policies and cartridge definitions are no longer supported in Apache Stratos 4.0.0 M5 milestone. These artifacts are now defined in json format and deployed through the Rest API. The order of artifact deployment is as follows: 1. Deploy Partitions Execute the following command in Stratos CLI to deploy a partition: stratos> deploy partition p /path/to/json/partition.json 2. Deploy Deployment Policies Execute the following command in Stratos CLI to deploy a deployment policy: stratos> deploy deployment policy p /path/to/json/deployment policy.json 3. Deploy Autoscale Policies Execute the following command in Stratos CLI to deploy a autoscale policy: stratos> deploy autoscaling policy p /path/to/json/autoscale policy.json 4. Deploy Load Balancer Cartridges Execute the following command in Stratos CLI to deploy a load balancer cartridge: stratos> deploy cartridge p /path/to/json/load balancer cartridge.json
5. Deploy Service Cartridges Execute the following command in Stratos CLI to deploy a service cartridge: stratos> deploy cartridge p /path/to/json/service cartridge.json Once above artifacts are successfully deployed, users could subscribe to services. Execute the below command in Stratos CLI to subscribe to a service: stratos> subscribe cartridge <service name> <subscription alias> ap autoscale policy id dp deployment policy id u <username> p <password> r <git repo url> Please find sample JSON files below: Partition Definition "partition": "id": "P1", "provider": "ec2", "property": [ "name": "region", "value": "ap southeast 1" ] Autoscale Policy Definition "autoscalepolicy": "id": "economypolicy", "loadthresholds": "requestsinflight": "average": "6000", "gradient": "0", "secondderivative": "0", "scaledownmarginofgradient": "1.0", "scaledownmarginofsecondderivative": "0.2"
, "memoryconsumption": "average": "6000", "gradient": "0", "secondderivative": "0", "scaledownmarginofgradient": "1.0", "scaledownmarginofsecondderivative": "0.2", "loadaverage": "average": "6000", "gradient": "0", "secondderivative": "0", "scaledownmarginofgradient": "1.0", "scaledownmarginofsecondderivative": "0.2" Deployment Policy Definition "deploymentpolicy": "id": "isuruh ec2", "partitiongroup": "id": "ec2", "partitionalgo": "one after another", "partition": [ "id": "P1", "partitionmax": "3", "partitionmin": "1" ] Loadbalancer Cartridge "cartridgedefinitionbean": "type": "lb", "provider": "apache",
"host": "stratos.org", "displayname": "load balancer", "description": "LB Cartridge", "version": "4", "defaultautoscalingpolicy": "economypolicy", "multitenant": "false", "portmapping": [ "protocol": "http", "port": "8280", "proxyport": "8280", "protocol": "https", "port": "8243", "proxyport": "8243" ], "deployment":, "iaasprovider": [ "type": "ec2", "imageid": "ap southeast 1/ami 70326522", "maxinstancelimit": "5", "property": [ "name": "instancetype", "value": "m1.medium", "name": "keypair", "value": "xxxxxx" ] ], "loadbalancer":, "property": [ "name": "load.balancer", "value": "true"
, "name": "payload_parameter.mb_ip", "value": "xx.xx.xx.xx", "name": "payload_parameter.mb_port", "value": "xxxx", "name": "payload_parameter.cep_ip", "value": "xx.xx.xx.xx", "name": "payload_parameter.cep_port", "value": "xxxx" ] PHP Cartridge Definition "cartridgedefinitionbean": "type": "php", "provider": "apache", "host": "stratos.org", "displayname": "PHP", "description": "PHP Cartridge", "version": "7", "multitenant": "false", "portmapping": [ "protocol": "http", "port": "80", "proxyport": "8280", "protocol": "https", "port": "443", "proxyport": "8243"
], "deployment":, "iaasprovider": [ "type": "ec2", "imageid": "ap southeast 1/ami 2e0d5a7c", "maxinstancelimit": "4", "property": [ "name": "instancetype", "value": "m1.medium", "name": "keypair", "value": "xxxxxxxx" ] ], "loadbalancer": "type": "lb", "property": "name": "default.load.balancer", "value": "true", Please update parameter values in each JSON file according to your configuration settings. Please refer Apache Stratos 4.0.0 M5 REST API Guide document for instructions on directly invoking the REST API via curl without using the Stratos CLI. It contains sample curl commands that could be used for deploying partitions, policies, cartridges and other operations such as subscribing, etc.