{section}
{column}

h1. Introduction

Petals ESB can be deployed into the cloud. By this way, to optimize hardware resource consumption:
* Petals ESB containers are instantiated on-demand,
* Service providers are instantiated and placed on the right Petals ESB container according to the system load.

In a user point of view, the Petals Virtual Container (PVC) will be the service infrastructure running all service consumers and service providers. The PVC is composed of:
* nodes of the Petals Registry Overlay, that are automatically instantiated according to the system load of the Petals Registry nodes and Petals ESB containers,
* Petals ESB containers that are automatically instantiated according to the system load of containers.

The user will deploy its regular Petals artifacts (shared library, components, SA or deployable SU) into the PVC. Service providers will be placed on the right container, and all dependencies (shared library, components) will be automatically deployed on this container.

{column}
{column:width=35%}
{panel:title=Table of contents}{toc:outline=true}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list|showAnonymous=true|showCount=true|showLastTime=true}{panel}
{column}
{section}

h1. Preparing the environment

Deployment of a PVC is assumed by [Roboconf|http://roboconf.net]. Make sure you have an operational Roboconf installation.

Before to install anything, you must define your software components to Roboconf:
* the software components of your applications used as service providers exposed into the PVC,
* the software components of the PVC, ie: mainly service units,
* the software components of your applications consuming service providers available into the PVC.

{gliffy:name=PVC_Overview|align=center|version=3|size=M}

Using several Roboconf applications is very interesting to keep the agility introduced by the usage of services deployed on the PVC part. In this way:
* the governance of applications is made easier because no synchronization is required between applications,
* an applicative resource can be re-deployed, only its dependencies are informed of configuration changes to take into account.

In a Roboconf point of view, each software component set is a Roboconf application that must be defined. See the Roboconf application to known how to define your Roboconf applications.
A Roboconf application template is provided to easily define your PVC. With this template, you have mainly to define the service units that must be deployed into the PVC.

{info}The new component *Petals Cockpit*, a web application in progress, will be able to generate your Roboconf application for the PVC part, and interact with the Roboconf engine. And so, it will be easier to instantiate PVCs.{info}

h1. Installing the PVC

Once all your Roboconf applications are ready, you can deploy them using the Roboconf Administration Console.

h1. Writing the Roboconf application for your PVC instance

{note}Waiting the release of Petals Cockpit, we must write our instance of PVC as a Roboconf application.{note}

To explain how to write a such application, we will use the following example:
* The process "Vacation" is deployed as service unit of the SE Activiti running into our PVC. This process provides a business process to manage vacation request.
* The process interacts with an external resources to archives the vacation requests and to log task status. The external resources is accessed through several web-services
* A portal is proposed to users to create and validate vacation requests.

So, we have 3 Roboconf applications:
* the Roboconf application for the portal,
* the PVC,
* and a Roboconf application archiving vacation requests and task status.

{info}Source code associated to this sample is available here: [https://github.com/petalslink/petals-virtual-container].{info}
{info}Docker is used as IaaS in this sample.{info}
{note}Extracts of source code given below are for comprehension. It's not the right source code. To get it, see the Git repository of the sample.{note}

h2. The Roboconf template "PVC"

h3. Overview

A Roboconf template is available as base to define a PVC. It defined several Roboconf components to instantiated in your PVC project:
* the bootstrap Petals Registry node. To be able to add another node to the Petals Registry Overlay it is required to one node of the Petals Registry. The master Petals Registry node is this node through which we can add another Petals Registry node,
* the standard Petals Registry node,
* the bootstrap Petals ESB container. It's a Petals ESB container used to dynamically add others Petals ESB containers. Such a container depends on the Petals Registry nodes (bootstrap and standard).
* the standard Petals ESB container. Such a container depends on the Petals Registry nodes (bootstrap and standard),
* abstract shared library. A shared library is a child of a Petals ESB container (standard or bootstrap),
* abstract binding component. A binding component is a child of a Petals ESB container (standard or bootstrap), and can depend on a shared library,
* abstract service engine. A service engine is a child of a Petals ESB container (standard or bootstrap), and can depend on a shared library,
* abstract service unit. A service unit is a child of a binding component or a service engine.

A plugin *Petals* for Roboconf has been developped to provide Roboconf installer for Petals ESB artifacts: shared library, binding component, service engine or service unit. Service assembly is not supported with Roboconf the service units of a SA can be children of different components that is not authorized by Roboconf: a child can have only one parent. That's why service units are declared directly as children of components.

{gliffy:name=PVCModel|size=M|version=11}

h3. Creating an empty PVC

{gliffy:name=PVC|size=M|version=2}

To create an empty PVC, just instantiate the following Roboconf components provided with the Petals Roboconf template:
* {{PetalsRegistry-VM}},
* {{PetalsRegistryBootstrap}},
* {{PetalsRegistry}},
* {{PetalsContainer-VM}},
* {{PetalsContainerBootstrap}},
* {{PetalsContainer}}.

Instance names of {{PetalsRegistryBootstrap}} and {{PetalsRegistry}} are used as Petals Registry member identifiers like the instance names of {{PetalsContainerBootstrap}} and {{PetalsContainer}} for the Petals container identifiers.

{section}
{column}
{gliffy:name=EmptyPVCModel|size=L|version=4}
{column}
{column}
{code}
##########################
# Registry part
##########################
instance of PetalsRegistry-VM {
name: registry-bootstrap-vm;

instance of PetalsRegistryBootstrap {
name: registry-bootstrap-node;
}
}

instance of PetalsRegistry-VM {
name: registry-vm-1;

instance of PetalsRegistry {
name: registry-node;
}
}

##########################
# Container part
##########################
instance of PetalsContainer-VM {
name: container-bootstrap-vm;

instance of PetalsContainerBootstrap {
name: container-bootstrap-node;

domainName: roboconf-demo;
subdomainName: roboconf-demo-1;
}
}

instance of PetalsContainer-VM {
name: container-vm-1;

instance of PetalsContainer {
name: container-node;
}
}
{code}
{column}
{section}

h3. Adding Petals artifacts to an empty PVC

The Petals artifacts that can be added to an empty PVC are: shared library, binding component, service engine and service unit.

h4. Adding a shared library

{section}
{column}
{gliffy:name=SharedLibraryModel|size=L|version=2}
{column}
{column}
{code}
PetalsSLPostgreSQL {
extends: PetalsSL;
}
{code}
{column}
{section}
{section}
{column}
{gliffy:name=SharedLibraryInstantiation|size=L|version=3}
{column}
{column}
{code}
instance of PetalsContainer-VM {
...
instance of PetalsContainer {
...
instance of PetalsSLPostgreSQL {
name: petals-sl-postgresql-9.4-1201-jdbc4;
}
}
}
{code}
{column}
{section}

h4. Adding a component (BC or SE)

In the Roboconf graph, just define the Roboconf component associated to your Petals component and extending the right Roboconf component {{PetalsBC or PetalsSE}} provided by the Roboconf template for Petals. It is needed to be able to define the configuration parameters of the Petals component, and potentially to define its dependencies with other resources or applications managed by Roboconf. Commonly, a binding component providing services will have a dependency to another Robocong application (for example, a BC SOAP can be linked to an external web application providing web-services), and a service engine can require a software resource for its own usage (for example, the SE Activiti requires a database).

In the Roboconf instances, just add a new instance of the new Roboconf component as a child of your instances {{PetalsContainer}} and {{PetalsContainerBootstrap}}. The Roboconf instance name is used as the JBI identifier of the Petals component, and *must match* the one defined into the JBI archive.
Each configuration parameters of your component (as CDK configuration parameters or dedicated configuration parameters) can be set or overriden at the instance level. Just declare them as instance properties. You can add the placeholders '{{container-name}}' and '{{component-name}}' in value of your configuration parameters.

h5. Adding a binding component use only as service consumer

{section}
{column}
{gliffy:name=ConsumerBCModel|size=L|version=2}
{column}
{column}
{code}
PetalsBCSoap {
extends: PetalsBC;
exports: httpPort = 8084;
}
{code}
{column}
{section}
{section}
{column}
{gliffy:name=ConsumerBCInstantiation|size=L|version=2}
{column}
{column}
{code}
instance of PetalsContainer-VM {
...
instance of PetalsContainer {
...
instance of PetalsBCSoap {
name: petals-bc-soap;

PetalsJBIComponent.propertiesFile: /etc/petals-esb/container-available/${container-name}/${component-name}.properties;
}
}
}
{code}
{column}
{section}

h5. Adding a binding component used as service provider

{warning}Must be updated with the Roboconf application dependency when it will be supported by Roboconf.{warning}

{section}
{column}
{gliffy:name=ProviderBCModel|size=L|version=2}
{column}
{column}
{code}
PetalsBCSoap {
extends: PetalsBC;
exports: httpPort = 8084;
}
{code}
{column}
{section}
{section}
{column}
{gliffy:name=ProviderBCInstantiation|size=L|version=2}
{column}
{column}
{code}
instance of PetalsContainer-VM {
...
instance of PetalsContainer {
...
instance of PetalsBCSoap {
name: petals-bc-soap;

PetalsJBIComponent.propertiesFile: /etc/petals-esb/container-available/${container-name}/${component-name}.properties;
}
}
}
{code}
{column}
{section}

h5. Adding a service engine requiring a shared libray and an Roboconf resource

Such a component require another Roboconf component as resource for its internal usage.
In the Roboconf graph, just define the Roboconf component extending the Roboconf component {{PetalsSE}} to:
* add the configuration parameters and,
* add the dependency to the Roboconf component that, obviously, must be defined,
* add the dependency to the shared library.

In the Roboconf instances, just add a new instance of the new Roboconf component as a child of your instances {{PetalsContainer}} and {{PetalsContainerBootstrap}}.

Caution, the JBI identifier of the shared library defined into the JBI component descriptor *must match* the shared library instance name.

{section}
{column}
{gliffy:name=SEWithSLModel|size=L|version=3}
{column}
{column}
{code}
PostgreSQL-VM {
installer: target;
children: PostgreSQLServer;
}

PostgreSQLServer {
installer: script;
children: ActivitiPgSQLDatabase;
}

ActivitiPgSQLDatabase {
installer: script;
exports: ip, databaseName = database-name, databaseUser = database-user, databasePwd = database-pwd;
}

PetalsSEActiviti {
extends: PetalsSE;
imports: PetalsSLPostgreSQL.present, ActivitiPgSQLDatabase.*;
}
{code}
{column}
{section}
{section}
{column}
{gliffy:name=SEWithSLInstantiation|size=L|version=2}
{column}
{column}
{code}
instance of PostgreSQL-VM {
name: postgresql-vm;

instance of PostgreSQLServer {
name: postgresql-server;

instance of ActivitiPgSQLDatabase {
name: activiti-database;

databaseName: activiti;
databaseUser: petalsseactiviti;
databasePwd: PetalsSeActiviti;
}
}
}

instance of PetalsContainer-VM {
...
instance of PetalsContainer {
...
instance of PetalsSLPostgreSQL {
name: petals-sl-postgresql-9.4-1201-jdbc4;
}

instance of PetalsSEActiviti {
name: petals-se-activiti;

PetalsJBIComponent.propertiesFile: /etc/petals-esb/container-available/${container-name}/${component-name}.properties;
}
}
}
{code}
{column}
{section}

h4. Adding a service unit

In the Roboconf graph, just define the Roboconf component associated to your service unit and extending the component {{PetalsSU}}.
In the Roboconf instances, just add a new instance of the new Roboconf component as a child of your instances inherited from {{PetalsBC}} and {{PetalsSE}}. The Roboconf instance name is used as the JBI identifier of the service unit.

{section}
{column}
{gliffy:name=ServiceUnitModel|size=L|version=2}
{column}
{column}
{code}
SU-SOAP-VacationServiceConsumer {
extends: PetalsSU;
}
{code}
{column}
{section}
{section}
{column}
{gliffy:name=ServiceUnitInstantiation|size=L|version=2}
{column}
{column}
{code}
instance of PetalsContainer-VM {
...
instance of PetalsContainer {
...
instance of PetalsBCSoap {
...
instance of SU-SOAP-VacationServiceConsumer {
name: su-SOAP-vacationService-consume;
}
}
}
}
{code}
{column}
{section}

h2. The Roboconf application "External resource"

This applicative resource is a web application running on Tomcat8 cluster, composed of:
* a load balancer redirecting incoming HTTP SOAP request on an available Tomcat8 server where the web application is deployed,
* several servers running Tomcat.

{gliffy:name=TomcatCluster|size=M|version=2}

So the model of this Roboconf application is:
{section}
{column}
*Component definitions*
{code}
Tomcat8_VM {
installer: target;
children: Tomcat8;
}

Tomcat8 {
installer: script;
exports: ip, port = 8080;
children: Tomcat8_Application_WAR;
}

Tomcat8_Application_WAR {
installer: script;
exports: applicationFile = my-tomcat8-app-file.war;
}

HAProxy_VM {
installer: target;
children: HAProxy;
}

HAProxy {
installer: script;
imports: Tomcat8.port (optional), Tomcat8.ip (optional);
exports: ip, httpPort = 80, statsPort = 8080;
}
{code}

{column}
{column}
*Default instantiation*
{code}
# A VM with HAProxy_VM load balancer
instance of HAProxy_VM {
name: HAProxy VM;

instance of HAProxy {
name: Haproxy;

httpPort: 80;
statsPort: 8080;
}
}

# A VM with Tomcat
instance of Tomcat8_VM {
name: Tomcat VM1;

instance of Tomcat8 {
name: Tomcat;

instance of Tomcat8_Application_WAR {
name: samplesActivitiSOAPservices;

applicationFile: samples-SOAP-services.war;
}
}
}

# Another VM with Tomcat
instance of Tomcat8_VM {
name: Tomcat VM2;

instance of Tomcat8 {
name: Tomcat;

instance of Tomcat8_Application_WAR {
name: samplesActivitiSOAPservices;

applicationFile: samples-SOAP-services.war;
}
}
}
{code}
{column}
{section}
h2. The Roboconf application "Portal"

The portal is a web application running on a simple instance of Tomcat8, providing the forms required by the process "Vacation".

{gliffy:name=Portal|size=M|version=2}

So the model of this Roboconf application is:
{section}
{column}
*Component definitions*
{code}
Tomcat8_VM {
installer: target;
children: Tomcat8;
}

Tomcat8 {
installer: script;
exports: ip, port = 8080;
children: Tomcat8_Application_Uncompress;
}

Tomcat8_Application_Uncompress {
installer: script;
exports: applicationDir = my-tomcat8-app-file, applicationFile = my-tomcat8-app-file.zip;
}

Portal_Application {
extends: Tomcat8_Application_Uncompress;

# Add imports link to the Petals BC SOAP used as entry point into the PVC part
}
{code}

{column}
{column}
*Default instantiation*
{code}
# A VM with Tomcat
instance of Tomcat8_VM {
name: Tomcat8 VM for Portal;

instance of Tomcat8 {
name: Tomcat8 for Portal;

instance of Portal_Application {
name: portal;

applicationFile: sample-vacation-webapp.war;
applicationDir: sample-vacation-webapp;
}
}
}
{code}
{column}
{section}

h2. The Roboconf application "Sample PVC"

Our PVC will:
* run our process "Vacation",
* expose service providers to the portal to interact with the process:
** create a new process instance (ie: create a new vacation request),
** validate or reject a vacation request,
** update a vacation request.
* expose external service providers used for archiving and used by the process.

So the following Petals artifacts will be deployed into the PVC:
* the SE Activity,
* as the SE Activity requires a database, we will deploy a PosgreSQL database,
* to connect to the database, the SE Activity requires a JDBC driver provided as a shared library,
* the service unit providing the process "Vacation",
* the BC SOAP that is needed to:
** run the service units required to interact with the external archiving web-services
** expose service providers associated to the process "Vacation"

To be highly available, all Petals components are duplicated at least twice. The PostgreSQL database should be also highly available, but to simplify the comprehension we will use only one instance of the database.

So at the definition of an empty PVC, we add the following Roboconf models:
{section}
{column}
*Component definitions*
{code}
import petals-pvc/main.graph;

PostgreSQL-VM {
installer: target;
children: PostgreSQLServer;
}

PostgreSQLServer {
installer: script;
children: ActivitiPgSQLDatabase;
}

ActivitiPgSQLDatabase {
installer: script;
exports: ip, databaseName = database-name, databaseUser = database-user, databasePwd = database-pwd;
}

PetalsSLPostgreSQL {
extends: PetalsSL;
# As SL are not supported by Roboconf because:
# - a SL export no configuration parameter
# - Roboconf is not able to manage local dependency
# We create a dummy exported variable and work with only one instance of Petals SE Activiti over all Petals containers
exports: present = true;
}

PetalsBCSoap {
extends: PetalsBC;
exports: httpPort = 8084;
}

PetalsSEActiviti {
extends: PetalsSE;
# See comment on PetalsSLPostgreSQL
imports: PetalsSLPostgreSQL.present, ActivitiPgSQLDatabase.*;
}

SU-Activiti-VacationRequest {
extends: PetalsSU;
}

SU-SOAP-VacationServiceConsumer {
extends: PetalsSU;
}

SU-SOAP-NotificationServiceProvider {
extends: PetalsSU;
}

SU-SOAP-ArchivingServiceProvider {
extends: PetalsSU;
}

SU-SOAP-ActivitiIntegrationConsumer {
extends: PetalsSU;
}
{code}

{column}
{column}
*Default instantiation*
{code}

##########################
# Registry part
##########################
instance of PetalsRegistry-VM {
name: registry-bootstrap-vm;

instance of PetalsRegistryBootstrap {
name: registry-bootstrap-node;
}
}

instance of PetalsRegistry-VM {
name: registry-vm-1;

instance of PetalsRegistry {
name: registry-node-1;
}
}

##########################
# Container part
##########################
instance of PetalsContainer-VM {
name: container-bootstrap-vm;

instance of PetalsContainerBootstrap {
name: container-bootstrap-node;

domainName: roboconf-demo;
subdomainName: roboconf-demo-1;

instance of PetalsSLPostgreSQL {
name: petals-sl-postgresql-9.4-1201-jdbc4;
}

instance of PetalsBCSoap {
name: petals-bc-soap;

instance of SU-SOAP-VacationServiceConsumer {
name: su-SOAP-vacationService-consume;
}

instance of SU-SOAP-NotificationServiceProvider {
name: su-SOAP-notifyVacationService-provide;
}

instance of SU-SOAP-ArchivingServiceProvider {
name: su-SOAP-archiveService-provide;
}

instance of SU-SOAP-ActivitiIntegrationConsumer {
name: su-SOAP-activitiIntegrationService-consume;
}
}

instance of PetalsSEActiviti {
name: petals-se-activiti;

instance of SU-Activiti-VacationRequest {
name: su-activiti-vacationService-provide;
}
}
}
}

instance of PetalsContainer-VM {
name: container-vm-1;

instance of PetalsContainer {
name: container-node-1;

instance of PetalsSLPostgreSQL {
name: petals-sl-postgresql-9.4-1201-jdbc4;
}

instance of PetalsBCSoap {
name: petals-bc-soap;

instance of SU-SOAP-VacationServiceConsumer {
name: su-SOAP-vacationService-consume;
}

instance of SU-SOAP-NotificationServiceProvider {
name: su-SOAP-notifyVacationService-provide;
}

instance of SU-SOAP-ArchivingServiceProvider {
name: su-SOAP-archiveService-provide;
}

instance of SU-SOAP-ActivitiIntegrationConsumer {
name: su-SOAP-activitiIntegrationService-consume;
}
}

instance of PetalsSEActiviti {
name: petals-se-activiti;

instance of SU-Activiti-VacationRequest {
name: su-activiti-vacationService-provide;
}
}
}
}

##########################
# Other resources
##########################
instance of PostgreSQL-VM {
name: postgresql-vm;

instance of PostgreSQLServer {
name: postgresql-server;

instance of ActivitiPgSQLDatabase {
name: activiti-database;

databaseName: activiti;
# The database user name must be defined in lower case and '-' is forbidden
databaseUser: petalsseactiviti;
databasePwd: PetalsSeActiviti;
}
}
}
{code}
{column}
{section}

h1. Deploying your PVC instance

Once your Roboconf PVC application is ready, it is deployed as any Roboconf application through the Roboconf administration console:
# Create a *New Application Template*
!new-app-template.png|thumbnail!
# *Select* your Roboconf PVC application archive and *upload* it
!upload-template.png|thumbnail!
# Next, *create a new application*
!new-app.png|thumbnail!
# The application is created
!app.png|thumbnail!
# Go to the instance management page
!instance-management.png|thumbnail!
# And *deploy and start all*
!all-is-started.png|thumbnail!