Chapter 1 Overview of N1 Service Provisioning System Plug-Ins

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

• Overview of Sun N1 Service Provisioning System

• Overview of the Solution Development Environment

• Introduction to Plug-Ins

• Parts of a Plug-In

• Plug-In Packaging

Overview of Sun N1 Service Provisioning System

The N1 SPS product 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:

• Common framework to build service provisioning automation – The provisioning system provides an XML schema and a Java API that enable you to model your applications and services and automate the deployment of these objects.

• Maintains an audit log of changes over time – The provisioning system Run History and Where Installed plans enable you to track the status of deployments in your network, as well as the target hosts of those deployments.

• Compares the current state of target hosts with their expected state – You can use the provisioning system to capture snapshots of the target hosts on your network, and run a variety of comparisons through the browser interface or the cmp command.

• Simulates a change to identify configuration problems – The preflight run option enables you to simulate your deployment plans. If you encounter deployment issues, you can safely troubleshoot and resolve these problems without adversely affecting your target hosts.

• Implements a set of rules to govern automation execution – In your provisioning plans, you can specify individual hosts or host sets to provision with the platform and limitToHostSet attributes to the component element.

• Notifies system administrators of problems and actions– You can use the <sendCustomEvent> step to generate a particular message each time a component is deployed or a plan is run. This step can be used in conjunction with the notification rules module to send an email any time this step is encountered on a particular host.

• Automatically manages version control– As you modify and check-in your components and plans, the provisioning system software versions the new component or plan, while preserving older versions.

The N1 SPS software 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 SPS basic concepts and terminology, see Chapter 1, Sun N1 Service Provisioning System 5.2 Overview, in Sun N1 Service Provisioning System 5.2 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 resources, such as source files and directories, that a component needs

   5. Defining specific tasks, or controls, 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, defined in the <hostSet> element, 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 sps-compSDK.jar file on your development system

   2. Developing a model for your plug-in, identifying how you plan to identify the various objects that make up the application that you want to deploy with your plug-in

   3. Developing the XML schema that identifies the application objects as components and resources, and defines the necessary variables for your application

   4. Creating an XML plan to perform specific deployment tasks, such as installing, uninstalling, and starting and stopping the application

   5. Including execNative steps in your components and plans to run native OS commands with your plug-in

   6. Including execJava steps in your components and plans to execute Java code when you deploy your plug-in

      ---

      Note –

      If you need to use Java to develop your plug-in, use the NetBeans product. For more information, see http://www.netbeans.org/.

      ---

   7. Enabling plug-in users to browse and create components from a remote system with the BrowserNode and ComponentExporter Java classes

   8. Developing a custom user interface for your plug-in to enable other SPS users to access your plug-in through the SPS browser user interface

   9. Packaging the components, plans, resources, and plug-in definition files, as a JAR file for delivery to other N1 SPS users

Introduction to Plug-Ins

In general usage, the term plug-in refers to loadable applications that provide additional functionality to your web browser. In the N1 SPS environment, a plug-in differs only slightly in concept from the general usage. A plug-in for the N1 SPS 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 BEA WebLogic 8.0, 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. This data is included in the following parts of the plug-in.

• Plug-in descriptor file - This file describes the contents of the plug-in. The plug-in descriptor contains metadata 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.

• Java class files - The Java-based component classes and the execJava class are included in the plug-in. These files enable you to include exporting and browsing functionality in your plug-in, and to include steps that run Java code.

• Component definitions - The components and component types that you create for your plug-in are stored as XML files as a part of your plug-in. These files define the objects and resources that your plug-in will deploy.

XML Schemas

In the N1 SPS 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:

• plugin.xsd – Plug-in schema used to describe the parts of the plug-in through the plug-in descriptor file

• pluginUI.xsd – Plug-in user interface schema used to define an interface to the plug-in within the N1 SPS browser interface

• component.xsd – Component schema used to define components and component types

• plan.xsd – Plan schema used to define execution plans

• planCompShared.xsd – Schema that contains elements that are common to plans and components

This document includes examples that illustrate the XML schemas. For complete reference information about the elements and attributes used in the XML schemas, see Sun N1 Service Provisioning System 5.2 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:

• Components

• Component types

• Folders

• Host searches

• Host sets

• Host types

• Plans

• System services

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

• Resources

• Java code to enable browse and export functionality for your plug-in

• execJava steps to run Java code as a part of your plug-in solution

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 development IDE, such as Sun Studio^TM or NetBeans, 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-ins can be imported into the N1 SPS environment through both the browser interface or the command-line interface. When you import a plug-in, the plug-in descriptor file and the contents of the plug-in are validated. Any errors with the import operation are highlighted in the browser interface.

For more information about how to import a plug-in, see Sun N1 Service Provisioning System 5.2 System Administration Guide.

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-Ins

To uninstall a plug-in, you must perform the following tasks.

• Uninstall all the components of the plug-in

• Uninstall all the system services that are installed on target hosts as a part of the plug-in deployment

• Delete from the Master Server component repository all component instances, including hidden instances, that were created from the plug-in component types

For more information about how to uninstall a plug-in, see Sun N1 Service Provisioning System 5.2 System Administration Guide.

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.

Versioning Considerations

The N1 SPS software enables you to capture versions of plans and components. When you modify the plans and components in your plug-in and check these objects in to your N1 SPS environment, the objects are assigned a new version number. As a part of your plug-in deployments, you can choose to use the most current version of the plug-in plans and components, or previous versions.

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.

To avoid naming conflicts, a plug-in cannot locate versioned objects, such as components and plans, into directories that were created by other plug-ins.

The following objects are not versioned.

• Component types

• System services

• Host types

• Host searches

• Host sets

If a plug-in attempts to create a non-versioned object that matches a same typed and named existing object, the plug-in name is prepended to the name of the object to avoid naming conflicts.

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 Display in the Browser Interface

The N1 SPS provisioning software controls the display order of plug-ins in the browser interface. You cannot control the display order of your plug-in in the plug-in definition.

Plug-In readme.txt File

You should provide a readme.txt file with your plug-in. The plug-in readme.txt file is intended as the holding place for instructions on configuring the system for a plug-in, as well as any copyright notice that applies to the 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.