Installable Unit Deployment Descriptor Specification Version 1.0

The purpose of this specification is to define the schema of an XML document describing the characteristics of an installable unit (IU) of software that are relevant for its deployment, configuration and maintenance. The XML schema is referred to as the Installable Unit Deployment Descriptor or IUDD schema.

IUDDs are intended to describe the aggregation of installable units at all levels of the software stack, including middleware products aggregated together into a platform; and user solutions composed of application-level artifacts which run on such a platform. The XML schema is flexible enough to support the definition of atomic units of software (Smallest Installable Units) as well as complex, multi-platform, heterogeneous solutions.

A solution is any combination of products, components or application artifacts addressing a particular user requirement. This includes what would traditionally be referred to as a product offering (e.g. a database product), as well as a solution offering (e.g. a business integration platform comprising multiple integrated products), or a user application (e.g. a set of application artifacts like J2EE applications and database definitions). All the software constituents of a solution can be represented by a single IUDD as a hierarchy of installable unit aggregates. The top-level aggregation is the root installable unit. In addition to the installable units that comprise a solution, the IUDD also describes the logical topology of targets onto which the solution can be deployed.

Status of this document

By publishing this document, W3C acknowledges that International Business Machines, Inc. and Novell, Inc. have made a formal submission to W3C for discussion. Publication of this document by W3C indicates no endorsement of its content by W3C, nor that W3C has, is, or will be allocating any resources to the issues addressed by it. This document is not the product of a chartered W3C group, but is published as potential input to the W3C Process. Publication of acknowledged Member Submissions at the W3C site is one of the benefits of W3C Membership. Please consult the requirements associated with Member Submissions of section 3.3 of the W3C Patent Policy. Please consult the complete list of acknowledged W3C Member Submissions.

1Document Control

1.1 Contributing Authors

2 Introduction

The purpose of this specification is to define the schema of an XML document describing the characteristics of an installable unit (IU) of software that are relevant for its deployment, configuration and maintenance. The XML schema is referred to as the Installable Unit Deployment Descriptor or IUDD schema.

IUDDs are intended to describe the aggregation of installable units at all levels of the software stack, including middleware products aggregated together into a platform; and user solutions composed of application-level artifacts which run on such a platform. The XML schema is flexible enough to support the definition of atomic units of software (Smallest Installable Units) as well as complex solutions.

A solution is any combination of products, components or application artifacts addressing a particular user requirement. This includes what would traditionally be referred to as a product offering (e.g. a database product), as well as a solution offering (e.g. a business integration platform comprising multiple integrated products), or a user application (e.g. a set of application artifacts like J2EE applications and database definitions). All the software constituents of a solution can be represented by a single IUDD as a hierarchy of installable unit aggregates. The top-level aggregation is the root installable unit. In addition to the installable units that comprise a solution, the IUDD also describes the logical topology of targets onto which the solution can be deployed.

2.1 Purpose

The IUDD provides a unique identification of each installable unit and it supports a declarative specification of dependencies that each IU may have on its hosting environment and on other units of software. This information can be leveraged by common tools and services to reduce the human interactions required for

· checking that dependencies are satisfied before creating or updating a software instance;

· checking the integrity of relationships that an IU instance is expected to maintain with other IU instances during its life cycle.

2.2 Scope

· Container Installable Unit (CIU) – an aggregated IU that is deployed entirely into a single target hosting environment;

This document does not define how the contents of a root installable unit, including the descriptor, are physically packaged together. This is defined in a separate specification [IUPACK].

2.3 Audience

This document is intended as a technical specification for people who require an in-depth understanding of the installable unit deployment descriptor. This includes developers of the IUDDs themselves, and developers of the associated tooling and applications for constructing and deploying IUDDs. This document is not intended as an introduction to the concepts of solution deployment or as a tutorial for developers.

2.4 Notational Convention

The key words “MUST,” “MUST NOT,” “REQUIRED,” “SHALL,” “SHALL NOT,” “SHOULD,” “SHOULD NOT,” “RECOMMENDED,” “MAY,” and “OPTIONAL” are to be interpreted as described in [RFC2119].

3 Installable Unit Deployment Descriptor Overview

The installable unit deployment descriptor (IUDD) is a means for describing the components of a solution, and for providing instructions on how to deploy and configure that solution. The IUDD is a reusable asset that can be deployed onto many different physical topologies, and can be aggregated into larger solutions. It establishes knowledge of the relationships and dependencies between components of the solution, which can then be used for its lifecycle management.

