N1 Grid Service Provisioning System 5.0 Plan and Component Developer's Guide

Chapter 1 Plan and Component Development Concepts

This chapter describes plan and component concepts that relate to the N1 Grid Service Provisioning System software, henceforth referred to as the provisioning system.

This chapter covers the following topics:

Component Concepts

A component is a logical grouping of resources that defines an application. It also includes a set of instructions that specifies how to handle the resources that make up the application. A component might be a collection of the following:

Files and directories
Autonomous archives, such as J2EE^TM Enterprise Archives (EAR) or COM components
Complete applications, such as the BEA WebLogic Server
Operating system-level updates, such as patches or service packs
Pointers to other components

You can use the provisioning system to manage applications in a data center. Before you can manage your applications with this product, you must first model them as components. The provisioning system enables you to do the following:

Create application models that include a carefully defined group of software resources for each application, along with information about how the application should be installed, configured, and analyzed
Store components in a component repository that employs version control so you can retrieve any previous version of a component
Make components available to plans that perform data center operations in a step-by-step manner to take advantage of the knowledge that is embedded in each component
Compare components to one another as well as to installations of software

The provisioning system supports two basic types of components:

Simple components. A simple component contains a single resource, but cannot contain references to other components.
Composite components. A composite component contains only references to other components, both simple and composite, but cannot contain any resources.

A composite component contains references to components. The referenced components are referred to as contained components (child components), and the referencing component is referred to as the container component (parent component).

A composite component declares whether each of its contained components is to be installed as a top-level component or a nested component. If a contained component is installed as top-level, it can be used by any component just as if it had been directly installed by a plan. However, if a contained component is installed as nested, its services are only available to the container component. A nested contained component defines a finer-grained unit of functionality required by the container component, but is not otherwise useful to other components. Whereas a top-level contained component defines services that will be used by the container component, it can also be used by other components.

Note –

Composite components contain only references to other components, not to the components themselves. The referenced components are other existing components that are updated and managed separately from the container component. A component can be referenced by any number of composite components. A component's name is not affected by whether it is referenced by other composite components. Name conflicts are resolved using paths.

The provisioning system manages the physical resources associated with a component. It also includes a number of predefined components that you can use directly, or as samples for constructing other components.

A component also includes procedures. A procedure is a program that is contained in a component that controls deployment of the component. Typical component procedures are defined for installation, uninstallation, and capturing snapshots. Other procedures can be defined in the control block. A control is a series of instructions in a component that can be used to manage the deployed application. For example, controls might be used to start or shut down an application. A component might include instructions that test for dependencies on other components or that verify that a particular process is running.

A component can also declare substitution variables that can be used within the component itself or for any resources that the component contains. These variables can be used as placeholders for values that will be substituted when the plan is run.

Modeling a Component

The provisioning system offers great flexibility when you model components. The application that you are modeling determines which of the following approaches to use:

Fully automated modeling. You can check in a component from a gold server or from a source code control system. When the check-in completes, the provisioning system has automatically generated a component, from which you can run installation, configuration, and comparison procedures.

Use this approach when you model applications for which a plug-in is already defined and imported. You can use built-in component types or imported component types to automatically model the most common resources that make up application components. The component type templates include built-in procedures for basic operations, such as installations. This means that you can perform basic operations on common types of components without having to write a plan.

For descriptions of the built-in component types, see Chapter 3, Built-in Component Types. For a list of component types delivered through plug-ins, see the N1 Grid Service Provisioning System 5.0 Plug-In Collection at http://docs.sun.com/db/coll/1223.1.
Extending built-in component types with XML authoring. You can customize an automatically generated component by editing its XML directly on the Advanced Edit page of the browser interface. Another way to customize the component is to download a file that contains the XML to your system and edit it with an XML-schema-validating editor, such as Turbo XML.

When you edit the XML, you can do the following:
- Customize the component by supplying additional variables
- Add calls to extended control procedures, such as starting and stopping IIS or Microsoft Windows services
Authoring component models in XML. You can create a component on your own by using an XML editor and by referring to the component schema descriptions in Chapter 2, Shared Schema Used by Components and Simple Plans, in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide, Chapter 3, Component Schema, in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide, and Chapter 4, Plan Schema, in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.

