Sun N1 Service Provisioning System 5.2 プラグイン開発ガイド

コンポーネントとプランの作成

企業全体で特定のソリューションを効果的に再現するには、ソリューションの共通の部分を特定するコンポーネント、リソース、およびプランを定義する必要があります。また、これらを配備するプロセスを定義する必要があります。プラン、コンポーネント、およびそれらの管理方法については、『Sun N1 Service Provisioning System 5.2 プランとコンポーネントの開発者ガイド』を参照してください。

コンポーネントの構築

ソリューション開発の重要な部分はコンポーネントの作成です。Sun N1 Service Provisioning System 環境では、コンポーネントは配備可能なオブジェクトです。コンポーネントに含めることができるオブジェクトの例を次に示します。

ファイルとディレクトリのコレクション
JAR ファイル、EAR ファイルなどのアーカイブファイル
必要なリソースすべてを含む、完全なアプリケーション
構成ファイルやマニュアルなどの特定のアプリケーションリソース

N1 SPS ソフトウェアでは、コンポーネントのバージョンを取得できます。プラグインのコンポーネントを変更し、これらのコンポーネントを N1 SPS 環境にチェックインすると、コンポーネントに新しいバージョン番号が割り当てられます。プラグインを使用してアプリケーションをプロビジョニングするときに、特定の配備に適切なコンポーネントのバージョンを選択できます。

Sun N1 Service Provisioning System のブラウザインタフェースを使用したコンポーネントの作成については、『Sun N1 Service Provisioning System 5.2 プランとコンポーネントの開発者ガイド』の「コンポーネントを作成する」を参照してください。

単純コンポーネントと複合コンポーネント

単純コンポーネントには、ファイル、ディレクトリ、アーカイブファイル、またはアプリケーションなどの単一の物理リソースが含まれます。単純コンポーネントはほかのコンポーネントを参照しません。

複合コンポーネントは、ほかの単純コンポーネントまたは複合コンポーネントを参照するだけです。複合コンポーネントには、直接、物理リソースは含まれません。

例 2–1 単純コンポーネントの XML

次の XML の例は、システムコンポーネントタイプ system#CR Simple Base を拡張して JAR ファイルを含めた単純コンポーネントを示します。コンポーネントの定義に使用する特定の要素や属性については、『Sun N1 Service Provisioning System 5.2 XML スキーマリファレンスガイド』の第 3 章「コンポーネントのスキーマ」を参照してください。

<?xml version="1.0" encoding="UTF-8"?>
<component xmlns='http://www.sun.com/schema/SPS' name='plugin-core.jar' 
    version='5.2' description='Jar file implementation of core plugin services' 
    xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' author='system' 
    softwareVendor='Sun Microsystems' path='/system' 
    xsi:schemaLocation='http://www.sun.com/schema/SPScomponent.xsd'>
  <extends>
    <type name='system#CR Simple Base'>
    </type>
  </extends>
  <resourceRef>
    <resource name='/system/plugin-core.jar' version='1.1'>
    </resource>
  </resourceRef>
</component>

変数

コンポーネントまたはプランを作成するときに、コンポーネントの配備時またはプランの実行時に使用する変数を定義できます。多くのコンポーネントタイプには共通の変数が含まれます。たとえば、installPath はコンポーネントのインストール先を定義します。installPath 変数の値は、コンポーネントがホストにインストールされるときに決定します。

共通の変数をいくつか次に示します。

installPath – コンポーネント、プラグイン、またはその他のリソースファイルのインストール先のパス
installName – インストールする項目の名前
installUser – コンポーネント、プラグイン、またはその他のリソースファイルをインストールしたユーザーのログイン名
pluginClasspath – 特定のプラグインに適用するクラスのインストール先のパス

変数は、コンテナコンポーネントの変数など、別の変数を参照できます。たとえば、単純コンポーネントの installPath 変数の値は、その親コンテナコンポーネントの installPath 変数の値にできます。