Installable Units (IU) are the key abstraction governing the structure of the IUDD. Within the IUDD, installable units are aggregated in a tree-like hierarchy whose leaf nodes are Smallest Installable Units (SIU) and Configuration Units (CU).

An SIU is limited in scope to describing a unit of software that is targeted to and is entirely contained by the single hosting environment where it is deployed. Analogously, a CU defines the configuration applying to a single resource (target) in the topology.

Container Installable Units (CIU) aggregate SIUs, CUs and other CIUs, again for deployment onto a single hosting environment.

Solution Modules (SM) aggregate SIUs, CUs, CIUs and other solution modules. IUs aggregated in a solution module are typically deployed into multiple hosting environments, possibly located on multiple physical computers.

The IUDD defines a single-rooted installable unit – the root IU – that aggregates one or more installable units of the above types as its base content and may define one or more selectable IUs (features). The root IU represents a “unit of manufacture”. The following elements of information are specifically associated to the root IU:

· File definitions (these are used to link references to packaged files that are made in various IUDD elements with the files physically bundled in a package and described in a separate package media descriptor; see [IUPACK]).

Other key elements of a RootIU that are also part of any other IU definition are:

Figure 1 shows the structure of the IUDD, effectively the structure of the associated root IU definition.

Information in the IUDD is independent from the package format, which is covered by a separate specification [IUPACK]. The latter describes how to construct a package including the IUDD and all the other files that may need to be accessed in order to deploy the root IU.

The independence of the IUDD and packaging specifications allows an IU to be composed flexibly, and to make packaging decisions independently from the logical definition of the installable units.

3.1 Deployment architectural pattern

Figure 2 shows the fundamental architectural pattern for solution deployment. An installable unit is the fundamental building block or component from which products or solutions are composed. An installable unit package consists of a descriptor, which describes the content of the installable unit, and one or more artifacts that are to be installed. The installable unit is installed into a hosting environment, which is a container that can accept the artifacts in the installable unit.

This architectural pattern is reusable at all levels of the software stack, from the operating system, through the middleware, up to application artifacts such as EJBs and database tables.

3.2 Roles

The overall process for developing and deploying a solution is illustrated in Figure 4. A solution is developed by application developers and/or product developers; it is then packaged as one or more root installable units, at which point the requirements on the target topology is defined; and distributed to deployers. The deployer makes installation-specific decisions about how the installable unit is to be configured, and the solution depoyment tooling assists in mapping the logical target topology defined in the IUDD onto the physical topology. The solution components (installable units) are then distributed and installed.

3.3 XML schema files

The IUDD schema is implemented by eight schema files. Types defined in each file are identified by a specific prefix, as indicated in the following:

· iudd.xsd (prefix: iudd) – See Appendix E.
This is the main schema file. rootIU is the single global element defined in iudd.xsd. This element defines the whole content of an IUDD XML document. This file contains definitions for the elements of a root IU and for the installable unit aggregates.

· siu.xsd (prefix: siu) – See Appendix F.
This file contains definitions of the SIU and CU types

· base.xsd (prefix: base) – See Appendix G.
This file contains definitions of basic types, like identity, variables and check types, as well as types that are re-used by several derived types.

· version.xsd (prefix: vsn) – See Appendix H.
This file defines normalized string formats for version information.

· iudd.relationships (prefix: rel) – See Appendix I.
This file contains an enumeration of relationships defined between resources.

· resourceTypes.xsd (prefix: rtype) – See Appendix J.
This file contains enumerations of resource types.

· signatures.xsd (prefix: sigt) – See Appendix K.
This file contains types defining signatures associated to an IU.

Artifacts associated to an installable unit (see Section 3.1 above) also have an associated XML descriptor. However, artifacts are referenced from within the IUDD through an identifier of the corresponding file. Since they are not defined inline within the IUDD, the XML schema for artifacts are independent from the IUDD schema files. See Section 14 and Section 15 for a proposed artifact schema.

3.4 UML representation of the RootIU type

The class diagram in the following page illustrates the composition relationships of the RootIU class with other types defined in the IUDD schema. The following sections provide an overview of types represented in the diagram. This provides an introduction to the detailed XML schema definitions of those types that are described later in this document.

3.4.1 IUorFixDefinition

IUorFixDefinition is the type providing identity information for the root IU. Different elements of this type are applicable depending on the installable unit type (base IU, full or incremental update and temporary fix).

