Difference between revisions of "Profile Specification"
Luca.frosini (Talk | contribs) (→MainPackage) |
m |
||
(102 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
+ | <!-- CATEGORIES --> | ||
+ | [[Category:Developer's Guide]] | ||
+ | <!-- END CATEGORIES --> | ||
= Preliminary definitions = | = Preliminary definitions = | ||
Line 10: | Line 13: | ||
* Running Instance ([[runninginstance-schema|XSD]]) | * Running Instance ([[runninginstance-schema|XSD]]) | ||
* External Running Instance ([[externalrunninginstance-schema|XSD]]) | * External Running Instance ([[externalrunninginstance-schema|XSD]]) | ||
− | * VRE ([[ | + | * VRE ([[Generic-Resource-schema|XSD]]) |
* Collection ([[collection-schema|XSD]]) | * Collection ([[collection-schema|XSD]]) | ||
* Metadata Collection ([[metadatacollection-schema|XSD]]) | * Metadata Collection ([[metadatacollection-schema|XSD]]) | ||
− | + | * gLite resource ([[Generic-Resource-schema|XSD]]) | |
− | + | ||
− | + | ||
− | * gLite resource ([[ | + | |
Such resources can be combined or created at VRE creation time in order to set up a new Virtual Research Environment. | Such resources can be combined or created at VRE creation time in order to set up a new Virtual Research Environment. | ||
= The gHN resource = | = The gHN resource = | ||
− | A | + | A gCube Hosting Node (shortly, a gHN) is the resource modelling a node of an infrastructure able to host gCube Running Instances. |
+ | |||
+ | The gHN resource is built by collecting and grouping both the configuration and runtime information on the node. The profile of the gHN is composed by two classes of information: | ||
+ | |||
+ | * static information, i.e. information that does not change once the gHN is started | ||
+ | |||
+ | * dynamic information, i.e. information that changes during the gHN lifetime | ||
+ | |||
+ | At the top level, there are four main sections in the gHN profile: | ||
+ | |||
+ | * ''Infrastructure'', reporting the name of the infrastructure to which the gHN is joined to | ||
+ | |||
+ | * ''GHNDescription'', a GLUE compliant section describing the hardware characteristics of the node | ||
+ | |||
+ | * ''Site'', reporting information about the site to which the gHN belongs to | ||
+ | |||
+ | * ''DeployedPackages'', reporting the list of gCube software packages actually deployed on the gHN | ||
[TBC] | [TBC] | ||
Line 35: | Line 51: | ||
Concretely, a Package is a “piece of software” that can be deployed on a [[Profile_Specification#The_gHN_resource|gHN]]. A Package can be: | Concretely, a Package is a “piece of software” that can be deployed on a [[Profile_Specification#The_gHN_resource|gHN]]. A Package can be: | ||
* a ''[[Profile_Specification#MainPackage|MainPackage]]'', representing a package that once deployed produces a WSRF Service (a service able to manage stateful resources following the WS-Resource patterns); | * a ''[[Profile_Specification#MainPackage|MainPackage]]'', representing a package that once deployed produces a WSRF Service (a service able to manage stateful resources following the WS-Resource patterns); | ||
− | * a ''[[Profile_Specification#Software|Software]]'', a software library (typically composed by one or more JAR archives) offering functionality for interacting with Service or a | + | * a ''[[Profile_Specification#Software|Software]]'', a software library (typically composed by one or more JAR archives) offering functionality for interacting with Service or a third party software distributed with the service that can be dynamically deployed; |
About how to define a package, see the [[Profile_Specification#Packages_section| Packages section]]. | About how to define a package, see the [[Profile_Specification#Packages_section| Packages section]]. | ||
Line 50: | Line 66: | ||
− | We enforce the use of this | + | We enforce the use of this convention: |
− | + | ||
− | + | ||
− | + | Main Package Name='''''ServiceName''-service''' | |
− | + | Stubs='''''ServiceName''-stubs''' | |
+ | Test suite='''''ServiceName''-test-suite''' | ||
+ | '''Example''': | ||
− | + | if the ''ServiceName'' is '''''Deployer''''', we will use: | |
− | Main Package Name | + | Main Package Name='''Deployer-service''' |
− | Stubs | + | Stubs='''Deployer-stubs''' |
− | Test suite | + | Test suite='''Deployer-test-suite''' |
===== How to behave with library ===== | ===== How to behave with library ===== | ||
+ | A library can be profiled in several ways, mainly depending of its source. The following table depicts them: | ||
{| align=center border=1 | {| align=center border=1 | ||
Line 78: | Line 95: | ||
| Service specific library || NO (Packaged with Service) || YES | | Service specific library || NO (Packaged with Service) || YES | ||
|- | |- | ||
− | | | + | | Library not service specific || YES (''Any Service Class'') || YES |
|- | |- | ||
| Service Indipendent (Deployable) || YES (''ExternalSoftware'' Class) || YES | | Service Indipendent (Deployable) || YES (''ExternalSoftware'' Class) || YES | ||
Line 86: | Line 103: | ||
− | ====== Example of profile for | + | ====== Example of profile for library not service specific ====== |
+ | This is a basic template for a library profile: | ||
+ | |||
+ | <source lang="xml"> | ||
<Resource> | <Resource> | ||
<ID></ID> | <ID></ID> | ||
Line 93: | Line 113: | ||
<Profile> | <Profile> | ||
<Description>....</Description> | <Description>....</Description> | ||
− | <Class> | + | <Class>... a class name...</Class> |
− | <Name> | + | <Name>... a library name...</Name> |
− | <Version> | + | <Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version> |
… | … | ||
<Packages> | <Packages> | ||
<Software> | <Software> | ||
<Description></Description> | <Description></Description> | ||
− | <Name> | + | <Name>... a library name...</Name> |
− | <Version> | + | <Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version> |
+ | <MavenCoordinates> | ||
+ | <GroupId></GroupId> | ||
+ | <ArtifactId></ArtifactId> | ||
+ | <Version></Version> | ||
+ | </MavenCoordinates> | ||
… | … | ||
</Software> | </Software> | ||
Line 107: | Line 132: | ||
</Profile> | </Profile> | ||
</Resource> | </Resource> | ||
+ | </source> | ||
− | + | where: | |
− | + | ||
+ | ''... a class name...'' has to be replaced with the name of Service Class the library belong to | ||
− | '' | + | ''... a library name...'' has to be replaced with the name of Library name |
+ | ''\d{1,2}+.\d{1,2}+.\d{1,2}'' has to be replaced with the actual version of the Library | ||
+ | The following is an instance example of the template: | ||
+ | <source lang="xml"> | ||
<Resource> | <Resource> | ||
<ID></ID> | <ID></ID> | ||
Line 131: | Line 160: | ||
<Name>ResultSetLibrary</Name> | <Name>ResultSetLibrary</Name> | ||
<Version>1.0.0</Version> | <Version>1.0.0</Version> | ||
+ | <MavenCoordinates> | ||
+ | <GroupId>org.gcube.search</GroupId> | ||
+ | <ArtifactId>resultsetlibrary</ArtifactId> | ||
+ | <Version>1.0.0</Version> | ||
+ | </MavenCoordinates> | ||
+ | |||
... | ... | ||
</Software> | </Software> | ||
Line 136: | Line 171: | ||
</Profile> | </Profile> | ||
</Resource> | </Resource> | ||
+ | </source> | ||
− | ====== Example of profile for Service | + | ====== Example of profile for Service Independent (Deployable) library ====== |
+ | This is a basic template for a Service Independent (Deployable) library profile: | ||
+ | <source lang=xml> | ||
<Resource> | <Resource> | ||
<ID></ID> | <ID></ID> | ||
Line 145: | Line 183: | ||
<Profile> | <Profile> | ||
<Description></Description> | <Description></Description> | ||
− | <Class> | + | <Class>ExternalSoftware</Class> |
− | <Name> | + | <Name>... a library name...</Name> |
− | <Version> | + | <Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version> |
… | … | ||
<Packages> | <Packages> | ||
<Software> | <Software> | ||
<Description></Description> | <Description></Description> | ||
− | <Name> | + | <Name>... a library name...</Name> |
− | <Version> | + | <Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version> |
+ | <MavenCoordinates> | ||
+ | <GroupId>.. groupID ..</GroupId> | ||
+ | <ArtifactId>.. artifactID ..</ArtifactId> | ||
+ | <Version>.. version ..</Version> | ||
+ | </MavenCoordinates> | ||
… | … | ||
</Software> | </Software> | ||
</Packages> | </Packages> | ||
</Resource> | </Resource> | ||
+ | </source> | ||
+ | |||
+ | where | ||
+ | |||
+ | ''... a library name...'' has to be replaced with the name of Library name | ||
+ | |||
+ | ''\d{1,2}+.\d{1,2}+.\d{1,2}'' has to be replaced with the actual version of the Library | ||
− | + | The following is an instance example of the template: | |
+ | <source lang=xml> | ||
<Resource> | <Resource> | ||
<ID></ID> | <ID></ID> | ||
Line 175: | Line 226: | ||
<Name>commons-httpclient</Name> | <Name>commons-httpclient</Name> | ||
<Version>3.0.1</Version> | <Version>3.0.1</Version> | ||
− | < | + | <MavenCoordinates> |
− | + | <GroupId>org.gcube.externals</GroupId> | |
− | + | <ArtifactId>commons-httpclient</ArtifactId> | |
− | + | <Version>3.0.1</Version> | |
− | + | </MavenCoordinates> | |
− | + | ... | |
− | </ | + | |
</Software> | </Software> | ||
</Packages> | </Packages> | ||
Line 187: | Line 237: | ||
</Profile> | </Profile> | ||
</Resource> | </Resource> | ||
+ | </source> | ||
===== How to specify dependencies ===== | ===== How to specify dependencies ===== | ||
− | + | ||
− | + | The dependencies are specified in the pom of the project, in the profile is only specified the set of maven coordinates. | |
− | + | The artifact can be found on an internal maven repository (Nexus) or on another trusted maven Repository | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
== How to compile a Service profile == | == How to compile a Service profile == | ||
The following example shows the common elements that compose the Service profile. The Package-specific sections are explained apart later. | The following example shows the common elements that compose the Service profile. The Package-specific sections are explained apart later. | ||
− | < | + | |
+ | <source lang=xml> | ||
<Resource xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> | <Resource xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> | ||
− | < | + | <ID></ID> |
<Type>Service</ResourceType> | <Type>Service</ResourceType> | ||
<Scopes> | <Scopes> | ||
Line 215: | Line 259: | ||
<Name>...a service name...</Name> | <Name>...a service name...</Name> | ||
<Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version> | <Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version> | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
<SpecificData/> | <SpecificData/> | ||
<Packages> | <Packages> | ||
Line 238: | Line 265: | ||
</Profile> | </Profile> | ||
</Resource> | </Resource> | ||
− | </ | + | </source> |
=== Common elements === | === Common elements === | ||
Line 251: | Line 278: | ||
The service version must be in the format: \d{1,2}+.\d{1,2}+.\d{1,2} | The service version must be in the format: \d{1,2}+.\d{1,2}+.\d{1,2} | ||
− | + | This version marks a whole gCube distribution and, for the current distribution under development, the version number is fixed to '''1.00.00'''. Future and different distributions will eventually evolve with a different service version. | |
==== Dependencies ==== | ==== Dependencies ==== | ||
Line 258: | Line 285: | ||
==== Packages section ==== | ==== Packages section ==== | ||
This element groups an unbounded sequence of Package-derived elements. Each element describes a package that comes with the service. The structure of a Package element includes an initial common part and a package-specific part rooted by an element named as the service type ([[Profile_Specification#MainPackage|MainPackage]] and [[Profile_Specification#Software|Software]]). | This element groups an unbounded sequence of Package-derived elements. Each element describes a package that comes with the service. The structure of a Package element includes an initial common part and a package-specific part rooted by an element named as the service type ([[Profile_Specification#MainPackage|MainPackage]] and [[Profile_Specification#Software|Software]]). | ||
− | The only constraint is that one and only one [[Profile_Specification#MainPackage|MainPackage]] element is accepted in the list. | + | The only constraint is that one and only one [[Profile_Specification#MainPackage|MainPackage]] element is accepted in the list. |
− | + | ||
− | + | ||
− | |||
The following example shows the elements of a Package definition common to both types of Package. | The following example shows the elements of a Package definition common to both types of Package. | ||
+ | <source lang=xml> | ||
<Packages> | <Packages> | ||
<Main deployable="true"> | <Main deployable="true"> | ||
<Name>Deployer-service</Name> | <Name>Deployer-service</Name> | ||
<Version>1.0.0</Version> | <Version>1.0.0</Version> | ||
+ | <MavenCoordinates> | ||
+ | <groupId>org.gcube.vremanagement</groupId> | ||
+ | <artifactId>deployer-service</artifactId> | ||
+ | <version>1.0.0</version> | ||
+ | </MavenCoordinates> | ||
<Mandatory level="GHN"/> | <Mandatory level="GHN"/> | ||
<Shareable level="VO"/> | <Shareable level="VO"/> | ||
Line 273: | Line 303: | ||
<Requirement category="Site" requirement="string" value="java1.5" operator="ge"/> | <Requirement category="Site" requirement="string" value="java1.5" operator="ge"/> | ||
</GHNRequirements> | </GHNRequirements> | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
<GARArchive>org.gcube.common.vremanagement.deployer.gar</GARArchive> | <GARArchive>org.gcube.common.vremanagement.deployer.gar</GARArchive> | ||
<PortType> | <PortType> | ||
<Name>gcube/common/vremanagement/Deployer</Name> | <Name>gcube/common/vremanagement/Deployer</Name> | ||
<Security/> | <Security/> | ||
− | |||
− | |||
</PortType> | </PortType> | ||
</Main> | </Main> | ||
</Packages> | </Packages> | ||
− | + | </source> | |
− | ====== | + | ====== Name ====== |
An arbritrary string that uniquely identifies the package within this service. | An arbritrary string that uniquely identifies the package within this service. | ||
====== Version ====== | ====== Version ====== | ||
The version of the package. It has to be in the format: \d{1,2}+.\d{1,2}+.\d{1,2} (e.g. 1.0.1 or 1.11.0) | The version of the package. It has to be in the format: \d{1,2}+.\d{1,2}+.\d{1,2} (e.g. 1.0.1 or 1.11.0) | ||
+ | |||
+ | ====== Mandatory ====== | ||
+ | If the ''Mandatory'' element is declared, it states when the package has to be deployed by default. The value of the attribute ''level'' defines at which level the package is mandatory. Accepted values are: ''NONE'', ''GHN'', ''VO'' and ''VRE''. For instance, stating that a package is mandatory at VO level means that each time a new VO is created the package MUST be deployed. | ||
+ | |||
+ | If the element is not declared, the package is assumed to be not mandatory at any level by default. | ||
====== Shareable ====== | ====== Shareable ====== | ||
− | + | If the ''Shareable'' element is declared, it states if the package can be shared across multiple Scopes. The value of the attribute ''level'' defines at which level the package is shareable. Accepted values are: ''NONE'', ''VO'' and ''VRE''. | |
+ | |||
+ | If the value is ''NONE'', the package cannot be shared across any scope, i.e. there must be one and only one deployed instance of that package in a scope. | ||
+ | |||
+ | If the element is not declared, the package is assumed to be shareable at any scope level by default. | ||
====== InstallScripts ====== | ====== InstallScripts ====== | ||
− | This set of scripts are executed before the deployment of the package. They can be used to prepare the environment for the package execution (create a file system structure, install third parties software). The current folder where they are executed is the one where the package | + | This set of scripts are executed before the deployment of the package. They can be used to prepare the environment for the package execution (create a file system structure, install third parties software). The current folder where they are executed is the one where it is places. So, one can navigate the package tree with relative paths starting from the install script folder. |
====== UninstallScripts ====== | ====== UninstallScripts ====== | ||
Line 325: | Line 338: | ||
This set of scripts are executed before each container startup. | This set of scripts are executed before each container startup. | ||
− | ====== | + | ====== MavenCoordinates ====== |
− | The | + | The MavenCoordinates is a set of maven coordinates that defines the artifact realted to the package. |
− | + | The dependencies of the project may be specified in the pom according to maven specifications | |
− | A | + | A set of coordinates is a declaration of the following elements: |
− | * | + | * GroupID |
− | * | + | * ArtifactID |
* Version | * Version | ||
− | |||
+ | ====== GHNRequirements ====== | ||
+ | A GHNRequirement is a requirement against the node where the package is going to be deployed. These requirements are matched with the gHN profiles in order to find a suitable node that can host the package. | ||
+ | A gHN requirement is expressed by: | ||
+ | * ''category'': it identifies the element/attribute of the Profile/GHNDescription section of the gHN profile against which the requirement is expressed. | ||
+ | It can assume one of the following values: | ||
− | + | <div style="border: 1px dashed #2F6FAB; background-color: #F9F9F9; color: black; padding:0.5em; margin-top:5px; margin-bottom:5px; font-family: monospace; font-style: normal; font-size-adjust: none;"> | |
− | + | :* MEM_RAM_AVAILABLE | |
− | + | :* MEM_RAM_SIZE | |
− | + | :* MEM_VIRTUAL_AVAILABLE | |
− | + | :* MEM_VIRTUAL_SIZE | |
− | + | :* HOST | |
− | + | :* OS | |
− | + | :* DISK_SPACE | |
− | + | :* LOAD1MIN | |
− | + | :* LOAD5MIN | |
− | + | :* LOAD15MIN | |
− | + | :* PLATFORM | |
− | + | :* PROCESSOR_NUM | |
− | + | :* PROCESSOR_BOGOMIPS | |
− | + | :* SITE_LOCATION | |
− | + | :* SITE_COUNTRY | |
− | + | :* SITE_DOMAIN | |
− | + | :* CUSTOM_REQUIREMENT | |
− | + | :* RUNTIME_ENV_STRING | |
+ | :* RUNTIME_ENV_NUMBER | ||
+ | </div> | ||
+ | * ''operator'': declares the relation between the actual value of the looked up attribute ''category'' and the ''value'' expressed in the Requirement. | ||
+ | It can assume one of the following values: | ||
+ | <div style="border: 1px dashed #2F6FAB; background-color: #F9F9F9; color: black; padding:0.5em; margin-top:5px; margin-bottom:5px; font-family: monospace; font-style: normal; font-size-adjust: none;"> | ||
+ | :* eq (Equal) | ||
+ | :* le (Less or Equal) | ||
+ | :* ge (Greater or Equal) | ||
+ | :* gt (Greater than) | ||
+ | :* lt (Less than) | ||
+ | :* exist (can be also used in terms of "contains") | ||
+ | :* ne (Not Equal) | ||
+ | </div> | ||
− | + | * ''requirement'': one of the attribute and/or child elements defined for the selected category in the gHN profile | |
− | + | * ''value'': the value of the selected attribute defined for the category in the GHN profile | |
− | + | Therefore, a gHN requirement is an expression evaluated in this form: | |
+ | ''<category/requirement operator value>'' | ||
− | * | + | * A simple '''example''': |
− | : . | + | <div style="border: 1px dashed #2F6FAB; background-color: #F9F9F9; color: black; padding:0.5em; margin-top:5px; margin-bottom:5px; font-family: monospace; font-style: normal; font-size-adjust: none;"> |
− | : . | + | <source lang="xml" enclose="none" line title="PlanRequest.xml"> |
− | + | <GHNRequirements> | |
− | + | <Requirement category="OS" operator="exist" value="Linux" requirement=""/> | |
− | + | <Requirement category="PROCESSOR_NUM" operator="ge" value="2" requirement=""/> | |
+ | </GHNRequirements> | ||
+ | </source> | ||
+ | </div> | ||
− | The | + | The example above means: "This package can be deployed on a gHN running on a Linux Operating System (Line 2) (it requires that the value of OS in the GHN profile '''contains''' the string Linux) ''and'' having at least 2 processors (Line 3)". '''Note''': in both cases the requirement attribute is not relevant. |
− | + | * '''Example'''. Accessing the run time environment variables: | |
− | + | <div style="border: 1px dashed #2F6FAB; background-color: #F9F9F9; color: black; padding:0.5em; margin-top:5px; margin-bottom:5px; font-family: monospace; font-style: normal; font-size-adjust: none;"> | |
− | + | <source lang="xml" enclose="none" line > | |
− | * '' | + | <GHNRequirements> |
− | + | <Requirement category="RUNTIME_ENV_STRING" requirement="ANT_HOME" operator="eq" value="/usr/share/ant" /> | |
− | : | + | <Requirement category="RUNTIME_ENV_STRING" requirement="GLOBUS_OPTIONS" operator="exist" value="" /> |
− | : | + | </GHNRequirements> |
− | : | + | </source> |
− | : | + | </div> |
− | : | + | |
− | : | + | |
− | + | ||
− | + | ||
− | + | The former block (Line 2) checks that the environment contains the key ''ANT_HOME'' and that its value is equal to ''/usr/share/ant'' while the latter (Line 3) simply checks that the environment contains the key ''GLOBUS_OPTIONS'' regardless its value. | |
− | '' | + | |
− | + | * '''Putting them together a clarifying example''': | |
− | < | + | <div style="border: 1px dashed #2F6FAB; background-color: #F9F9F9; color: black; padding:0.5em; margin-top:5px; margin-bottom:5px; font-family: monospace; font-style: normal; font-size-adjust: none;"> |
+ | <source lang="xml" enclose="none" line > | ||
<GHNRequirements> | <GHNRequirements> | ||
− | < | + | <Requirement category="RUNTIME_ENV_STRING" requirement="Java" operator="exist" value="1.5" /> |
− | < | + | <Requirement category="RUNTIME_ENV_STRING" requirement="gCore-version" operator="eq" value="1.0.1" /> |
+ | <Requirement category="RUNTIME_ENV_STRING" requirement="CATALINA_HOME" operator="exist" value="" /> | ||
+ | <Requirement category="SITE_DOMAIN" requirement="" operator="exist" value="research-infrastructures.eu" /> | ||
+ | <Requirement category="OS" requirement="" operator="exist" value="Linux" /> | ||
+ | <Requirement category="OS" requirement="" operator="eq" value="i386" /> | ||
</GHNRequirements> | </GHNRequirements> | ||
− | </ | + | </source> |
+ | </div> | ||
+ | Here a concrete example where the user statically claims that its service to run needs: | ||
+ | * A jdk having version 1.5.* (note the exist operator) | ||
+ | * An installed gCore having version 1.0.1 | ||
+ | * That apache tomcat is installed on the machine (it is enough to check the CATALINA_HOME environment variable is defined) | ||
+ | * The ghn must run in the *.research-infrastructures.eu domain | ||
+ | * The operating system must be Linux* | ||
+ | * The platform must be i386 | ||
+ | |||
+ | * '''Example'''. Custom queries: | ||
+ | To give freedom to customize the access to specific paths in the resources a CUSTOM_REQUIREMENT category has been introduced. The example below is a sample: | ||
+ | |||
+ | <div style="border: 1px dashed #2F6FAB; background-color: #F9F9F9; color: black; padding:0.5em; margin-top:5px; margin-bottom:5px; font-family: monospace; font-style: normal; font-size-adjust: none;"> | ||
+ | <source lang="xml" enclose="none" > | ||
+ | <Requirement category="CUSTOM_REQUIREMENT" operator="exist" value="/GHNDescription/Architecture[@PlatformType = 'i386']" requirement="" /> | ||
+ | </source> | ||
+ | </div> | ||
+ | |||
+ | The same result can be obtained by the query: | ||
+ | <div style="border: 1px dashed #2F6FAB; background-color: #F9F9F9; color: black; padding:0.5em; margin-top:5px; margin-bottom:5px; font-family: monospace; font-style: normal; font-size-adjust: none;"> | ||
+ | <source lang="xml" enclose="none" > | ||
+ | <Requirement category="PLATFORM" operator="eq" value="i386" requirement=""/> | ||
+ | </source> | ||
+ | </div> | ||
− | |||
GHNRequiremnts can be also used when a package depends on a software that cannot be dynamically deployed. In this case, such a software has to be | GHNRequiremnts can be also used when a package depends on a software that cannot be dynamically deployed. In this case, such a software has to be | ||
Line 411: | Line 468: | ||
=== Package-specific sections === | === Package-specific sections === | ||
+ | Depending on the type of the package, there are some specific elements to report on the package profile. | ||
==== MainPackage ==== | ==== MainPackage ==== | ||
---- | ---- | ||
+ | |||
+ | A MainPackage is a package than once deployed it generates an instance of a gCube Service. | ||
+ | |||
For convention the main package name have to be in the form: | For convention the main package name have to be in the form: | ||
'''''ServiceName''-service''' | '''''ServiceName''-service''' | ||
Example: | Example: | ||
− | + | <source lang=xml> | |
<Packages> | <Packages> | ||
<Main deployable="true"> | <Main deployable="true"> | ||
<Name>Deployer-service</Name> | <Name>Deployer-service</Name> | ||
<Version>1.0.0</Version> | <Version>1.0.0</Version> | ||
+ | <MavenCoordinates> | ||
+ | [...] | ||
+ | </MavenCoordinates> | ||
<Mandatory level="GHN"/> | <Mandatory level="GHN"/> | ||
<Shareable level="VO"/> | <Shareable level="VO"/> | ||
Line 428: | Line 492: | ||
<Requirement category="Site" requirement="string" value="java1.5" operator="ge"/> | <Requirement category="Site" requirement="string" value="java1.5" operator="ge"/> | ||
</GHNRequirements> | </GHNRequirements> | ||
− | |||
− | |||
− | |||
<GARArchive>org.gcube.common.vremanagement.deployer.gar</GARArchive> | <GARArchive>org.gcube.common.vremanagement.deployer.gar</GARArchive> | ||
<PortType> | <PortType> | ||
<Name>gcube/common/vremanagement/Deployer</Name> | <Name>gcube/common/vremanagement/Deployer</Name> | ||
<Security/> | <Security/> | ||
− | |||
− | |||
</PortType> | </PortType> | ||
</Main> | </Main> | ||
</Packages> | </Packages> | ||
− | + | </source> | |
===== GARArchive ===== | ===== GARArchive ===== | ||
The full path of the GAR file. The path must start from the package folder. | The full path of the GAR file. The path must start from the package folder. | ||
Line 454: | Line 513: | ||
The declaration in the profile must be: | The declaration in the profile must be: | ||
+ | <source lang=xml> | ||
<GARArchive>archive/org.gcube.searchservice.resultsetservice.gar</GARArchive> | <GARArchive>archive/org.gcube.searchservice.resultsetservice.gar</GARArchive> | ||
+ | </source> | ||
===== PortType ===== | ===== PortType ===== | ||
Line 460: | Line 521: | ||
===== Name ===== | ===== Name ===== | ||
− | The value of the name attribute in the <service> element in the service's WSDD file. | + | The value of the name attribute in the ''<service>'' element in the service's WSDD file. |
==== Software ==== | ==== Software ==== | ||
− | A Software package is a deployable library or | + | A Software package is a deployable library or any third party package that can be dynamically deployed. |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
+ | Here is an example of a software declared of type=library (meaning that its files are copied in the $GLOBUS_LOCATION folder) and using installation and reboot scripts: | ||
+ | <source lang=xml> | ||
+ | <?xml version="1.0" encoding="UTF-8"?> | ||
+ | <Resource xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> | ||
+ | <ID></ID> | ||
+ | <Type>Service</Type> | ||
+ | <Profile> | ||
+ | <Description>eXistDB</Description> | ||
+ | <Class>ExternalSoftware</Class> | ||
+ | <Name>exist</Name> | ||
+ | <Version>1.2.6</Version> | ||
+ | <Packages> | ||
+ | <Software> | ||
+ | <Description>eXist XML Database</Description> | ||
+ | <Name>exist</Name> | ||
+ | <Version>1.2.6</Version> | ||
+ | <MultiVersion value="true"/> | ||
+ | <Mandatory level="VO"/> | ||
+ | <Shareable level="VO"/> | ||
+ | <InstallScripts> | ||
+ | <File>install.sh</File> | ||
+ | </InstallScripts> | ||
+ | <RebootScripts> | ||
+ | <File>reboot.sh</File> | ||
+ | </RebootScripts> | ||
+ | <Type>library</Type> | ||
+ | <Files> | ||
+ | <File>commons-collections-3.1.jar</File> | ||
+ | <File>commons-pool-1.4.jar</File> | ||
+ | <File>excalibur-cli-1.0.jar</File> | ||
+ | <File>exist.jar</File> | ||
+ | <File>exist-optional.jar</File> | ||
+ | <File>javax.servlet-1.4.jar</File> | ||
+ | <File>jEdit-syntax.jar</File> | ||
+ | <File>jgroups-all.jar</File> | ||
+ | <File>jline-0_9_5.jar</File> | ||
+ | <File>jta.jar</File> | ||
+ | <File>quartz-1.6.0.jar</File> | ||
+ | <File>stax-api-1.0.1.jar</File> | ||
+ | <File>sunxacml.jar</File> | ||
+ | <File>xmldb.jar</File> | ||
+ | <File>xmlrpc-client-3.1.1.jar</File> | ||
+ | <File>xmlrpc-common-3.1.1.jar</File> | ||
+ | <File>xmlrpc-server-3.1.1.jar</File> | ||
+ | <!--File>xmlrpc-1.2-patched.jar</File--> | ||
+ | <File>conf.xml</File> | ||
+ | <File>catalog.xml</File> | ||
+ | </Files> | ||
+ | </Software> | ||
+ | </Packages> | ||
+ | </Profile> | ||
+ | </Resource> | ||
+ | </source> | ||
===== Files ===== | ===== Files ===== | ||
− | The relative path (starting from software archive root directory) and the name of the library's files in the software archive. | + | The relative path (starting from software archive root directory) and the name of the library's files shipped in the software archive. |
Latest revision as of 17:12, 11 July 2013
Contents
Preliminary definitions
gCube resources and profiles
A gCube Resource is anything whose related information can be gathered, stored, monitored, and disseminated in order to provide the valuable amount of knowledge needed during the creation and management of a VRE as well as to operate an entire gCube infrastructure. In order to be appropriately managed and discovered, a gCube resource has to be described by creating a profile document compliant with its XML schema. The following resources have been identified:
- gHN (XSD)
- Service (XSD)
- Running Instance (XSD)
- External Running Instance (XSD)
- VRE (XSD)
- Collection (XSD)
- Metadata Collection (XSD)
- gLite resource (XSD)
Such resources can be combined or created at VRE creation time in order to set up a new Virtual Research Environment.
The gHN resource
A gCube Hosting Node (shortly, a gHN) is the resource modelling a node of an infrastructure able to host gCube Running Instances.
The gHN resource is built by collecting and grouping both the configuration and runtime information on the node. The profile of the gHN is composed by two classes of information:
- static information, i.e. information that does not change once the gHN is started
- dynamic information, i.e. information that changes during the gHN lifetime
At the top level, there are four main sections in the gHN profile:
- Infrastructure, reporting the name of the infrastructure to which the gHN is joined to
- GHNDescription, a GLUE compliant section describing the hardware characteristics of the node
- Site, reporting information about the site to which the gHN belongs to
- DeployedPackages, reporting the list of gCube software packages actually deployed on the gHN
[TBC]
The Service resource
Usually, a Service is defined as a software system that delivers functionalities. In gCube, a Service is a not-empty set of related Packages (connected through dependencies) forming an unique logical entity. A Package is the smallest installable unit of software that can be deployed on a gHN (e.g. a JAR o a GAR archive). Packages are the way in which the software needed to set up a VRE has to prepared in order to be used and stored in the system. Once the service components have been developed, they must be described by compiling the service profile.
Package types
Concretely, a Package is a “piece of software” that can be deployed on a gHN. A Package can be:
- a MainPackage, representing a package that once deployed produces a WSRF Service (a service able to manage stateful resources following the WS-Resource patterns);
- a Software, a software library (typically composed by one or more JAR archives) offering functionality for interacting with Service or a third party software distributed with the service that can be dynamically deployed;
About how to define a package, see the Packages section.
Composition
The set of Packages forming a Service is composed by:
- one and only one MainPackage representing the gCore compliant Web-Service
- an arbitrary number of other Packages of different types logically related (even if not used) to the MainPackage
The "main" part of a Service is, of course, the MainPackage from which the related Running Instance resource is generated. The other packages can be:
- helper modules developed and used by the MainPackage i.e stubs
- helper modules developed and distributed with the MainPackage in order to be used by other Services to interact with a Running Instance of the Service. e.g. test-suite
We enforce the use of this convention:
Main Package Name=ServiceName-service
Stubs=ServiceName-stubs
Test suite=ServiceName-test-suite
Example:
if the ServiceName is Deployer, we will use:
Main Package Name=Deployer-service
Stubs=Deployer-stubs
Test suite=Deployer-test-suite
How to behave with library
A library can be profiled in several ways, mainly depending of its source. The following table depicts them:
Package in a Separated Software Archive | Appear as package in Service Profile | |
Stubs library | NO (Packaged with Service) | YES |
Service specific library | NO (Packaged with Service) | YES |
Library not service specific | YES (Any Service Class) | YES |
Service Indipendent (Deployable) | YES (ExternalSoftware Class) | YES |
Service Indipendent (NOT Deployable) | NO (Contained in GAR archive) | NO |
Example of profile for library not service specific
This is a basic template for a library profile:
<Resource> <ID></ID> <Type>Service</Type> <Profile> <Description>....</Description> <Class>... a class name...</Class> <Name>... a library name...</Name> <Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version> … <Packages> <Software> <Description></Description> <Name>... a library name...</Name> <Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version> <MavenCoordinates> <GroupId></GroupId> <ArtifactId></ArtifactId> <Version></Version> </MavenCoordinates> … </Software> </Packages> </Profile> </Resource>
where:
... a class name... has to be replaced with the name of Service Class the library belong to
... a library name... has to be replaced with the name of Library name
\d{1,2}+.\d{1,2}+.\d{1,2} has to be replaced with the actual version of the Library
The following is an instance example of the template:
<Resource> <ID></ID> <Type>Service</Type> <Profile> <Description>....</Description> <Class>Search</Class> <Name>ResultSetLibrary</Name> <Version>1.0.0</Version> <Packages> <Software> <Description>RS Library</Description> <Name>ResultSetLibrary</Name> <Version>1.0.0</Version> <MavenCoordinates> <GroupId>org.gcube.search</GroupId> <ArtifactId>resultsetlibrary</ArtifactId> <Version>1.0.0</Version> </MavenCoordinates> ... </Software> </Packages> </Profile> </Resource>
Example of profile for Service Independent (Deployable) library
This is a basic template for a Service Independent (Deployable) library profile:
<Resource> <ID></ID> <Type>Service</Type> <Profile> <Description></Description> <Class>ExternalSoftware</Class> <Name>... a library name...</Name> <Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version> … <Packages> <Software> <Description></Description> <Name>... a library name...</Name> <Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version> <MavenCoordinates> <GroupId>.. groupID ..</GroupId> <ArtifactId>.. artifactID ..</ArtifactId> <Version>.. version ..</Version> </MavenCoordinates> … </Software> </Packages> </Resource>
where
... a library name... has to be replaced with the name of Library name
\d{1,2}+.\d{1,2}+.\d{1,2} has to be replaced with the actual version of the Library
The following is an instance example of the template:
<Resource> <ID></ID> <Type>Service</Type> <Profile> <Description>Commons HTTP Client library</Description> <Class>ExternalSoftware</Class> <Name>commons-httpclient</Name> <Version>3.0.1</Version> <Packages> <Software deployable="true"> <Description>Commons HTTP Client library</Description> <Name>commons-httpclient</Name> <Version>3.0.1</Version> <MavenCoordinates> <GroupId>org.gcube.externals</GroupId> <ArtifactId>commons-httpclient</ArtifactId> <Version>3.0.1</Version> </MavenCoordinates> ... </Software> </Packages> <SpecificData></SpecificData> </Profile> </Resource>
How to specify dependencies
The dependencies are specified in the pom of the project, in the profile is only specified the set of maven coordinates. The artifact can be found on an internal maven repository (Nexus) or on another trusted maven Repository
How to compile a Service profile
The following example shows the common elements that compose the Service profile. The Package-specific sections are explained apart later.
<Resource xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <ID></ID> <Type>Service</ResourceType> <Scopes> </Scopes> <Profile> <Description> ...a description...</Description> <Class> ... a class name... </Class> <Name>...a service name...</Name> <Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version> <SpecificData/> <Packages> [...] </Packages> </Profile> </Resource>
Common elements
Class
The class of a service is its functional area. It's a free text field that should group packages belonging the same logical functionalities.
Name
The Name is an arbitrary string that uniquely identifies the service within a service class.
Version
The service version must be in the format: \d{1,2}+.\d{1,2}+.\d{1,2}
This version marks a whole gCube distribution and, for the current distribution under development, the version number is fixed to 1.00.00. Future and different distributions will eventually evolve with a different service version.
Dependencies
A gCube service is part of a complex system and it makes use of other services. At VRE definition time, firstly, it is compiled the list of services that satisfy the VRE definition criteria and, then, such a list is completed with the other services that allow the first ones to work properly. Therefore it is needed that a service declares which other services it will need to be available in order to do its work once it is deployed.
Packages section
This element groups an unbounded sequence of Package-derived elements. Each element describes a package that comes with the service. The structure of a Package element includes an initial common part and a package-specific part rooted by an element named as the service type (MainPackage and Software). The only constraint is that one and only one MainPackage element is accepted in the list.
The following example shows the elements of a Package definition common to both types of Package.
<Packages> <Main deployable="true"> <Name>Deployer-service</Name> <Version>1.0.0</Version> <MavenCoordinates> <groupId>org.gcube.vremanagement</groupId> <artifactId>deployer-service</artifactId> <version>1.0.0</version> </MavenCoordinates> <Mandatory level="GHN"/> <Shareable level="VO"/> <GHNRequirements> <Requirement category="Site" requirement="string" value="java1.5" operator="ge"/> </GHNRequirements> <GARArchive>org.gcube.common.vremanagement.deployer.gar</GARArchive> <PortType> <Name>gcube/common/vremanagement/Deployer</Name> <Security/> </PortType> </Main> </Packages>
Name
An arbritrary string that uniquely identifies the package within this service.
Version
The version of the package. It has to be in the format: \d{1,2}+.\d{1,2}+.\d{1,2} (e.g. 1.0.1 or 1.11.0)
Mandatory
If the Mandatory element is declared, it states when the package has to be deployed by default. The value of the attribute level defines at which level the package is mandatory. Accepted values are: NONE, GHN, VO and VRE. For instance, stating that a package is mandatory at VO level means that each time a new VO is created the package MUST be deployed.
If the element is not declared, the package is assumed to be not mandatory at any level by default.
If the Shareable element is declared, it states if the package can be shared across multiple Scopes. The value of the attribute level defines at which level the package is shareable. Accepted values are: NONE, VO and VRE.
If the value is NONE, the package cannot be shared across any scope, i.e. there must be one and only one deployed instance of that package in a scope.
If the element is not declared, the package is assumed to be shareable at any scope level by default.
InstallScripts
This set of scripts are executed before the deployment of the package. They can be used to prepare the environment for the package execution (create a file system structure, install third parties software). The current folder where they are executed is the one where it is places. So, one can navigate the package tree with relative paths starting from the install script folder.
UninstallScripts
This set of scripts are executed after the undeployment of the package. They can be used to clean up the environment. The current folder where they are executed is the one where the package is downloaded and uncompressed.
RebootScripts
This set of scripts are executed before each container startup.
MavenCoordinates
The MavenCoordinates is a set of maven coordinates that defines the artifact realted to the package. The dependencies of the project may be specified in the pom according to maven specifications
A set of coordinates is a declaration of the following elements:
- GroupID
- ArtifactID
- Version
GHNRequirements
A GHNRequirement is a requirement against the node where the package is going to be deployed. These requirements are matched with the gHN profiles in order to find a suitable node that can host the package. A gHN requirement is expressed by:
- category: it identifies the element/attribute of the Profile/GHNDescription section of the gHN profile against which the requirement is expressed.
It can assume one of the following values:
- MEM_RAM_AVAILABLE
- MEM_RAM_SIZE
- MEM_VIRTUAL_AVAILABLE
- MEM_VIRTUAL_SIZE
- HOST
- OS
- DISK_SPACE
- LOAD1MIN
- LOAD5MIN
- LOAD15MIN
- PLATFORM
- PROCESSOR_NUM
- PROCESSOR_BOGOMIPS
- SITE_LOCATION
- SITE_COUNTRY
- SITE_DOMAIN
- CUSTOM_REQUIREMENT
- RUNTIME_ENV_STRING
- RUNTIME_ENV_NUMBER
- operator: declares the relation between the actual value of the looked up attribute category and the value expressed in the Requirement.
It can assume one of the following values:
- eq (Equal)
- le (Less or Equal)
- ge (Greater or Equal)
- gt (Greater than)
- lt (Less than)
- exist (can be also used in terms of "contains")
- ne (Not Equal)
- requirement: one of the attribute and/or child elements defined for the selected category in the gHN profile
- value: the value of the selected attribute defined for the category in the GHN profile
Therefore, a gHN requirement is an expression evaluated in this form: <category/requirement operator value>
- A simple example:
- <GHNRequirements>
- <Requirement category="OS" operator="exist" value="Linux" requirement=""/>
- <Requirement category="PROCESSOR_NUM" operator="ge" value="2" requirement=""/>
- </GHNRequirements>
The example above means: "This package can be deployed on a gHN running on a Linux Operating System (Line 2) (it requires that the value of OS in the GHN profile contains the string Linux) and having at least 2 processors (Line 3)". Note: in both cases the requirement attribute is not relevant.
- Example. Accessing the run time environment variables:
- <GHNRequirements>
- <Requirement category="RUNTIME_ENV_STRING" requirement="ANT_HOME" operator="eq" value="/usr/share/ant" />
- <Requirement category="RUNTIME_ENV_STRING" requirement="GLOBUS_OPTIONS" operator="exist" value="" />
- </GHNRequirements>
The former block (Line 2) checks that the environment contains the key ANT_HOME and that its value is equal to /usr/share/ant while the latter (Line 3) simply checks that the environment contains the key GLOBUS_OPTIONS regardless its value.
- Putting them together a clarifying example:
- <GHNRequirements>
- <Requirement category="RUNTIME_ENV_STRING" requirement="Java" operator="exist" value="1.5" />
- <Requirement category="RUNTIME_ENV_STRING" requirement="gCore-version" operator="eq" value="1.0.1" />
- <Requirement category="RUNTIME_ENV_STRING" requirement="CATALINA_HOME" operator="exist" value="" />
- <Requirement category="SITE_DOMAIN" requirement="" operator="exist" value="research-infrastructures.eu" />
- <Requirement category="OS" requirement="" operator="exist" value="Linux" />
- <Requirement category="OS" requirement="" operator="eq" value="i386" />
- </GHNRequirements>
Here a concrete example where the user statically claims that its service to run needs:
- A jdk having version 1.5.* (note the exist operator)
- An installed gCore having version 1.0.1
- That apache tomcat is installed on the machine (it is enough to check the CATALINA_HOME environment variable is defined)
- The ghn must run in the *.research-infrastructures.eu domain
- The operating system must be Linux*
- The platform must be i386
- Example. Custom queries:
To give freedom to customize the access to specific paths in the resources a CUSTOM_REQUIREMENT category has been introduced. The example below is a sample:
<Requirement category="CUSTOM_REQUIREMENT" operator="exist" value="/GHNDescription/Architecture[@PlatformType = 'i386']" requirement="" />
The same result can be obtained by the query:
<Requirement category="PLATFORM" operator="eq" value="i386" requirement=""/>
GHNRequiremnts can be also used when a package depends on a software that cannot be dynamically deployed. In this case, such a software has to be
- manually installed,
- declared in the gHN profile as a conventional RunTimeEnv/Variable value and,
- reported as GHNRequirement in the package definition.
The list of labels is open and new labels can be defined at any time. So far, the list includes:
- java1.5 - a JVM v1.5 is available
- gLiteSEAccess - the node is configured to access to a Storage Element on a gLite infrastructure
- MySQLdb - a MySQL database is available
- Oracle10g - an Oracle10g database is available
Package-specific sections
Depending on the type of the package, there are some specific elements to report on the package profile.
MainPackage
A MainPackage is a package than once deployed it generates an instance of a gCube Service.
For convention the main package name have to be in the form: ServiceName-service
Example:
<Packages> <Main deployable="true"> <Name>Deployer-service</Name> <Version>1.0.0</Version> <MavenCoordinates> [...] </MavenCoordinates> <Mandatory level="GHN"/> <Shareable level="VO"/> <GHNRequirements> <Requirement category="Site" requirement="string" value="java1.5" operator="ge"/> </GHNRequirements> <GARArchive>org.gcube.common.vremanagement.deployer.gar</GARArchive> <PortType> <Name>gcube/common/vremanagement/Deployer</Name> <Security/> </PortType> </Main> </Packages>
GARArchive
The full path of the GAR file. The path must start from the package folder.
Example: If the structure of the directory is like this
|--Deployer-service \--archive \--org.gcube.common.vremanagement.deployer.gar
The declaration in the profile must be:
<GARArchive>archive/org.gcube.searchservice.resultsetservice.gar</GARArchive>
PortType
A PortType is a WSDL interface generated by the deployment of the MainPackage's GAR. Each of them is declared in the Deployment Descriptor file (WSDD) with a <service> element.
Name
The value of the name attribute in the <service> element in the service's WSDD file.
Software
A Software package is a deployable library or any third party package that can be dynamically deployed.
Here is an example of a software declared of type=library (meaning that its files are copied in the $GLOBUS_LOCATION folder) and using installation and reboot scripts:
<?xml version="1.0" encoding="UTF-8"?> <Resource xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <ID></ID> <Type>Service</Type> <Profile> <Description>eXistDB</Description> <Class>ExternalSoftware</Class> <Name>exist</Name> <Version>1.2.6</Version> <Packages> <Software> <Description>eXist XML Database</Description> <Name>exist</Name> <Version>1.2.6</Version> <MultiVersion value="true"/> <Mandatory level="VO"/> <Shareable level="VO"/> <InstallScripts> <File>install.sh</File> </InstallScripts> <RebootScripts> <File>reboot.sh</File> </RebootScripts> <Type>library</Type> <Files> <File>commons-collections-3.1.jar</File> <File>commons-pool-1.4.jar</File> <File>excalibur-cli-1.0.jar</File> <File>exist.jar</File> <File>exist-optional.jar</File> <File>javax.servlet-1.4.jar</File> <File>jEdit-syntax.jar</File> <File>jgroups-all.jar</File> <File>jline-0_9_5.jar</File> <File>jta.jar</File> <File>quartz-1.6.0.jar</File> <File>stax-api-1.0.1.jar</File> <File>sunxacml.jar</File> <File>xmldb.jar</File> <File>xmlrpc-client-3.1.1.jar</File> <File>xmlrpc-common-3.1.1.jar</File> <File>xmlrpc-server-3.1.1.jar</File> <!--File>xmlrpc-1.2-patched.jar</File--> <File>conf.xml</File> <File>catalog.xml</File> </Files> </Software> </Packages> </Profile> </Resource>
Files
The relative path (starting from software archive root directory) and the name of the library's files shipped in the software archive.