変数を定義するときに変数の名前とデフォルト値の属性を指定します。デフォルト値は、次の場所から取得できます。

リテラル文字列
ホスト (target キーワードを使用)
別のコンポーネント (component キーワードを使用)
ユーザーのセッション (session キーワードを使用)

これらの属性の使用については、『Sun N1 Service Provisioning System 5.2 プランとコンポーネントの開発者ガイド』の「置換に使用できる変数の種類」を参照してください。

変数は、ブラウザインタフェースを使用して定義するか、または直接 XML ファイルで定義できます。XML ファイルでは、変数は <var> 要素を使用して定義され、<varList> 要素内に追加されます。

例 2–2 XML での変数の定義

次の XML フラグメントでは、複数の変数を定義しています。

<varList>
    <var name='installPath' 
         default=':[target:sys.raDataDir]:[/]systemcomps'>
    </var>
    <var name='pluginClasspath' 
         default=':[installPath]:[/]plugin-core.jar'>
    </var>
    <var name='fileBrowser' 
          default='com.sun.n1.sps.pluginimpl.system.browse.FilesystemBrowserFactory'>
    </var>
    <var name='directoryBrowser' 
          default='com.sun.n1.sps.pluginimpl.system.browse.FilesystemBrowserFactory'>
    </var>
    <var name='symlinkBrowser' 
          default='com.sun.n1.sps.pluginimpl.system.browse.FilesystemBrowserFactory'>
    </var>
</varList>

構成テンプレート

構成テンプレートは、特殊なファイルコンポーネントです。構成テンプレートを使用すると、配備するファイル内でトークン置換を行うことができます。この使用方法の例として、DNS の /etc/resolv.conf ファイルの配備があります。配備の目標は、たとえばファイルで変数置換を使用し、ホストタイプ属性を使用して最も近い DNS サーバーを定義することです。構成テンプレートの例を次に示します。

search :[search_path]
nameserver :[primary_dns]
nameserver :[secondary_dns]

この場合、構成テンプレートによって search_path、 primary_dns、secondary_dns というコンポーネント変数が自動的に作成されます。すると、プランやコンポーネントの制御で変数置換を使用して、適切な値を指定できます。

構成テンプレートの定義方法については、『Sun N1 Service Provisioning System 5.2 XML スキーマリファレンスガイド』を参照してください。

コンポーネントタイプの定義

Sun N1 Service Provisioning System 製品には、基本のコンポーネントタイプが多数含まれます。一部の基本コンポーネントタイプには、ファイルやディレクトリなどの項目が含まれます。特定のアプリケーションまたはプラットフォームで使用する特定のコンポーネントタイプを定義することもできます。たとえば、アプリケーションで常に使用する特定のファイルタイプがあるとします。この場合、アプリケーション用に system#CR Simple Base コンポーネントタイプを拡張して、アプリケーションに新しいコンポーネントタイプを定義できます。

コンポーネントタイプの定義は、ほかのコンポーネントの XML ファイルと同様に XML ファイルに保存されます。プラグインを定義するときに、記述子ファイルの <component> 要素で、バッキングコンポーネントのファイルのパスを指定します。<component> 要素の <componentType> 子要素を使用して、名前、説明などの追加情報を指定します。詳細は、例 2–15 を参照してください。

コンポーネントタイプにバージョンはありません。プラグインで、既存のコンポーネントタイプと同じ名前のコンポーネントタイプを作成しようとすると、名前の衝突を防ぐために、新しいコンポーネントタイプの名前の前にプラグイン名が付加されます。

コンポーネントタイプの作成方法については、『Sun N1 Service Provisioning System 5.2 XML スキーマリファレンスガイド』の「<componentType> 要素」を参照してください。

プランの作成

