N1 Grid Service Provisioning System 5.0 Plug-in Development Guide

Chapter 1 Overview of N1 Grid Service Provisioning System Plug-Ins

This chapter provides a brief introduction to the N1 Grid Service Provisioning System environment and explains how plug-ins fit into that environment. The chapter contains the following information:

Overview of N1 Grid Service Provisioning System

The N1 Grid Service Provisioning System is an object oriented, XML-based, distributed environment to solve enterprise system configuration, service provisioning, and application deployment needs. The provisioning system provides an extensible framework and environment that at a minimum provides the following functionality:

The N1 Grid Service Provisioning System implements a distributed environment in which object-oriented components are authored in XML scripts and orchestrated to follow execution plans for distribution, provisioning, and installation needs. For more information about N1 Grid Service Provisioning System basic concepts and terminology, see Chapter 1, N1 Grid Service Provisioning System 5.0 Overview, in N1 Grid Service Provisioning System 5.0 Installation Guide.

Overview of the Solution Development Environment

You can use the provisioning system to build system configuration, service provisioning, and application deployment solutions. At a very high level, you follow this simple process:

  1. Build a set of components. This step might involve any of the following sub-tasks:

    1. Defining application-specific component types

    2. Naming each component

    3. Assigning a component type to each component

    4. Identifying any source files and directories that a component needs

    5. Defining specific tasks for that component

  2. Create a plan to direct the deployment of the components. Each plan includes the following information:

    1. A list of components

    2. A sequence in which the components are to run

    3. A list of any variables that the components need

    4. A set of target hosts to which the components should be deployed

  3. Create a plug-in that enables others to use the components and plans that you developed for a given platform or application. This task involves four main sub-tasks:

    1. Installing the core plug-in development files

    2. Using the XML plug-in definition schema to provide an interface for the users

    3. Using the Java-based APIs to provide component browsers and exporters, and to define custom execJava steps.

    4. Packaging the components, plans, resources, plug-in definition files, and APIs for delivery to other N1 Grid Service Provisioning System users

Introduction to Plug-Ins

In general usage, plug-in applications are programs that can easily be installed and used as part of your web browser. A plug-in application is recognized automatically by the browser and its function is integrated into the main HTML file that is being presented. Web browser plug-in applications generally play sound or motion video or perform some other functions.

In the N1 Grid Service Provisioning System environment, a plug-in differs only slightly in concept from the general usage. A plug-in for the N1 Grid Service Provisioning System product is a packaged solution that extends the provisioning capability of the product for a specific platform, application, or environment. For example, you might create a plug-in solution for a specific application, such as Oracle 8i, or for some feature of an operating system, such as Solaris Zones.

A plug–in includes all the relevant data needed to support a new custom application. The contents of the plug–in are described in the plug–in descriptor file. This file is located in a standard place within the plug–in packaging structure.

The plug-in descriptor contains meta-data about the plug-in including name, description, vendor, version number, previous version, and dependencies. In addition, the descriptor may contain a pointer to a readme.txt file. The descriptor also contains instructions for creating components, plans, folders, host types, host sets, host searches, resources, component types, and system services. The descriptor may optionally define a library of server-side plug-in code and a set of GUI extensions for the plug-in.

Objects defined in the plug-in are loaded in the order in which they are defined within the descriptor file. Objects defined in the plug-in may only reference objects defined earlier in the plug-in, or in a plug-in on which this plug-in directly depends. This dependency must be declared in the plug-in descriptor.

XML Schemas

In the N1 Grid Service Provisioning System environment, plans, components, and other parts of the solution are defined through XML. You can use several XML schemas to define your plug-in solution. The following schemas are provided in the docs/xml directory of the product media:

This document includes examples that illustrate the XML schemas. For complete reference information about the elements and attributes used in the XML schemas, see N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.

Parts of a Plug-In

A plug-in solution includes all the relevant data needed to support a new custom application. This data includes first-class provisioning system objects:

In addition, the plug-in can also include auxiliary objects for use by the system, such as the following objects:

Plug-In Packaging

