{section}
{column}

{note}This is the documentation section for the *development version* of Petals ESB Deployer.
Please, note that such a documentation and product may be incomplete and/or unstable. For production environment, please use the latest public release of product and documentation.
{note}

h1. Introduction

Petals ESB Deployer is a tool to manage the deployment of a whole Petals ESB bus.

Deploying a whole Petals ESB bus includes to deploy Petals ESB containers, Petals ESB Hazelcast Registry, and service consumers or providers running on their binding components or service-engines correctly configured. The architecture of the Petals ESB bus and service providers/consumers to deploy are defined into a model.

Petals ESB Deployer is embedded into Petals ESB CLI through different commands:
* the command {{deploy}} is extended to deploy a whole Petals ESB bus, and to migrate an existing deployment to a new version,
* the command {{undeploy}} is extended to undeploy a whole Petals ESB bus,
* the dedicated command {{check-deployment}} will check an existing Petals ESB bus against a given model describing the expected Petals ESB bus.

{warning}
Petals ESB Deployer *1.0.0* is provided with [Petals ESB CLI *3.2.0*|petalsclisnapshot:Petals ESB CLI 3.2.0-SNAPSHOT].
{warning}
{column}
{column:width=40%}
{panel:title=Table of contents}{toc}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list}{panel}
{column}
{section}

h1. Use cases

The goal of Petals ESB Deployer is to resolve several deployment problematics:
* how to simplify the deployment of a Petals ESB bus avoiding to use scripts for automating deployment ?
* how to upgrade an existing deployment of a Petals ESB bus to a new version of this Petals ESB bus,
* how to deploy a set of service providers and consumers on different environments, for example DEV, TEST or PROD where the Petals ESB bus topology and external resources are different ?
* how to deploy a Petals ESB bus on different environments, for example STAGING, PRE-PROD, PROD where the Petals ESB bus topology is the same but where machines running Petals ESB bus and external resources are differents ?

h2. Deployment samples

h3. Classic: Different topologies following project progress

In this use case sample, service providers/consumers are deployed on a topology that is different according to the project step: DEV, TEST, PRE-PROD and PROD. Service providers/consumers are the same on each environment, but their instance number can be different.

h4. 1st step: development

Once the development is finished, some artefacts are delivered to the team "TEST":
* the list of service-unit that must be deployed,
* the service-assemblies or deployable service units as archives to deploy.

With the Petals ESB architect, the team "TEST" defines a simplified version of the Petals ESB bus topology that will be used for testing. Finally we can have such a topology using machines:
* {{host-test-0}} and {{host-test-1}} for both Petals ESB containers,

Once tests are passed, we validate deliverables on a pre-production environment for which the Petals ESB bus topology is the same than the production environment. As the pre-production environment is a mirror of the production environnment, this topology was defined by the Petals ESB architect in agreement with production operators. Service units deployed are the same than the one of the testing environment, only machines and few configuration items are different between environments PRE-PROD and PROD. Machines of the pre-production environment are:
* {{host-prep-0}}, {{host-prep-1}}, {{host-prep-2}} and , {{host-prep-3}} where are running Petals ESB containers,

If no problem has been detected in pre-production stage, the project is deployed on the production environment with the same topology and the same service-units than the one of the pre-production environment, except machines and few parameters:
* {{host-prod-0}}, {{host-prod-1}}, {{host-prod-2}} and , {{host-prod-3}} where are running Petals ESB containers,

In this use case sample, a Petals ESB bus is already deployed, and we want to upgrade it to a new version where:
* a set of service-units must be upgraded, including:
** some service-units to upgrade to an upper version,
** some new service-units to deploy,

In this use case sample, an organisation want to give access to some of its internal resources through its ESB. Moreover, to minimize problems between partners, the organisation wants to isolate each partner, but few partners can use same services.

So, the organisation decides to design an ESB based on several distinct Petals ESB buses. Each partner has its own set of service consumers/providers. Because the service level agreement can be different between partners, the Petals ESB bus topology associated to each partner can be the same or different. For mutualisation reasons, a unique Petals ESB Hazelcast Registry instance is used to host each registry of Petals ESB bus.

h2. Model overview

Petals ESB Deployer is based on a model defining your Petals ESB bus to deploy. This model contains all components and their configurations forming your Petals ESB bus.