プランは、特定のホストで 1 つまたは複数のコンポーネントの管理に使用する一連の命令です。たとえば、プランで 3 つのコンポーネントをインストールして、別のコンポーネントの起動制御を開始することができます。ほとんどの場合、プランを作成するには、XML を編集する必要があります。この規則への唯一の例外は、自動生成プランです。Sun N1 Service Provisioning System ソフトウェアでは、直接実行手続きから構成されるプランを自動的に生成できます。たとえば、1 つのコンポーネントのインストールから構成されるプランを自動生成できます。次に、このプランを直接実行するか、保存してほかの複雑なプランを作成するテンプレートとして使用できます。

N1 SPS ソフトウェアでは、プランのバージョンを取得できます。プラグインのプランを変更し、これらのプランを N1 SPS 環境にチェックインすると、プランに新しいバージョン番号が割り当てられます。プラグインを使用してアプリケーションをプロビジョニングするときに、配備に適切なプランのバージョンを選択できます。

単純プランと複合プラン

単純プランには、一連の配備命令 (ステップ) が含まれます。単純プランは、1 つのホストまたはホストセットで実行します。単純プランでは、インストールやアンインストールなどの共通の手続きを呼び出すことができます。また、条件付きのプログラミング構文も使用できます。

複合プランには、単純プランへの呼び出しが含まれます。複合プランでは、1 つのホストに手続きを適用すると同時に、ほかの手続きを別のホストまたはホストセットに適用できます。

例 2–3 単純プランの XML

単純プランの例を次に示します。このプランには、インストールブロックとアンインストールブロックがあります。プランの定義に使用する特定の要素や属性については、『Sun N1 Service Provisioning System 5.2 XML スキーマリファレンスガイド』の第 4 章「プランのスキーマ」を参照してください。

<?xml version="1.0" encoding="UTF-8"?>
<!-- generated by N1 SPS -->
<executionPlan xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' 
    name='plugin-core.jar-1096573592002' version='5.12' 
    xsi:schemaLocation='http://www.sun.com/schema/SPSplan.xsd' 
    xmlns='http://www.sun.com/schema/SPS' path='/system/autogen'>
    <simpleSteps>
        <install blockName='default'>
            <component name='plugin-core.jar' path='/system' version='1.1'>
            </component>
        </install>
        <uninstall blockName='default'>
            <installedComponent name='plugin-core.jar' versionOp='=' 
                 version='1.1' path='/system'>
            </installedComponent>
        </uninstall>
    </simpleSteps>
</executionPlan>

例 2–4 複合プランの XML

複合プランの例を次に示します。この例では、3 つのサブプランを呼び出しています。

<executionPlan 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  name="apache-tomcat-uninstall" version="5.2"
  xsi:schemaLocation="http://www.sun.com/schema/SPSplan.xsd"
  xmlns="http://www.sun.com/schema/SPS">
    <compositeSteps>
        <execSubplan planName="mod-jk-uninstall" />
        <execSubplan planName="apache-uninstall" />
        <execSubplan planName="tomcat-uninstall" />
    </compositeSteps>
</executionPlan>

例 2–5 より高度なプランの XML

次の例に、条件に基づいて何を実行するかを決定する、より複雑なプランを示します。