A plug-in is packaged as a Java Archive (JAR) file. The contents and instructions for interpreting the contents of the JAR file are contained in an optionally signed plugin-descriptor.xml file located in the top-level directory of the JAR file. The syntax of the plug-in descriptor is specified using XML Schema as per the May 2, 2001 W3C Recommendation (http://www.w3.org/TR/2001/xmlschema-0-20010502/). The schema can be used in conjunction with a validating parser to determine the syntactical validity of a plug-in descriptor file.

Recommended Naming

To avoid potential conflicts, you should use a Java package naming convention for plug-ins (com.companyname.productname, for example, com.sun.solaris). Any objects that can be in a folder should be placed in a folder directory structure that mirrors the plug-in name, such as /com/sun/solaris. The plug-in JAR file name should use the convention pluginname_version.jar, for example com.sun.solaris_1.1.jar.

Installation Considerations

To install a plug-in, service provisioning administrators load the plug-in JAR file.

Plug-In Upgrade Considerations

To upgrade from an existing version of a plug-in to a newer version of a plug-in, you provide a patch JAR file that contains only the contents needed for the patch . For example, if you only changed two component types between version 1.2 and version 1.3, then your upgrade patch would contain only those new component type XML files. Define your patch so that it can be applied in series to upgrade multiple versions . For example, to upgrade from version 1.0 to version 1.2, a user would first apply the upgrade from 1.0 to 1.1, then apply the upgrade from version 1.1 to version 1.2. Update patches are strictly additive with respect to the previously loaded version of the plug-in. You can also create a patch that would upgrade from a specific existing version (for example, 1.0) to a specific newer version (for example, 1.3). However, you cannot create a patch to upgrade from any arbitrary version to a higher version.

Uninstalling Plug-In Versions

You cannot uninstall an individual patch of a plug-in, and you cannot delete objects created by previous versions of a plug-in. To remove this content, you would need to uninstall the current version of the plug-in and reinstall the older version of the plug-in. Alternatively, you could create an anti-patch that would install the old plug-in version's code while creating new versions of the plug-in defined objects.

Component Versions and Dependencies

Objects that are defined by a plug-in are loaded at installation time in the order in which they are defined in the plug-in descriptor file. These objects may only reference other objects that were defined either earlier in the plug-in or in a plug-in on which the defining plug-in directly depends. Any dependencies must be declared in the plug-in descriptor file. If a plug-in attempts to create a versioned object that matches a same typed and named object existing in the system, a new version of the object is created. The minor version of this object is incremented unless the plug-in definition explicitly defines the object as requiring a major version increment. If a plug-in attempts to create a non-versioned object that matches a same typed and named existing object, the plug-in object replaces the previous definition of the object. In both the versioned and unversioned cases, the existing object must have been created by a prior version of the same plug-in that is attempting to create the new version of the object.

Certificates

If the plug-in descriptor file is signed for one version of a plug-in, then the file must be signed for any subsequent versions of that plug-in. Use the standard jarsigner tool to sign the plug-in descriptor file. If the file is signed, the signature will be verified against the public certificate when the plug-in is installed. When upgrading a plug-in, the certificate used to sign the newer version is matched against the certificate used to sign the existing version in the system. The upgrade will not succeed if certificates have expired between plug-in versions.

You should sign all entries in the plug-in JAR (not just the plug-in descriptor file) with the same certificate. Only a single certificate may be attached to each entry.

Security Considerations

A plug-in does not include facilities for defining groups or permissions. This is because permission management depends highly on the environment into which the plug-in is loaded, and cannot be effectively modeled for all environments.

The administrator who adds the plug-in must decide what permissions are appropriate. The general expectation is that plug-ins are designed to be used by everyone. However, certain clients may wish to limit the use of a plug-in to a certain group. Plug-ins may also have certain folders that are meant to have different execution permissions.

Plug-In readme.txt File

You can provide a readme.txt file with your plug-in, if needed. The plug-in readme.txt file is intended as the holding place for instructions on configuring the system for a plug-in. In general, the readme.txt file should document the permissions, session variables, and other instance-specific settings required for the plug-in to function. Specifically, the readme.txt should contain instructions for setting permissions on plug-in created folders, as well as enumerating expected session variables, their descriptions and encryption methods.