The model of your Petals ESB bus is composed of 4 separated parts whose each goal is different:
* a 1st model defines the *applicative content* of your Petals ESB bus. The *Service-units Object Model* lists all service-units that must be deployed into your Petals ESB bus,
* a 2nd model defines the *topologic architecture* of your Petals ESB bus. The *Topology Object Model* designs your Petals ESB bus topology,
* and a *physical view* of your Petals ESB bus defining the placement of each components. The *Bus Object Model* locates:
** where are running the service-units, on which Petals ESB container of your topology,
** where are running your Petals ESB containers, on which machine,
** where are running your Petals ESB Hazelcast Registry nodes, on which machine,
** which kind of machines are running all needed components,
** where are running "virtual machine" (VM, DOcker container, ...), on which host,
** which external resources are to be used (as placeholder values).

These models are completed by a *Component Repository Model* that defines for each component:
* where its archive can be found,
* which are its configuration parameter,
* and, which shared libraries are required.
The *Component Repository Model* is not dedicated to your Petals ESB bus. It can be easily reused. Each Petals ESB distribution pack includes such a model for all components that delivers.

{anchor:serviceUnitsObjectModel}

h2. Service-units Object Model

This model defines a set of service units to deploy on your Petals ESB bus as *Service Unit Objects*. This model will be mainly written by development teams because they have the knowledge of service units to deploy.

!serviceUnitsObjectModel.png!