<?xml version="1.0" encoding="UTF-8"?>
<!-- generated by CR -->
<executionPlan xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    name="BAM_backout_new_version_NODE-A" version="5.2" 
    xsi:schemaLocation="http://www.sun.com/schema/SPSplan.xsd" 
    xmlns="http://www.sun.com/schema/SPS" path="/plans/uat">
   <paramList>
      <param name="backout_type" prompt="Enter type of backout (all,ear,prop)"></param>
   </paramList>
   <varList>
      <var name="admin_server" default="wusx119"></var>
      <var name="node" default="wust3022"></var>
      <var name="wl_server_name" default="bamC"></var>
      <var name="apphome" default="/opt/uat/ceodomain"></var>
      <var name="prop_args" default="-s wust3022"></var>
      <var name="application_name" default="bam"></var>
      <var name="staging_base" default="/usr/local"></var>
      <var name="user" default="weblogic"></var>
   </varList>
   <simpleSteps limitToHostSet="uat-bam">
      <if>
         <condition>
            <or>
               <equals value2="all" value1=":[backout_type]"></equals>
               <equals value2="prop" value1=":[backout_type]"></equals>
               <equals value2="ear" value1=":[backout_type]"></equals>
            </or>
         </condition>
      <then>
         <call blockName="backout_application">
            <argList application_name=":[application_name]" 
                 staging_base=":[staging_base]" 
                 backout_type=":[backout_type]" 
                 user=":[user]">
            </argList>
            <installedComponent name="deploy_tools" 
                  path="/components/function_library">
             </installedComponent>
         </call>
         <call blockName="wl_stop">
            <argList wl_server_name=":[wl_server_name]" 
                  node=":[node]" apphome=":[apphome]" user=":[user]">
            </argList>
            <installedComponent name="deploy_tools" 
                  path="/components/function_library">
            </installedComponent>
         </call>
         <if>
            <condition>
              <equals value2="all" value1=":[backout_type]"></equals>
            </condition>
         <then>
               <call blockName="clusterdeploy">
                  <argList application_name=":[application_name]" 
                        staging_base=":[staging_base]" node=":[node]" user=":[user]">
                  </argList>
                  <installedComponent name="deploy_tools" 
                        path="/components/function_library">
                  </installedComponent>
               </call>
               <call blockName="deploy_prop">
                  <argList application_name=":[application_name]" 
                        prop_args=":[prop_args]" staging_base=":[staging_base]" 
                        user=":[user]">
                  </argList>
                  <installedComponent name="deploy_tools" 
                        path="/components/function_library">
                     </installedComponent>
                  </call>
                  <call blockName="wl_startjsp">
                     <argList application_name=":[application_name]" 
                        wl_server_name=":[wl_server_name]" 
                        node=":[node]" apphome=":[apphome]" user=":[user]">
                     </argList>
                     <installedComponent name="deploy_tools" 
                        path="/components/function_library">
                     </installedComponent>
                  </call>
               </then>
            </if>
            <if>
               <condition>
                  <equals value2="ear" value1=":[backout_type]"></equals>
               </condition>
               <then>
                  <call blockName="clusterdeploy">
                     <argList application_name=":[application_name]" 
                        staging_base=":[staging_base]" node=":[node]" user=":[user]">
                     </argList>
                     <installedComponent name="deploy_tools" 
                        path="/components/function_library">
                     </installedComponent>
                  </call>
                  <call blockName="wl_startjsp">
                     <argList application_name=":[application_name]" 
                        wl_server_name=":[wl_server_name]" 
                        node=":[node]" apphome=":[apphome]" user=":[user]">
                     </argList>
                     <installedComponent name="deploy_tools" 
                        path="/components/function_library">
                     </installedComponent>
                  </call>
               </then>
            </if>
            <if>
               <condition>
                  <equals value2="prop" value1=":[backout_type]"></equals>
               </condition>
               <then>
                  <call blockName="deploy_prop">
                     <argList application_name=":[application_name]" 
                        prop_args=":[prop_args]" 
                        staging_base=":[staging_base]" user=":[user]">
                     </argList>
                     <installedComponent name="deploy_tools" 
                        path="/components/function_library">
                     </installedComponent>
                  </call>
                  <call blockName="wl_start">
                     <argList application_name=":[application_name]" 
                        wl_server_name=":[wl_server_name]" 
                        node=":[node]" 
                        apphome=":[apphome]" 
                        user=":[user]">
                     </argList>
                     <installedComponent name="deploy_tools" 
                        path="/components/function_library">
                     </installedComponent>
                  </call>
               </then>
            </if>
         </then>
         <else>
            <raise message="Please enter a valid deployment type (all/ear/prop)"></raise>
         </else>
      </if>
   </simpleSteps>