3.4.2 Variables

Variables is an aggregate containing the variable definitions associated with the root IU.

3.4.3 ConditionedIU

ConditionedIU is the generic type describing any contained IU defined within the root IU. Two compositions of this type are defined by a root IU: one is for the base content (installableUnit) while the other is for features (selectableContent).

IUs that can appear in an IU aggregate have an associated condition. The condition is a boolean variable expression. When the condition is false, the IU is not selected for install. IUs defined within the aggregate may have siblings. A sequence number may be associated to the IU to specify the order in which the IU should be processed with respect to its siblings.

3.4.4 RootIU.rootInfo

The rootInfo element defines characteristics of the root IU instance, such as the schema version on which it is based and the size of all files associated to artifacts defined in this root IU.

3.4.5 RootIU.features

A root IU may define zero or more features. Either each feature represents a top-level IUs defined inline within the RootIU or it is a reference to a feature in a referenced, separately packaged IU. In both cases, the IU referred to by the feature definition MUST be defined within the root IU selectable content composite.

3.4.6 RootIU.groups

The root IU may define zero or more groups of features (installation groups). Each group represents a combination of installable units that could be chosen for a given configuration or role, e.g. minimal versus typical; administrator versus developer versus client.

3.4.7 RootIU.topology

The root IU topology is a composite of one or more target definitions. A target can be a hosting environment onto which one or more IUs are to be deployed, or it can be a generic resource that is needed for the proper functioning of the solution. Ordinary targets pre-exist the solution deployment. Deployed targets are defined in the topology to represent resources that are created by instantiating an installable unit.

3.4.8 RootIU.customCheckDefinitions

The customCheckDefinitions element includes definitions of check artifacts. Each artifact is a descriptor of actions that need to be performed on a target to establish if the latter satisfies some given requirements. Some of the actions defined in a check artifact may specify the execution of custom code. Multiple checks defined in different IUs may need to reuse the same custom check artifact. For this reason, the identification of check artifacts is factored out in the root IU.

3.4.9 RootIU.requisites

In addition to IUs that are part of the aggregate, the root IU may define requisite IUs, i.e. bundled packaged IUs, which may be installed on a target to satisfy a software requirement.

3.4.10 RootIU.files

The files element of the root IU is a composite of File definitions. Each File definition includes a file identifier. Any element within a root IU that is associated to a physical file declares that association by means of a reference to the corresponding file identifier. Examples of elements associated to a physical file are Referenced IUs and bundled requisite IUs. Actions specified within install artifacts (see Section 9.4) may also contain references to physical files that need to be bundled with the root IU. These files need to be defined in the files element.

4 Software Change Management

The following data-flow diagram provides a model for the process involved in a software change. This model is provided as an illustrative example and alternative processes MAY be supported by an implementation of an install runtime. The process is a sequence of five logical activities: Environment Checks, Input, Dependency Check, Change and Register. These activities interact with the target hosting environment, and the installable unit database. The hosting environment (e.g. a configured operating system image) is the actual destination of the software being installed. The installable unit database is the repository holding information about the installable unit configuration for a set of hosting environments within a given scope (for example those on a single machine, or those within a complete administrative domain). The user provides input, in this process, either interactively or via a response file, and that input drives the activity of a software installer program.

Figure 5: Model of the software change management process

The rectangles at the bottom of Figure 5 represent entities defined in this specification:

The rectangle on the left represents the IU descriptor, conforming to the IUDD XML descriptor defined by this specification.

The rectangles on the right side represent artifacts associated to an SIU or to a CU. An SIU or CU may define multiple artifacts, each one associated to a different type of change (operation). Each artifact includes one artifact descriptor defining actions – such as the ones for creating or removing files on an operating system environment. Action definitions in the artifact descriptor are interpreted on the IU’s hosting environment to implement the change, and may reference files that need to be available when the actions are performed.

The following list provides a description of the five logical activities illustrated in Figure 5:

Environment Checks.

Gather information about the current environment (e.g. the presence of installed software on the target system). This activity generally executes before entering into the interactive stage of an attended installation or other change management operation, because the information may be used by an installer to determine the additional input that the user should provide during an interactive install. The environment checks should not be affected by user input: any variable contained in the specification of a check, if any, should have a well-defined initial value.
Input.

Obtain replacement values for parameters defined in a package, either through interactive user input or from a response file.
Requirements Checks.