This model is composed of following elements:
* {{service-units}}, the list of service units that must be deployed,
* {{service-unit}}, one service unit to deploy:
** {{id}}, the identifier of this service-unit in the model. Can be different from the service unit name,
** {{url}}, the URL of the associated archive that can be a service assembly or a deployable service unit,
** {{archive-checksum}}, SHA-256 checksum of the associated archive file,
** {{component-instance-id}}, the identifier of the component instance on which this service unit must be deployed. Optional for deployable service unit and service unit embedded in a service assembly, requires for other service units,
** {{placeholder-references}}, the set of references on placeholder objects that the service unit object requires for its execution,
* {{placeholders}}, a set of placeholder objects configuring service unit objects,
* {{placeholder}}, a placeholder object configuring service unit objects:
** {{key}}, the placeholder name as used in the service-unit. A value can be associated to this placeholder in the [bus object model|#busObjectModel],
** {{description}}, a description of the placeholder. Optional,
** {{default-value}}, default value of the placeholder. Optional.

{note}
Placeholders without a default value will have to be set in the [Bus Object Model model|#busObjectModel] or the associated property '{{<placeholder-key>}}' will have to be set when deploying the model.
{note}

{anchor:topologyObjectModel}

h2. Topology Object Model

This model defines a set of topologies, as *Topology Object*, used by your Petals ESB busses. This model will be mainly written by the Petals ESB bus architect.

!topologyObjectModel.png!

This model is composed of following elements:
* {{topology}}, the topology definition of a Petals ESB bus, with:
** {{default-domain-name}}, default domain name of the topology. Optional.
** {{containers}}, its different Petals ESB containers as a list of {{container}},
** {{registry}}, the registry used in your topology. Optional.
* {{container}}, a Petals ESB container member of your topology:
** {{id}}, identifier of the Petals ESB container as used as name in the file {{topology.xml}},
** {{default-jmx-port}}, default JMX port value for Petals ESB container instance of this container definition. A [deployment property|#deployment_properties] can be used. Optional, if not set, the internal default value '{{7700}}' will be used,
** {{default-jmx-user}}, default JMX username value of the Petals ESB container instance of this container definition. A [deployment property|#deployment_properties] can be used. Optional, if not set, the internal default value '{{petals}}' will be used,
** {{default-jmx-password}}, default JMX password value of the Petals ESB container instance of this container definition. A [deployment property|#deployment_properties] can be used. Optional, if not set, the internal default value '{{petals}}' will be used,
* {{standalone-registry}}, the registry is implemented by Petals ESB Standalone Registry, default implementation for a standalone topology. Can not be used for a distributed topology,
* {{hazelcast-registry}}, the registry is implemented by Petals ESB Hazelcast Registry, default implementation for a distributed topology:
** {{default-group-name}}, default group name value for the instance of this Petals ESB Hazelcast Registry definition. A [deployment property|#deployment_properties] can be used. Optional, if not set, the internal default value '{{default-sample}}' will be used,
** {{default-group-password}}, default password value for the instance of this Petals ESB Hazelcast Registry definition. A [deployment property|#deployment_properties] can be used. Optional, if not set, the internal default value '{{s3cr3t}}' will be used,
** {{members}}, the members of the Petals ESB Hazelcast Registry,
* {{hazelcast-registry-member}}, a member of the Petals ESB Hazelcast Registry:
** {{id}}, identifier of the Petals ESB Hazelcast Registry member as used as name in the file {{cluster.xml}},
** {{default-port}}, default communication port value for the instance of this Petals ESB Hazelcast Registry member definition. A [deployment property|#deployment_properties] can be used. Optional, if not set, the internal default value '{{7900}}' will be used,

{anchor:busObjectModel}

h2. Bus Object Model

This model defines your Petals ESB bus placing Petals ESB components on their containers:
* service-unit on its Petals ESB container,
* Petals ESB container on its machine,
* Petals ESB Hazelcast Registry member on its machine.

This model will be mainly written by the Petals ESB bus architect in agreement with operators.

!busObjectModel.png!

This model is composed of following elements:
* {{busses}}, the set of Petals ESB busses to deploy,
** {{busses}}, the list of Petals ESB bus instances to deploy,
** {{machines}}, a list of {{machine}} on which the current Petals ESB busses will be running,
** {{component-instances}}, the component instances require by service unit instances to deploy,
* {{bus}}, a Petals ESB bus to deploy, with:
** {{service-unit-instances}}, the service unit instances to deploy,
** {{topology-instance}}, the topology instance on which the Petals ESB bus will be deployed
* {{machine}}, a machine on which a part of a Petals ESB bus will be running:
** {{id}}, identifier of the machine used as reference key for {{container-instance}} and {{hazelcast-registry-member-instance},
** several types of machines are supported:
*** {{provisioned-machine}}, a provisioned machine as a physical machine or a virtual machine already existing:
**** {{hostname}}, hostname, IP address or [deployment property|#deployment_properties] name for the current provisioned machine,
*** {{docker-container}}, a Docker container running a Petals ESB component:
**** {{docker-host-hostname}}, hostname, IP address or [deployment property|#deployment_properties] name of the Docker host on which the Docker container will be started,
**** {{docker-host-port}}, port or [deployment property|#deployment_properties] of the Docker daemon of the Docker host on which the Docker container will be started,
* {{topology-instance}}, the topology instance associated to a topology object defined in the topology object model,
** {{domain-name}}, domain name of the Petals ESB bus. A [deployment property|#deployment_properties] can be used. Optional, if not set, the value defined by the [topology|#topologyObjectModel] object will be used,
** {{registry-instance}}, the instance of the registry to used in the topology,
** {{container-instances}}, the instances of Petals ESB containers forming the Petals ESB bus,
* {{container-instance}}, the instance of a Petals ESB container defined in the topology object model:
** {{reference}}, reference to a {{container}} of the [topology object model|#topologyObjectModel],
** {{machine-reference}}, the reference of the machine on which the current Petals ESB Container is running,
** {{jmxPort}}, port JMX of the current Petals ESB container. A [deployment property|#deployment_properties] can be used. Optional, if not set, the value defined by the [referenced container|#topologyObjectModel] object will be used,
** {{jmxUser}}, JMX username of the current Petals ESB container. A [deployment property|#deployment_properties] can be used. Optional, if not set, the value defined by the [referenced container|#topologyObjectModel] object will be used,
** {{jmxPassword}}, JMX password of the current Petals ESB container. A [deployment property|#deployment_properties] can be used. Optional, if not set, the value defined by the [referenced container|#topologyObjectModel] object will be used,
* {{service-unit-instance}}, an instance of a service unit running on a Petals ESB container:
** {{reference}}, reference to a {{service-unit}} of the [service-units object model|#serviceUnitsObjectModel],
** {{container-reference}}, reference to a {{container}} of the [topology object model|#topologyObjectModel],
** {{placeholder-instances}}, the set of {{placeholder-instance}} that must be applied to configure the current service-unit instance. Optional,
* {{placeholder-instance}}, an instance of placeholder to define its value:
** {{reference}}, reference to a {{placeholder}} of the [service-units object model|#serviceUnitsObjectModel],
** {{value}}, value to set to the current placeholder,
* {{component-instance}}, a component instance requires by a service unit:
** {{id}}, the identifier of this component in the model. Must be the same than the component id of a service unit of the [service-units object model|#serviceUnitsObjectModel],
** {{reference}}, reference to a {{component}} of the [component repository model|#componentRespositoryModel],
** {{sharedLibraryReferences}}, reference to a set of shared libraries of the [component repository model|#componentRespositoryModel] used to override the shared library definition of the associated component. These shared libraries will be added to the ones already refereced ate component definition level. Optional,
** {{parameter-instances}}, the set of {{parameter-instance}} used to configure the current component instance. Optional,
* {{parameter-instance}}, an instance of configuration parameter to define its value:
** {{reference}}, reference to a {{parameter}} of the component in the [component respository model|#componentRepositoryModel],
** {{value}}, value to set to the current parameter,
* {{hazelcast-registry-instance}} defines the registry instance of the current Petals ESB bus as a Petals ESB Hazelcast Registry instance:
** {{reference}}, the reference of the Petals ESB Hazelcast Registry in the [topology object model|#topologyObjectModel],
** {{group-name}}, name identifying the Petals ESB Hazelcast Registry instance inside the Hazelcast cluster. A [deployment property|#deployment_properties] can be used. Optional, if not set, the value defined by the [referenced Petals ESB Hazelcast Registry|#topologyObjectModel] object will be used,
** {{group-password}}, password of the Petals ESB Hazelcast Registry instance. A [deployment property|#deployment_properties] can be used. Optional, if not set, the value defined by the [referenced Petals ESB Hazelcast Registry|#topologyObjectModel] object will be used,
** {{member-instances}}, list of member instances ({{hazelcast-registry-member-instance}}) composing the current Petals ESB Hazelcast Registry instance,
* {{hazelcast-registry-member-instance}}, a member of the current Petals ESB Hazelcast Registry instance:
** {{reference}}, the reference of the member of the Petals ESB Hazelcast Registry in the [topology object model|#topologyObjectModel],
** {{host-machine}}, the reference of the machine on which the current Petals ESB Hazelcast Registry is running,
** {{port}}, the communication port of the current member instance. A [deployment property|#deployment_properties] can be used. Optional, if not set, the value defined by the [referenced Petals ESB Hazelcast Registry member|#topologyObjectModel] object will be used.

h2. Component Repository Model

This model defines a set of binding components, service engines and shared libraries as *Component Object* that can be used to perform the deployment of a Petals ESB bus. Such models are included in Petals ESB distribution packs for all components that includes, and you can write your own.

!componentRepositoryModel.png!

This model is composed of following elements:
* {{components}}, the list of component objects of this repository,
* {{component}}, one component object of this repository:
** {{id}}, the identifier of this component object in the model. Must be the same than the one defines in the JBI descriptor of the component,
** {{url}}, the URL of the associated archive,
** {{archive-checksum}}, SHA-256 checksum of the associated archive file,
** {{parameters}}, a set of parameters to configure the component,
** {{sharedLibraryReferences}}, a set of shared library references that the component requires. Optional,
* {{parameter}}, a configuration parameter of a component:
** {{name}}, the configuration parameter name as declared in the JBI descriptor of the component. A value can be associated to this parameter in a [bus object model|#busObjectModel],
** {{default-value}}, default value of the placeholder. Optional.
* {{shared-libraries}}, the list of shared libraries of this repository. Optional,
* {{sharedLibrary}}, a shared library of this repository:
** {{id}}, the identifier of this shared library in the model. Must be the same than the one defines in the JBI descriptor of the shared library,
** {{version}}, the version of this shared library in the model. Must be the same than the one defines in the JBI descriptor of the shared library,
** {{url}}, the URL of the associated archive,
** {{archive-checksum}}, SHA-256 checksum of the associated archive file.

{note}
Parameter without a default value will have to be set in the [Bus Object Model model|#busObjectModel] or the associated property '{{<component-id>.<parameter-name>}}' will have to be set when deploying the model.
{note}

{anchor:deployment_properties}

h2. Deployment properties

Deployment properties can be used in models to specify the following elements:
* in the service units object model:
** a default value of a placeholder
* in the topology object model:
** default values of Petals ESB container parameters,
** default values of Petals ESB Hazelcast Registry parameters,
* in the bus object model:
** configuration values for machines: IP address, Docker host parameters,
** configuration values for Petals ESB container instances overriding the default ones,
** configuration values for Petals ESB Hazelcast Registry instance overriding the default ones,
* or to set the value of a service unit placeholder that has neither value nor default value set.

Each deployment property values will be required at deployment time.

{anchor:axioms}

h2. Axioms

* About service unit object model:
** A service unit model definition must contain at least one service-unit object,
** The identifier of a service unit object must be unique over the service unit object model,
** The URL of a service unit object must point to a service unit archive,
** The identifier of a service unit object must match:
*** the identifier defined in the service unit archive, if it's a deployable service unit,
*** the identifier defined in the service assembly descriptor, if it's embedded in a service assembly,
** The component-id of a service unit object is extracted:
*** if it's a deployable service unit, from the service unit archive identified by the provided URL,
*** if it's embedded in a service assembly archive, from the JBI descriptor of the service assembly archive identified by the provided URL,
*** otherwise the component id must be set,
** The identifier of a placeholder object must be unique over the service unit object model,
** A placeholder object is referenced by a service unit object at most one time,
** Different service unit objects can reference a same placeholder object.

* About topology object model:
** A topology object model definition must contain only one topology object,
** A topology object must contain at least one container,
** Petals ESB Hazelcast Registry and Petals ESB Standalone registries cannot coexist,
** A Petals ESB Standalone registry can be used only when there is a unique container,
** The Petals ESB Hazelcast Registry must be used if at least two Petals ESB containers are declared,
** The Petals ESB Hazelcast Registry must contain at least one Petals ESB Hazelcast Registry member,

* About component repository model:
** A component repository model must contain at least one component object,
** The URL of a component object must point to a component archive,

* About bus object model:
** A bus object model contains at least one machine object,
** A bus instance always refers to only one topology object,
** A machine must host at least one Petals ESB container or one Petals ESB Hazelcast Registry member,
** Two machines can refer to a same physical machine if they will have the same configuration values or deployment properties,
** Petals ESB container instances and Petals ESB Hazelcast Registry member instances can reference the same machine to force a co-localization,
** Identifiers of component instances must be unique
** All service units placed on a container instance must refer to a declared component instance,
** Two service units can refer to a same component with two different configurations if the service unit instances use two different component instances referencing a same component object,

* About service unit object model vs bus object model:
** A bus object model definition imports 0 to many service unit object models,
** A bus object model definition defines 0 to many service unit object models,
** A bus object model must contains at least one service unit: if no service unit object model is imported by a bus object model, the bus object model must define at least one service unit object model,
** The identifier of a service unit object must be unique over all service unit objects model declared and imported in a bus object model,
** The identifier of a placeholder object must be unique over all service unit objects model declared and imported in a bus object model,
** A service unit instance can have only placeholder instances referencing placeholder objects that are referenced by the associated service unit object.

* About topology object model vs bus object model:
** A bus object model definition imports 0 to many topology object model definitions,
** A bus object model definition defines 0 to many topology object model definitions,
** A bus object model must contains at least one topology object: if no topology object model is imported by a bus object model, the bus object model must define at least one topology object model,
** The identifier of a topology object must be unique over all topology object models declared and imported in a bus object model.
** A topology instance of a bus instance declares as many container instances as there are containers defined in the associated topology object,
** A topology instance of a bus instance declares as many Petals ESB Hazelcast Registry member instances as there are Petals ESB Hazelcast Registry member defined in the associated topology object,

* About component repository model vs bus object model:
** A bus object model definition imports 0 to many component repository model definitions,
** A bus object model definition defines 0 to many component repository model definitions,
** A bus object model must contains at least one component repository: if no component repository model is imported by a bus object model, the bus object model must define at least one component repository model,
** The identifier of a component objects must be unique over all component repository models declared and imported in a bus object model.

h2. Writing your deployment model

The best practice is to write your deployment model with different files, but you are able to write your deployment model in only one file.

h3. Writing your deployment model in separated files

The best practice is to write your deployment model with different files:
* a 1st file for your service units object model, written by your development team,
* an optional 2nd file for your component repository model, written by your development team in agreement with the Petals ESB architect. Petals ESB distribution packs come with a component repository model associated to their content,
* a 3rd file for your topology object model, written by the Petals ESB architect,
* and a 4th file for your bus object model, written by the Petals ESB bus architect in agreement with operators, importing other models:
** several service units object models can be imported,
** several component repository models can be imported,
** several topology object models can be imported.

h4. Writing a service units object model

Example of a service unit object model:
{code:lang=xml}
<service-units xmlns="http://petals.ow2.org/deployer/models/service-units.om/1.0" targetNamespace="http://petals.ow2.org/deployer/sample.suom">
<service-unit id="su-filetransfer-consume">
<url>mvn://org.ow2.petals.samples.filetransfer/su-filetransfer-consume/4.1.0-1.0.0</url>
</service-unit>
<service-unit id="su-filetransfer-provide">
<url>mvn://org.ow2.petals.samples.filetransfer/su-filetransfer-provide/4.1.0-1.0.0</url>
</service-unit>
</service-units>
{code}

h4. Writing a service units object model

Example of a service unit object model:
{code:lang=xml}
<service-units xmlns="http://petals.ow2.org/deployer/models/service-units.om/1.0" targetNamespace="http://petals.ow2.org/deployer/sample.suom">
<service-unit id="su-filetransfer-consume">
<url>mvn://org.ow2.petals.samples.filetransfer/su-filetransfer-consume/4.1.0-1.0.0</url>
</service-unit>
<service-unit id="su-filetransfer-provide">
<url>mvn://org.ow2.petals.samples.filetransfer/su-filetransfer-provide/4.1.0-1.0.0</url>
</service-unit>
</service-units>
{code}

h4. Writing a component repository model

Example of a component repository model:
{code:lang=xml}
<components xmlns="http://petals.ow2.org/deployer/models/components.rm/1.0" targetNamespace="http://petals.ow2.org/deployer/sample.crm">
<component id="petals-bc-filetransfer">
<url>mvn://org.ow2.petals/petals-bc-filetransfer/4.1.0</url>
<parameters>
<parameter name="properties-file">petals-bc-filetransfer.properties</parameter>
</parameters>
</component>
</components>
{code}

Example of a distributed topology object model:
{code:lang=xml}
<topology xmlns="http://petals.ow2.org/deployer/models/topology.om/1.0" targetNamespace="http://petals.ow2.org/deployer/sample-distributed.tom"
id="bi-containers"
default-domain-name="PEtALS">
<containers>
<container id="cont-0" />
<container id="cont-1" />
</containers>
<hazelcast-registry>
<members>
<member id="hzlreg-0" />
</members>
</hazelcast-registry>
</topology>
{code}

h4. Writing a bus object model

Example of a bus based on a standalone topology:
{code:lang=xml}
<busses
xmlns="http://petals.ow2.org/deployer/models/bus.om/1.0"
xmlns:suom="http://petals.ow2.org/deployer/sample.suom"
xmlns:tom="http://petals.ow2.org/deployer/sample-standalone.tom"
targetNamespace="http://petals.ow2.org/deployer/sample-standalone.bom">

<!-- Import of the service unit object model -->
<import namespace="http://petals.ow2.org/deployer/sample.suom" location="sample.suom"
importType="http://petals.ow2.org/deployer/models/service-units.om/1.0">
<!-- Import of the component repository model -->
<import namespace="http://petals.ow2.org/deployer/sample.crm" location="sample.crm"
importType="http://petals.ow2.org/deployer/models/components.rm/1.0">
<!-- Import of the topology object model -->
<import namespace="http://petals.ow2.org/deployer/sample-standalone.tom" location="sample-standalone.tom"
importType="http://petals.ow2.org/deployer/models/topology.om/1.0">

<machines>
<provisioned-machine id="machine-00">
<hostname>machine-00.petals.org</hostname>
</provisioned-machine>
</machines>

<bus>
<topology-instance ref="tom:bi-containers">
<container-instances>
<container-instance ref="tom:cont-0" machine-ref="machine-00" jmx-port="7700" jmx-user="petals" jmx-password="petals"/>
</container-instances>
</topology-instance>

<service-unit-instances>
<service-unit-instance ref="suom:su-filetransfer-consume" container-ref="tom:cont-0" />
<service-unit-instance ref="suom:su-filetransfer-provide" container-ref="tom:cont-0" />
</service-unit>
</bus>
</busses>
{code}

Example of a bus based on a distributed topology:
{code:lang=xml}
<busses
xmlns="http://petals.ow2.org/deployer/models/bus.om/1.0"
xmlns:suom="http://petals.ow2.org/deployer/sample.suom"
xmlns:tom="http://petals.ow2.org/deployer/sample-distributed.tom"
targetNamespace="http://petals.ow2.org/deployer/sample-standalone.bom">

<!-- Import of the service unit object model -->
<import namespace="http://petals.ow2.org/deployer/sample.suom" location="sample.suom"
importType="http://petals.ow2.org/deployer/models/service-units.om/1.0">
<!-- Import of the component repository model -->
<import namespace="http://petals.ow2.org/deployer/sample.crm" location="sample.crm"
importType="http://petals.ow2.org/deployer/models/components.rm/1.0">
<!-- Import of the topology object model -->
<import namespace="http://petals.ow2.org/deployer/sample-distributed.tom" location="sample-distributed.tom"
importType="http://petals.ow2.org/deployer/models/topology.om/1.0">

<machines>
<provisioned-machine id="machine-00">
<hostname>machine-00.petals.org</hostname>
</provisioned-machine>
<provisioned-machine id="machine-01">
<hostname>machine-01.petals.org</hostname>
</provisioned-machine>
<provisioned-machine id="machine-02">
<hostname>machine-02.petals.org</hostname>
</provisioned-machine>
</machines>

<bus>
<topology-instance ref="tom:bi-containers">
<hazelcast-registry-instance group-name="default-sample" group-password="s3cr3t">
<hazelcast-registry-member-instances>
<hazelcast-registry-member-instance machine-ref="machine-02" port="7900" />
</hazelcast-registry-member-instances>
</hazelcast-registry-instance>

<container-instances>
<container-instance ref="tom:cont-0" machine-ref="machine-00" jmx-port="7700" jmx-user="petals" jmx-password="petals"/>
<container-instance ref="tom:cont-1" machine-ref="machine-01" jmx-port="7700" jmx-user="petals" jmx-password="petals"/>
</container-instances>
</topology-instance>

<service-unit-instances>
<!-- Service unit deployed on container 'cont-0' -->
<service-unit-instance ref="suom:su-filetransfer-consume" container-ref="tom:cont-0" />
<service-unit-instance ref="suom:su-filetransfer-provide" container-ref="tom:cont-0" />

<!-- Service unit deployed on container 'cont-1' -->
<service-unit-instance ref="suom:su-filetransfer-consume" container-ref="tom:cont-1" />
<service-unit-instance ref="suom:su-filetransfer-provide" container-ref="tom:cont-1" />
</service-unit>
</bus>
</busses>
{code}

h3. Writing your deployment model in only one file

Example of a bus based on a standalone topology:
{code:lang=xml}
<busses
xmlns="http://petals.ow2.org/deployer/models/bus.om/1.0"
xmlns:tns="http://petals.ow2.org/deployer/sample-standalone.bom"

targetNamespace="http://petals.ow2.org/deployer/sample-standalone.bom">

<!-- Import of the component repository model coming from Petals ESB -->
<import namespace="http://petals.ow2.org/deployer/sample.crm" location="classpath:petals-component-repository.xml"
importType="http://petals.ow2.org/deployer/models/components.rm/1.0">

<suom:service-units xmlns:suom="http://petals.ow2.org/deployer/models/service-units.om/1.0">
<service-unit id="su-filetransfer-consume">
<url>mvn://org.ow2.petals.samples.filetransfer/su-filetransfer-consume/4.1.0-1.0.0</url>
</service-unit>
<service-unit id="su-filetransfer-provide">
<url>mvn://org.ow2.petals.samples.filetransfer/su-filetransfer-provide/4.1.0-1.0.0</url>
</service-unit>
</suom:service-units>

<topologies>
<tom:topology xmlns:tom="http://petals.ow2.org/deployer/models/topology.om/1.0"
id="standalone"
default-domain-name="PEtALS">
<containers>
<container id="cont-0" />
</containers>
</tom:topology>
</topologies>

<machines>
<provisioned-machine id="machine-00">
<hostname>machine-00.petals.org</hostname>
</provisioned-machine>
</machines>

<bus>
<topology-instance ref="tom:standalone">
<container-instances>
<container-instance ref="tns:cont-0" machine-ref="machine-00" jmx-port="7700" jmx-user="petals" jmx-password="petals"/>
</container-instances>
</topology-instance>

<service-unit-instances>
<service-unit-instance ref="tns:su-filetransfer-consume" container-ref="tns:cont-0" />
<service-unit-instance ref="tns:su-filetransfer-provide" container-ref="tns:cont-0" />
</service-unit>
</bus>
</busses>
{code}

h1. Executing deployment

h2. Launching a deployment

A Petals ESB bus deployment is launched through the command {{deploy}} of [Petals ESB CLI|petalsclisnapshot:Petals ESB CLI 3.2.0-SNAPSHOT#deploy]. See the documentation of the command to get more information.

h2. Deployment execution

h3. Step #1: Pre-checks

Different errors can occurs during the full deployment process of a Petals ESB bus:
* errors linked to invalid model definitions,
* errors linked to unavailable artefacts,
* errors linked to unreachable machines,
* ...

Petals ESB Deployer avoid to start a deployment if one of these error can occur. So no undeployment is needed to redeploy the Petals ESB bus. That'why [static|#static-checks] and [dynamic|#dynamic-checks] checks are applied, example:
* validating that artefacts are available and have the right checksum (this check is not sufficient to assume that artefacts will be always reachable, but this avoid error on their URL),
* checking that all machines are reachable (this check is not sufficient to assume that machine will be always reachable, but this avoid error on hostname, IP address and port),
* ...

{anchor:static-checks}

h4. Static checks

First checks applied are the basic checks as:
* the [validation|#axioms] of the provided bus object model. If the bus object model is invalid, the deployment process is aborted and an error is returned,
* archives associated to service unit objects, component objects and shared library object are available and have the right checksum. If a associated archive is unavailable or has an unexpected checksum, the deployment process is aborted and an error is returned,
* containers declared as running on provisioned machines are really running (a JMX connection can be established). If a container is unreachable, the deployment process is aborted and an error is returned.

{anchor:dynamic-checks}

h4. Dynamic checks

To complete the basic checks a set of dynamic checks is applied to validate the execution context of each container running on provisioned machines:
* the identifier of the container running on the provisioned machine must match the identifier of the associated container instance. If not, the deployment process is aborted and an error is returned.

h3. Step #2: Deployment logic execution

h4. Deployment execution

According to the bus object model, service units instance are configured and deployed taking into account required dependencies as component instances and shared library instances.

h4. Concurrent deployments

To be able to redeploy a Petals ESB bus from scratch in a minimum time, the deployment of the Petals ESB bus must be the fastest as possible. So, Petals ESB containers are deployed concurrently.

h3. Step #3: Deployment verification

Once all is deployed, a verification of the deployment is launched:
* a model is built from the on-line Petals ESB bus (the one previously deployed),
* and compared to the initial bus object model.

They should be similar, the same object instances must exist on both side without other object instances.

h1. Verifying deployment

A Petals deployment model (ie. [bus object model|#busObjectModel]) can be used to verify the installation of a topology checking:
* topology architecture against the [topology object model|#topologyObjectModel],
* topology instantiation against the topology instance of the [bus object model|#busObjectModel],
* for each container of the topology:
** shared libraries installed,
** components and their configuration installed,
** service units deployed and their placeholders.

h2. Launching the verification

The installation verification is launched using Petals CLI through the command '{{to-be-defined}}' requiring a bus object model and a topology instance identified by the Petals ESB container on which Petals CLI is connected.

h2. Checking topology

First, the Petals ESB container on which we are connected *must* be declared as container instance into the bus object model. Next, the current topology is retrieved from the Petals ESB container on which we are connected. Each container of the current topology *must* be declared as container instance into the bus object model, and all containers instances of the bus object model must form the current topology.

The current registry retrieved from the current topology *must* match the registry instance declared in the bus object model: same implementation, same clustering.

h2. Checking share libraries

For each shared library instance referenced in the bus object model through component instances:
* it *must* be installed on the expected container,
* the checksum of the archive used for installation *must* match the checksum declared in the component repository model.

h2. Checking components

For each component instance referenced in the bus object model:
* it *must* be installed on the expected container,
* the checksum of the archive used for installation *must* match the checksum declared in the component repository model,
* the installed component *must* use only the shared libraries declared in the bus object model,
* the configuration of the installed component *must* match the configuration declared in the bus object model for all parameter values that are not deployment properties.

h2. Checking service units

For each service unit instance referenced in the bus object model:
* it *must* be deployed on the expected container,
* the checksum of the archive used for deployment *must* match the checksum declared in the service unit object model,
* the configuration of the service unit instance *must* match the configuration declared in the bus object model for all placeholder values that are not deployment properties.

h1. Petals Deployment Model

h2. Source code

Maven project work in progress (POC ?)

[Petals ESB Deployer 1.0.0^petals-deployment-model.zip]

Here is a project to try making deployment model for an existing project (with script CLI)

[Petals ESB Deployer 1.0.0^hdbank-deployment-model.zip]