</executionPlan>

プランの生成方法

「Components」ページを表示します。

プランを生成するコンポーネントを選択します。

コンポーネントの詳細を表示します。

「Component Procedures」が表示されていない場合は、表示されるまでページをスクロールダウンします。

プランで使用する手続きを選択します。

「Generate Plan with Checked Procedures」をクリックします。

「Plans」編集ページが表示されます。このページから、XML を変更して例 2–5 に示すような複雑なステップを含めることができます。

プランやコンポーネントでのネイティブコマンドの使用 (`<execNative>` ステップ)

XML の <execNative> ステップを使用すると、プランやコンポーネント内からネイティブコマンドを実行できます。たとえば、プロセスが開始したことを確認するには、<execNative> を使用して UNIX の ps コマンドを呼び出すことができます。<execNative> のスキーマ、属性、および子要素については、『Sun N1 Service Provisioning System 5.2 XML スキーマリファレンスガイド』の「<execNative> ステップ」を参照してください。

指定したコマンドが <execNative> で実行される前に、コマンドが存在すること、また指定したユーザーがコマンドの実行権を持っていることが Sun N1 Service Provisioning System ソフトウェアによって確認されます。コマンドが存在しないか、実行権がなかった場合は、<execNative> がエラーで終了します。

例 2–6 `<execNative>` を使用した簡単なコマンドの呼び出し

次の <execNative> の例では、UNIX の ps -ef コマンドと同等な動作が実行されます。

<execNative>
    <exec cmd="ps">
        <arg value="-ef" />
    </exec>
</execNative>

例 2–7 `<execNative>` を使用したアプリケーションの起動

次の <execNative> の例では、Web サーバーのインスタンスを開始しています。

<execNative
  dir="/opt/ns/https-admserv"                Set working directory
  userToRunAs="webadmin"                     Equates to "su -webadmin"
  timeout="5">
    <inputText>
        start.sh                             Input parameters to command
    </inputText>
    <exec cmd="sh />                         Command to run
    <successCriteria status="0" />           execNative succeeds only if exit code is "0"
</execNative>

プランやコンポーネントでの Java ベースのオブジェクトの呼び出し (`<execJava>`)

<execJava> メカニズムを使用すると、プランまたはコンポーネントの定義内でのクライアント提供 Java コードのプロセス内実行をエージェント側で有効化できます。<execJava> は <execNative> に似ていますが、Java コードの実行が対象です。

<execJava> 機能は、XML ステップとして、また Java ベースの API として提供されています。XML のスキーマ、属性、および子要素については、『Sun N1 Service Provisioning System 5.2 XML スキーマリファレンスガイド』の「<execJava> ステップ」を参照してください。execJava API については、「execJava API」を参照してください。ここでは、例も示しています。

XML の <execJava> ステップには必須の属性が 1 つ、省略可能な属性が 2 つあります。

className – ターゲットホストで実行する Java クラスを指定する必須の属性です。
classPath – className 属性で指定するクラスのパスを指定する省略可能な属性です。この属性を使用しなかった場合、リモートエージェントのシステムクラスパスが使用されます。
timeout – タイムアウトになるまでに Java クラスの実行を待つ時間 (秒単位) を指定する省略可能な属性です。

<execJava> メカニズムでは、<argList> 子要素を使用して Java Executor に引数を渡すことができます。

例 2–8 コンポーネントの XML での `<execJava>` の使用

<varList>
   <var name="installPath" default="/opt/util"/>
</varList>
<resourceList defaultInstallPath=":[installPath]">
   <resource resourceName="util/propPrint.jar" installName="propPrint.jar"/>
</resourceList>
   ...
<controlList>
   <control name="showProp"/>
   <paramList>
       <param name="propName">
   </paramList>
   <execJava
       className="com.raplix.util.PropertyPrinterFactory"
       classPath="$[installPath]/propPrint.jar">
       <argList>
           <arg name="propertyName" value=":[propName]"/>
       </argList>
       <successCriteria outputMatches="<undefined>" inverse="true"/>
   </execJava>

