Apache Stratos (incubating) M5 Installation Guide

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.

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

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.

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>

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­broker­ ip>:<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.

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

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

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",

},

"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",

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