Before you can use the component, you must check the component's XML file and its resources in to the repository.
Authoring component models by using the browser interface. You can use the browser interface to create a component. Saving it automatically builds the component. Then, you can install the component by doing one of the following:
- Running the installation procedure, which installs the component on a single host or a host set
- Writing a plan to install the component on one or more hosts or host sets
  
  For more information about plans, see Chapter 4, Plans.
Before you can use the component, you must first check it in to the repository.

When you check in a component, it is built, and particular versions of the component resources are assigned to it. The build also assigns a version number to the component and ensures that that version of the component is always associated with particular versions of the component's resources.

Component Characteristics

A component is distinguished by many characteristics. The following list describes some of the more common component characteristics:

Path. A location in the folder in which to store components. Use folders to organize components in a hierarchical manner.
Component name. The name of the component.
Component type name. The name of the component type that is associated with a component. See Component Type Concepts.

The provisioning system includes some component types that support generic models, such as files and directories. Additional component types can be added to the system by importing plug-ins that are specific to application domains, such as Microsoft Windows and WebLogic.
Version number. The version number of the component. Each time a component is modified, the version number is incremented.

At check-in time, you choose how to increment the version number. You can increment by the major number, which is to the left of the decimal point, or by the minor number, which is to the right of the decimal point.
Platform. The operating system on which this component can be installed.
Check-in date. The date and time when the component was checked in.
Check-in user. The user ID of the person who checked in the component. This attribute is useful when you want to audit provisioning system processes.
Label. An optional string that you can use to categorize or group components.
Category. An optional object that you can use to filter the component list. After you create a category object, you can subsequently use it to group components.
Description. An optional string that describes the component. Use this attribute to provide meaningful information about the component.
Source. The resource that has been included in this component. The source can be a single file resource or a list of other components.
Component variables. A list of variables and their values (name-value pairs) that are required to deploy a component resource. See Component Variables.
Procedures. A set of instructions that specifies what to do with the resources and variables.
Hidden. A characteristic that indicates whether you can view the component in a list of components. By default, components are not hidden.

You might want to shorten a component list by hiding components that are older versions or that are not being managed. The shortened list would include any non-hidden components, which might be those that you are currently managing. Hidden components do not appear in lists unless you request to view them.

Component Procedures

A component procedure (or procedure) is a program that is contained in and manages a component. A component procedure might install, uninstall, or control a component. A procedure is created when you build the component.

You can run a procedure in these ways:

Directly from the Details page of a component, where a plan is generated and then executed
By writing a plan that calls the procedure, then running the plan
By calling the procedure from other components and plans

Your component can have several procedures. For example, a component might include a control procedure to start or stop the application that it models.

When you create a component that extends from a component type, the component inherits the procedures that are defined by the component type.

When you create a composite component, it inherits default installation and uninstallation procedures. Usually, components inherit procedures from the associated component type.

Component Inheritance

Component inheritance is the means by which a component obtains attributes and behavior from another component. When you create a component, it inherits any variables, snapshots, and procedures from the associated component type.

The use of inheritance makes the component model powerful and flexible. For example, suppose that you have a thousand components that are based on the IIS Application component type. You want to add more functionality to these components. By adding the functionality to the IIS Application component type, each of the thousand components that extend it will inherit the new functionality.

Component Variables

Components support the use of variables, which are user-definable containers that store values and are used during deployment.

A component variable is used to make parts of a component accessible and configurable by objects that are external to the component. For example, a component might have a variable named installPath that is overridden on a per-host basis. This variable defines where to install each component.

The value of a component variable can be a reference to another component variable, which includes variables that are defined by the component's container. When a nested component is added to a container component, the browser interface verifies that the referenced variable is defined in the container. If the variable is not defined in the container component, the browser interface automatically adds the referenced variable to the list of the container's variables.

For example, simple components typically define their installPath variable to have the value of the container component's installPath variable. In this example, the syntax of the referenced variable is :[container:installPath]. For more information about variable substitution, see Chapter 6, Configuration Generation.

Component variables are evaluated and assigned a value when the component is deployed. Component variables are used to specify information (such as host names, IP addresses, and paths) that is required to implement a deployment.

Variable Settings

Variable settings are collections of variable values that can be used to override the default values of one or more component variables. Based on the variable settings that you use, you can specify different values for component variables. You specify which variable settings to use when you run a plan.