例 2–9 プランの XML での `<execJava>` の使用

<executionPlan xmlns="http://www.sun.com/schema/SPS" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xsi:schemaLocation="http://www.sun.com/schema/SPSplan.xsd" 
   name="execJavaExample" version="5.2">
   <paramList>
       <param name="name"></param>
       <param name="value"></param>
   </paramList>
   <varList>
       <var name="classpath" 
           default=":[target:sys.raDataDir]:[/]systemcomps:[/]plugin-com.sun.sample.jar"/>
   </varList>
   <simpleSteps>
       <execJava className="com.sun.n1.sps.pluginimpl.sample.executor.SampleExecutorFactory"
           classPath=":[classpath]">
           <argList nameParam=":[name]" valueParam=":[value]" />
       </execJava>
   </simpleSteps>
</executionPlan>

条件付き要素

プランまたはコンポーネント内で <if> 要素を使用して、ステップのブロックを実行する条件を指定できます。従来のプログラミングの if-then-else 構文と同様に、<if> 要素内の文が評価されます。この文が真の場合は、<then> 要素のステップが実行されます。真ではなかった場合は、<else> 要素のステップが実行されます。<else> 要素がなかった場合は、何も処理が行われません。

例 2–10 `<if>` 要素の XML

次の例では、<if> 要素を使用して、ユーザーが配備時にシステムのスナップショットを作成して、ターゲットホストでのコンポーネントのインストール状態を取得するかどうかを決定できるようにしています。

<if>
    <condition>
        <istrue value=:[createSnapshot]"></istrue>
    </condition>
    <then>
        <createSnapshot blockName="default"></createSnapshot>
    </then>
</if>

エラーの処理

XML スキーマには、エラー処理用の一連の要素があります。この一連の要素の親は <try> 要素です。これらの要素は、次のような場合に使用できます。

配備時にエラーを抑制する場合。たとえば、コンポーネントのインストール時にファイルまたはその他のリソースを配備してから再起動する場合、再起動が失敗したときにインストール自体は失敗しません。
別のステップに依存するステップを実行するかどうかを制御する場合。たとえば、useradd と groupadd の両方の機能を実行する場合、groupadd は useradd が正常に終了した場合にのみ実行します。
インストールパスを指定する場合。たとえば、アプリケーションの version 1.1 をインストールする場合、ターゲットホストにそのアプリケーションの version 1.0 があるかどうかによってインストールパスが異なります。

<try> 要素には、ステップのブロックを含めます。これらの手順は、すべてが正常に完了するまで、または 1 つのステップが失敗するまで順番に実行されます。ステップが失敗し、<catch> 要素があった場合、<catch> 要素のステップが、すべて正常に完了するまで、または 1 つのステップが失敗するまで順番に実行されます。<finally> 要素が定義されている場合は、<finally> 要素のステップが、すべて正常に完了するまで、または 1 つのステップが失敗するまで順番に実行されます。これは、<try> 要素と <catch> 要素が正常に完了したかどうかに関係ありません。一般に、<finally> 要素は、クリーンアップ機能の実行やリソースの解放のために使用します。

<raise> 要素は、専用のステップを作成せずに障害の状態を指定するために使用します。<raise> ステップは必ず失敗します。<raise> 要素は単独で使用できますが、通常は <catch> 要素のブロック内で使用します。

例 2–11 `<try>` 要素の XML

次の XML の例では、<try> 要素を使用して、初期インストールを実行するか、アップグレードインストールを実行するかを決定しています。

<installSteps blockName="default">
    <try>
        <block>
            <checkDependency>
                <installedComponent name="foo" version="1.0" />
            </checkDependency>
        </block>
        <catch>
          <raise message="Required component foo is not installed on this system"/> 
        </catch>
    </try>
</installSteps>