Ensure that all requirements stated in the IU descriptor for a given type of change are satisfied before starting the change.
Change.

Perform the requested change operation on the installable unit, such as Create, Configure or Delete. The full list of change management operations, and the corresponding states of the installable unit, are described in section 4.2.
Register.

Persist information about the installable unit. For a Create operation, this information may include the identity of the newly created IU instance, its target, its relationships to other installable units, and the values of variables used in its installation.

4.1 Hosting Environments

Software deployment has been traditionally designed and implemented as a process by which a software package (artifact) is installed on the running operating system image on one or more physical computers. In general, deployment of a software component (e.g. a database client) on one target needs to be coordinated with deployment of a different software component (e.g. a database server) onto another target.

“Hosting Environment” is a term used to denote the target of a software component with specific characteristics. Therefore, the term “OS hosting environment” is used to denote the hosting environment of traditional software products that are installed on an operating system, while the term “J2EE hosting environment” is used to denote a J2EE application server hosting J2EE applications. Other hosting environment types may be defined, such as RDBMS databases, messaging systems, and other middle-ware.

4.2 Software Life-Cycle Operations

The following state diagram applies to an instance of any installable unit (SIU or aggregate). During its life-cycle an IU instance makes state transitions as a consequence of Change Management (CM) operations being applied to it. A CM operation MAY require an artifact specifying the actions to be executed on the hosting environment.

State diagram of an installable unit instance

Figure 6: State diagram of an installable unit instance.

Error states that result from errors encountered when performing any of the indicated operations are not covered in this specification, and are not shown in the above diagram.

The following sections 4.2.1 to 4.2.10 describe the operations that create an IU instance, apply updates and configuration to that instance and delete the instance when it is no longer needed. The descriptions focus on the meaning of the operation for an SIU. Applying updates to an IU aggregate is discussed in Section 11. Ordering of install, applying to both Create and Update, is defined in Section 12.

4.2.1 Create

The Create operation creates a new instance of an SIU. The Install artifact associated to the SIU, see Section 9.4, defines the actions to be executed on the hosting environment to instantiate the SIU.

The newly created IU instance transitions directly to the Usable state if no InitialConfig artifact is specified and there are no sibling configuration units defined in the same aggregate. Otherwise, the instance enters the Created state and an InitialConfig operation is needed to bring the instance to the Usable state.

On some hosting environments, the operation MAY be used to overwrite an existing instance of the SIU. The end result SHOULD be the same that would be obtained by performing the Create operation after applying the Delete operation to the existing instance.

An SIU may define a new base, an IU update or a temporary fix. An update can be full, in which case it is possible to use if for a fresh install; or incremental, in which case it must be applied to an existing instance. The Create operation can only be performed for an SIU defining a new base or a full update. An SIU defining a temporary fix or an incremental update can only be applied to an existing instance using the Update operation.

4.2.2 Update

The Update operation updates an existing instance. The SIU defining an update or temporary fix contains a declaration of the version range of a base IU instance onto which it can be applied (update base). The Install artifact associated to the SIU, see Section 9.4, defines the actions to be executed on the hosting environment to update the base instance.

After the update, the version of the updated instance is changed to reflect the version specified by the SIU update.

The updated IU instance transitions directly to the Usable state if no Migrate artifact is specified and there are no sibling configuration units defined in the same aggregate. Otherwise, the instance enters the Updated state and the Migrate operation is needed to bring the instance to the Usable state.

The update may be applied in undo-able mode. In this case, any resources (e.g. files) associated to the instance being updated that are being replaced or modified need to be saved, in order to support the roll-back of the update.

SIU updates and fixes may supersede fixes that are already applied to the instance being updated.

4.2.3 InitialConfig

The InitialConfig operation applies the initial configuration to an instance of the insta

Christine Draper	IBM Autonomic Computing Architecture	cdraper@uk.ibm.com
Marcello Vitaletti	IBM Autonomic Computing Architecture	marcello.vitaletti@it.ibm.com
Randy George	IBM Tivoli Architecture	randyg@us.ibm.com
Julia McCarthy	IBM SWG Componentization Architecture	julia@us.ibm.com
Devin Poolman	Zero G Software	devin.poolman@zerog.com
Tim Miller	Zero G Software	tim.miller@ZeroG.com
Art Middlekauff	InstallShield Software Corp.	artm@installshield.com
Carlos Montero-Luque	Novell	carlos@novell.com