For example, a component is deployed to different environments, such as a production environment and a development environment. If the defined component variables are set up to recognize the differences between environments, you can use variable settings to configure the component for each environment. For example, use one set to configure the production environment and another set to configure the component for the development environment.

Variable Overrides

Variable overrides enable you to override variable default values for composite components. They cannot be used for simple components.

When a component contains other components, called child components, variable settings only affect the top-level parent component. All child components use the default values for their variables. A child component can obtain variable values from its parent component in these two ways:

The container (parent) component “pushes” variable values to the contained (child) components. To override the default values for child components, set the variable overrides when you create a component that contains child components. Each referenced component has a set of variable overrides that you can use.
The contained (child) components “pull” variable values from the container (parent) component. One or more of the contained component's variable values are defined based on the value of a variable in the container component. The contained component uses the variable substitution syntax :[container:varname] in the default value of its variables.

Steps

Steps are simple instructions that can be part of both plans and components.

For information about steps, see Step Overview.

Component Type Concepts

A component type is a component that has been designed as an encapsulation of behavior for reuse by other components. A component type usually represents behavior that is specific to a particular type of application. For example, an Enterprise JavaBeans^TM (EJB^TM) component type might contain generic procedures that can be used to deploy and undeploy an EJB archive to and from an application server. When a component extends from a component type, it automatically inherits the behavior that is defined in that component type.

Components are usually associated with a component type. If you select untyped from the browser interface, your component will not extend from any other component type. The provisioning system includes some built-in component types. See Chapter 3, Built-in Component Types.

The files, directories, and other tree structures that are referred to by a simple component are managed as a discrete unit in a component.

For example, an IIS application, which the provisioning system would manage as referenced resources, might include the following:

Directory and its contents
IIS web site settings
COM+ application
Microsoft Windows registry settings

Some of the resources that are referenced by components, such as files and directories, can be copied from a gold server or another data source. Others, such as IIS web site settings or Microsoft Windows registry entries, must be extracted from a data source in a special way so that they can be treated as independent, manageable entities.

With its built-in component types, the provisioning system can recognize the most common source items that are used for Java^TM 2 Platform, Enterprise Edition (J2EE platform) and Microsoft Windows applications. These component types can accurately extract data for use as a component resource, store the component resource in a repository, and correctly install the resources in the specified location.

System Services Concepts

System services are components that are automatically deployed to all applicable hosts when the hosts are prepared. System services define utility controls and resources that can be used by other components for component installation and management.

System services enrich the set of services that are available during plan execution.

Plan Concepts

A plan, also called an execution plan, is a sequence of instructions that is used to manage one or more components on the specified hosts. For example, an execution plan might install three components and initiate the “startup” control of another component.

A plan can also include a sequence of other plans, which enables common instruction sequences to be written as plans and then shared among plans. For example, a plan might instruct the provisioning system to install three components and initiate the startup control for another.

The provisioning system provides an in-memory representation of the objects expressed by the XML schema. This representation also defines a process for the validation, persistence, and version control for those objects.

When the provisioning system executes a plan, substitution variables that are declared by a component are replaced by actual values. The provisioning system also supports a notification feature that can send email in response to events that are related to plan execution.

Plan Types

The provisioning system supports two types of plans:

Simple plans. A simple plan contains a collection of simple steps, but cannot call other plans.
Composite plans. A composite plan contains only other plans, called subplans.

The XML schema enforces the distinction between the two types of plans. Thus, you can use a top-level plan that contains calls to other subplans, or a simple plan that contains simple steps but no calls to subplans.

This distinction is important because the steps in a simple plan can only execute on the same set of target hosts, whereas the steps of a composite plan can execute on different sets of target hosts. A composite plan can use one set of target hosts for each simple plan that it contains.

Step Overview

Steps are simple instructions that can be part of both plans and components. The provisioning system supports the following kinds of steps:

Steps that can only be called from within a component. Such steps can only be called from install blocks or from uninstall blocks. See Install-Only Steps for Components in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide and Uninstall-Only Steps for Components in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.
Steps that can only be called from a plan. Such steps can only be called from composite plans or from simple plans. See Plan-Only Steps for Composite Plans in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide and Plan-Only Steps for Simple Plans in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.
Steps that can be called from either a plan or from a component. See Chapter 2, Shared Schema Used by Components and Simple Plans, in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.

Component References

A number of steps can reference components in the following situations:

Components that have yet to be installed can use the <install> step.

Steps that refer to components that have yet to be installed only need to specify the name of the component and an optional version.
Components that have already been installed can use the following steps:
- <uninstall>
- <call>
- <checkDependency>
- <createDependency>
- <addSnapshot>
Steps that refer to an installed component must specify the installPath attribute because the same component can be installed more than once on the same server.

Example 1–1 Using Component References

Assume that the “Apache” component is installed on a host with the following attribute settings.

Component Instance	installPath	version	installDate
A	`/opt`	1.3	6/1/01 6:00 p.m.
B	`/usr/local`	1.4	6/1/01 5:00 p.m.
C	`/opt`	1.2	6/2/01 5:00 p.m.
D	`/usr/local/bin`	1.4	6/3/01 5:00 p.m.
E	`/export`	1.1	6/4/01 5:00 p.m.

The following shows which installed component is referenced when values for various combinations of the installPath and version attributes are supplied.

installPath	version	versionOp	Result	Explanation
None	None	None	E	The most recently installed component on the target host is used, regardless of the values of version and installPath.
`/opt`	None	None	C	The most recently installed component in the named install path is used regardless of the value of version.
`/usr/bin`	None	None	ERROR	No component is installed in the specified path.
None	1.4	`=`	D	The most recently installed component that has the specified version is chosen, regardless of the value of installPath.
None	1.5	Any	ERROR	No component is installed with the specified version.
`/usr/local`	1.4	`=`, `>=`	B	The component that matches the specified installPath and version attribute values is chosen.
`/usr/local`	1.2	`=`	ERROR	No such version is installed at the specified install path.
`/usr/local`	1.2	`>`, `>=`	B	The values for installPath, version, and versionOp match.
`/opt`	3	Any	ERROR	If two or more components are installed in the same path and they have the same name, the most recently installed component effectively overwrites any other components that have been installed earlier. Components that have been installed at an earlier time cannot be accessed, even if directly specified.

Session Variable Concepts

A session is initiated when you log in to the browser interface or use the CLI. A session persists until you log out or inactivity causes the session to expire. Logically, a session represents the authenticated credentials of a particular user. A session is used to identify the user throughout a series of related requests without reauthentication.

Each session can have a set of session variables that are initialized from the database when you log in. You can use session variables to preserve session-related information, such as user authentication and other credentials. You can modify the session variables in the current session without affecting the session variables that are saved in the database. If you make changes to session variables and their values, you can save them to the database. When saved, all of the variables and their values are saved and are available in future sessions. You can make session variable references when you execute plans and comparisons.

If you have initiated more than one session and try to save the session variables at the same time, only the first session to save the variables succeeds. After the first session successfully saves the session variables, the other sessions are prevented from saving changes to their session variables. To save those changes, do the following:

Log out of all sessions.
Log in again to restart a session.

The new set of session variables and values are retrieved from the database based on the last successful save.
Make the changes you want to the session variables.
Save the changes to the session variables.

Session variables exist in a global namespace, which means that the session variable names you declare are available to all user sessions. For example, suppose that you define a session variable named passwd. Any plan that requests the passwd session variable is referring to the same variable. Session variable names are not scoped to current plans, components, blocks, or hosts. Thus, you must ensure that your session variable names are unique. For example, you might use your initials and birthday month and day, or some other identifier, to make your session variables unique.

Secure Session Variables

A session variable is made up of a name, value, and the secure flag. The session variable name has the same limits as a host-type variable name. The secure flag is a Boolean value that describes whether the value should be securely stored.

When a value is securely stored, the secure flag is set to true. The value of the session variable appears as *** and is encrypted when the variable is saved. When this value is used during plan execution, the value of this variable is obscured from plan history output, as well. Use this secure flag when the variable value is sensitive data, such as passwords. By default, session variables are created with the secure flag set to true.

If any secure variables are saved to the database, you must type your password, which is used as the encryption key. If you supply the wrong password, you are prompted for the password again.

If the password you enter is not recognized, an error is issued. This might occur if the system administrator has changed your password or your login configuration. You are given the following options:

Reencrypt the session variables. Supply your user name, the password with which the session variables have been encrypted, and your new password.
Flush the session variables. Delete all of the session variables that you declared. Supply your user name and your current password.

Use this option if you forgot the password with which the session variables were encrypted.