THIS SECTION OF GCUBE DOCUMENTATION IS OBSOLETE. THE NEW VERSION IS UNDER CONSTRUCTION.

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)
Transformation Program (XSD)
CS (XSD)
CSInstance (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

[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 Library, representing a software library (typically a JAR) that can be hosted on a GHN. There are three types of library:
- Shared Library, software library offering functionality of common utility, e.g. an XML parser library or a mathematical support library;
- Stub Library, software library offering functionality for interacting with WSRF Services.
- External Library, a thirdy party library available on the ETICS Repository that can be dynamically deployed.
Software, a thirdy party software distributed with the service that can be dynamically deployed;
ExternalSoftware, a thirdy party software available on the ETICS repository that can be dynamically deployed.

About how to define a package of any type above, see the PackageList section.

Composition

The set of Packages forming a Service is composed by:

one and only one Package of WSRFService type (the main package)
an arbitrary number of other Packages of different type logically related (even if not used) to it.

An exception to this rule is represented by the Software Archive.

The "main" part of a Service is, of course, the WSRFService package from which the related Running Instance resource is generated. The other packages can be:

helper modules developed and used by the WSRFService
thirdy parties software used by the WSRFService
helper modules developed and distributed with the WSRFService in order to be used by other Services to interact with a Running Instance of the Service.

How to specify dependencies

A package, once deployed, can rely on other software to perform its activities. Let's see how to specify these dependencies by distinguishing among:

software developed within this service (this is the case of a stub library, for instance)
→ the software has to be declared as Library and the dependency is specified as package Dependency
software developed and distributed within other DILIGENT services
→ the dependency is specified as package Dependency against a package defined in another Service profile
thirdy party deployable software used only by this service
→ the software has to be declared as Software or Library (it depends on the nature of the software) and the dependency is specified as package Dependency
thirdy party deployable software used by other services
→ the software has to be uploaded in the ETICS repository, the package has to be declared as ExternalSoftware and the dependency is specified as package Dependency
thirdy party software that is not dynamically deployable
→ the software has to be manually installed, the label has to be manually declared in the DHN profile (by the DHN owner) and the dependency is specified as DHN Requirement

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">
        <UniqueID/>
	<Type>Service</ResourceType>
	<Scopes>
	</Scopes>
	<Profile>
                <Description>IS-Registry: validate, register and unregister GCUBE resources to/from the IS. It also publishes Topics for notifications about GCUBE resource events</Description>
                <Class>InformationSystem</Class>
                <Name>IS-Registry</Name>
                <Version>1.0</Version>		
		<Dependencies>
			<Dependency>
				<Class>MetadataManagement</Class>
				<Name>XMLIndexer</Name>
				<Version>1.0</Version>
			</Dependency>
			<Dependency>
				<Class>ContentManagement</Class>
				<Name>StorageManagementService</Name>
				<Version>1.0</Version>
			</Dependency>
			<Dependency>
				<Class>ContentManagement</Class>
				<Name>CollectionManagementService</Name>
				<Version>1.1</Version>
			</Dependency>
		</Dependencies>
		<SpecificData/>
		<PackagesList>
                 [...]
		</PackagesList>
	</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 in the format: x.x.x

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.

PackagesList section

This element groups an unbounded sequence of Package-derived elements. Each element describes a package that belongs 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, Library, Software, ExternalSoftware). The only constraint is that one and only one MainPackage element is accepted in the list.

Common elements

Example

The following example shows the elements of a Package definition common to all types of Package.

<Package>
	<Name>IS-Registry-service</Name>
        <Version>1.0</Version>
        <Mandatory level="VO"/>
	<Shareable level="VO"/>
	<GHNRequirements>
		<Requirement category="Site" requirement="string" value="java1.5" operator="ge"/>
	</GHNRequirements>
	<Dependencies>
		<Dependency>
			<Service>
				<Class>InformationSystem</Class>
				<Name>IS-Registry</Name>
			</Service>
			<Package>IS-Registry-stubs</Package>
			<Version>1.0</Version>
			<Scope level="GHN"/>
			<Optional>false</Optional>
		</Dependency>
	</Dependencies>
	<InstallScripts>
		<File>...</File>
	</InstallScripts>
	<UninstallScripts>
		<File>...</File>
	</UninstallScripts>
	<RebootScripts>
		<File>...</File>
	</RebootScripts>		
	<ConfigurationFiles>
		<File>....</File>
	</ConfigurationFiles>

	[package specific elements]		
</Package>

PackageName

An arbritrary string that uniquely identifies the package within this service.

Version

The version of the package. It has to be in the form of X.Y.

Shareable

It states if the package can be shared across multiple DLs (true) or if it is DL-Specific (false).

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 is downloaded and uncompressed.

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.

Dependencies

The dependencies of the package are a list of other packages (defined somewhere in the current or in other profiles) that allow the package to properly work. It is important to point out that also the dependencies against the packages declared in the current profile has to be specified (like the one against its own stub library).

A dependency is a declaration of the following elements:

Service
PackageName
Version (optional)
Scope level

..equals to "GHN" means that the package must be co-deployed on the same GHN

..equals to "VRE" means that the package must be deployed on a GHN and visible in the same VRE (typically used for dependencies against MainPackages)

..equals to "VO" means that the package must be deployed on a GHN and visible in the same VO (typically used for dependencies against MainPackages)

Optional

a false value means that the fulfilment of dependency is mandatory for a successful deployment of the package that declares the dependency

The following example defines a dependency that requires that the stub classes of the IS-registry service have to be co-deployed with the package that includes such a dependency declaration:

<Dependencies>
	<Dependency>
		<Service>
			<Class>InformationSystem</Class>
			<Name>IS-Registry</Name>
		</Service>
		<Package>IS-Registry-stubs</Package>
		<Version>1.0</Version>
		<Scope level="GHN"/>
		<Optional>false</Optional>
	</Dependency>
</Dependencies>

Finally, if the dependency is against a software stored in the ETICS repository, an ExternalSoftware package has to be defined in the current profile and the dependency has to be defined as any other one.

GHNRequirements

A GHNRequirement is a requirement against the node where the package is 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 composed by:

category

It is a name of an element in the DHN profile

operator

it is one of the following values:

eq (equal)
ne (not equal)
lt (less than)
le (less or equal than)
gt (greater than)
ge (greater or equal than)
requirement

It is one of the attributes/child elements defined for the selected category in the DHN profile

value

it is the value of the selected attribute defined for the category in the DHN profile

At the end of the story, a requirement is an expression evaluated in this form: <category/requirement operator value>

Example:

<GHNRequirements>
	<Req category="RunTimeEnv" operator="eq" requirement="Variable" value="java1.5"/>
	<Req category="OperatingSystem" operator="eq" requirement="Name" value="Linux"/>
</GHNRequirements>

The example above means: "I can be deployed on a DHN where there is a RunTimeEnv/Variable element equals to java 1.5 and an OperatingSystem[@Name] element equals to Linux"

A typical usage of GHNRequiremnts is when a package depends on a software that cannot be dynamically deployed. In this case, the software has to be manually installed and declared in the GHN profile as RunTimeEnv/Variable and then it has to be reported as DHN requirement in the package definition. A list of conventional labels that identify the software (and more in general, the GHN capabilities) has to be fixed:

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

Of course, the list above can be enriched at any time.

ConfigurationFiles

...

Package-specific sections

MainPackage

Example:

GARArchive

BuildFile

DeploymentOptions

ArchitecturalPattern

This element declares the architectural pattern adopted by the WSRF service.

ServiceEquivalenceFunctions element: Fix the service equivalence

This element allows to define functions to use at runtime to understand when two Running Instances of the service are equivalents from a specific function point of view. They can be considered are a sort of criteria to find service's replicas. Each function defined here must have a corrispondent section in the Running Instance profile that gives the values to the formal parameter defined in the function. So far, the following fuction are used in the infrastructure:

match, used by the Active Planner service to discriminate among two Running Instances of the same service

WSRFEntry

A WSRFEntry is a WSDL interface generated by the deployment of the WSRFService's GAR. Each of them is declared in the Deployment Descriptor file (WSDD) with a <service> element.

EntryName

The value of the name attribute in the <service> element in the service's WSDD file.

Security

This section includes information for a correct management of the service's security at Collective Layer level. If the service is not configured for security it can be omitted.

Example

<Security>
	<SecurityDescriptor>
		<securityConfig xmlns="http://www.globus.org">
			<authz value="VOAuthorizationPDP:org.diligentproject.dvos.authorization.handler.VOAuthorizationPDP"/>
			<method name="addCredentialsRenewalOperation">
				<auth-method>
					<GSISecureConversation>
			 	   		<protection-level>
		         				<privacy/>
		      				</protection-level>
					</GSISecureConversation> 
				</auth-method>
				<run-as> 
					<service-identity/>
				</run-as>
			</method>
			<auth-method>
				<GSISecureConversation/>
			</auth-method>
			<run-as> 
				<service-identity/>
			</run-as>
		</securityConfig>
	</SecurityDescriptor>
	<LogicalOperations>
		<Operation id="{http://www.diligentproject.org/namespaces/dvos/credentialRenewal}manageCredentialsTask" 
			name="manageCredentialsTask"  
			description="This operation allows to set credentials renewal task on the credentials renewal service">
			<Role name="CredentialsTaskManager"/>
		</Operation>
	</LogicalOperations>
	<ServiceRoles>
		<Role name="CredentialsManager"/>
	</ServiceRoles>								
</Security>

SecurityDescriptor

The content of the security descriptor file for the WSRF entry.,

LogicalOperations

This section defines logical operations required to access Running Instances of this service. Those used in the configuration file of the authorization handler for the service. For each operation also the list of roles to which the operation should be permitted in the VO must be given. This allows the DLManagement, after the deployment of a new Running Instance., to correclty set auhtorizations to access the RI just created.

ServiceRoles

The set of roles Running Instances of this service have to hold in order to succesfully act in the VO. As identities used by the Running Instance have to be selected before the deployment, the DLManagement is in charge to assign these roles to the identity selected for the new Running Instance.

Library

The Library packages are usually JAR archives. The Collective Layer copies such libraries in the $GLOBUS_LOCATION/lib folder. There are 3 types of Library:

shared library
stub library
external library

Shared Library

Example

<Library>
	<Type>shared</Type>
	<Parameters/>
	<LibraryFile>ip/org_diligentproject_informationservice_disip.jar</LibraryFile>
</Library>

Type

Fixed: "shared"

Parameters

The parameters grouped in this section allow to statically configure the library. The section can be leave empty if there is no need to configure the package in this way.

LibraryFile

The path and the name of the library's file in the service archive.

Stub Library

Example:

<Library>
	<Type>stub</Type>
	<IsStubOf>
		<PackageName>DIS-IC_Service</PackageName>
		<Version>1.0</Version>
		<Service>
			<Class>InformationSystem</Class>
			<Name>DIS-IC</Name>
		</Service>
	</IsStubOf>
	<Parameters/>
	<LibraryFile>bin/org_diligentproject_informationservice_disic_stubs.jar</LibraryFile>
</Library>

Type

Fixed: "stub"

IsStubOf

This element declares of which WSRFService package the library is stub of.

Parameters

The parameters grouped in this section allow to statically configure the library. The section can be leave empty if there is no need to configure the package in this way.

LibraryFile

The path and the name of the library's file in the service archive.

External Library

Example:

<Library>
	<Type>external</Type>
	<ExternalLibraryFile>		
		<DownloadFrom>http://grids17.eng.it/engrepository/commons-io/1.2.0/noarch/commons-io-1.2.tar.gz</DownloadFrom>
		<Description>Apache Common IO v1.2</Description>
	</ExternalLibraryFile>					
</Library>

Type

Fixed: "external"

ExternalLibraryFile

It includes the URL on the ETICS Repository (or in another network accessible location) and a human readable description. The file MUST be in the .tar.gz compressed format.

The .jar files included in the archive will be added to the ones available on the JVM where the local DHN services are executed.

Software

A Software package is a deployable thirdy party package uploaded with the service.

Example:

<Software>
	<FileList>
		<File>setup.exe</File>
		<File>data.cab</File>
	</FileList>
	<Description>my software</Description>
</Software>

FileList

The list of files that compose the software. It is validated at registration time and if one of the declared files is not included in the Service Archive, the registration fails.

Descritpion

A human description of the software (can be left empty).

ExternalSoftware

An ExternalSoftware package is a deployable thirdy party package used by this service but not uploaded with the Service on the infrastructure. One can decide to do not include a software as part of a Service because:

it is supposed that the software is of general interest and it can be used also by other Services
the size of the software is quite huge (more than few Megabytes) and it is better to do not upload it in a service invocation.

These software must be uploaded in the ETICS Repository and referred here.

Example:

<ExternalSoftware>
	<DownloadFrom>http://grids17.eng.it/engrepository/..</DownloadFrom>
	<Description>Aggregator Framework for Java WS Core 4.0.2</Description>
</ExternalSoftware>

DownloadFrom

A valid location on the ETICS Repository

Descritpion

A human readable description of the software referred by the ID (can be left empty).

The external software is downloaded on the DHN and the related installation scripts are executed in the same folder where it is stored.

--Manuele.simi 04:50, 8 July 2008 (EEST)

Profile Specification

Contents

Preliminary definitions

gCube resources and profiles

The GHN resource

The Service resource

Package types

Composition

How to specify dependencies

How to compile a Service profile

Common elements

Class

Name

Version

Dependencies

PackagesList section

Common elements

Example

PackageName

Version

Shareable

InstallScripts

UninstallScripts

RebootScripts

Dependencies

GHNRequirements

ConfigurationFiles

Package-specific sections

MainPackage

GARArchive

BuildFile

DeploymentOptions

ArchitecturalPattern

ServiceEquivalenceFunctions element: Fix the service equivalence

WSRFEntry

EntryName

Security

Example

SecurityDescriptor

LogicalOperations

ServiceRoles

Library

Shared Library

Stub Library

External Library

Software

ExternalSoftware

Navigation menu

Search