Creating an IBM® Pattern Software Component Project

You can use the Plug-in Development Kit to create software component projects.

1. If you are using the Plug-in Development Kit Eclipse plug-in, open the Workload Plug-in Development perspective by clicking Window > Open Perspective > Other > Workload Plug-in Development. Then, click OK.

   The Plug-in Development Kit welcome page opens.

2. Click the Create an IBM Workload Software Component Project link on the welcome page. You can also create a software component project by clicking File > New > Project > IBM Workload Software Component Project.
3. Enter the information for the project:

   Project name

   Set the name for your project.

   Location

   Set the location where the files for your project are stored.

   Plug-in name

   Set the name of the plug-in that is generated by your project. This plug-in makes the components that you configure in the software component project available in Cloud Pak System Software for Power®. After you install the plug-in to Cloud Pak System Software for Power, you can view it by clicking Catalog > Components Definition .

   Plug-in version

   Set the version for your plug-in. You can increment the version as you update your software component project to track changes.

   Note: When system fetches plug-in details from the database query, it finds plug-ins with the same partKeys. However, the system picks up the first version of the plug-in's partKeys. If you want to use two versions of the plug-ins, use a different partsKey for each version.

   Generate project skeleton

   This setting is enabled by default. With this option checked, the Plug-in Development Kit creates the skeleton project artifacts, such as config.json, parts, and lifecycle scripts, for you. After these skeleton artifacts are created, you edit them as needed for your project. If you do not select this option, you must manually create these artifacts.

   Add project to working sets

   Use this option to add the project to a specified working set. This option is disabled by default.

4. Click Next.
5. Set the pattern type that contains the plug-in. Software components are added to the virtual system pattern type by default.
   Important: If you plan to use the Build with binary option when you build the plug-in, you must select a primary pattern type. Otherwise, the installation of this single plug-in, with its binary files, might fail. If you want the software component to be included only with the Virtual System Pattern Type, set it as the primary pattern type. Set the Virtual System Pattern Type as the primary pattern type by adding vsys as the name and the version of the Virtual System Pattern Type on the system where you plan to import the software component as the version.
6. Click Finish.
   The Plug-in Development Kit creates the project, and the Overview page for the project, which lists the steps to complete the project, is displayed.

   Note: If you close the Overview page, you can open it by clicking overview in the software component project.
7. From the Overview page, click Configure Software Packages, or change to the Packages tab.
8. Define the package information for the project:
   Note: Required fields are marked with an asterisk (*). Be sure to populate all required fields or an error occurs when you build the software component.
   1. Modify the Name field, if needed. By default, this field is populated with the name that you set in step 3.
   2. Modify the Version field, if needed. By default, this field is populated with the version that you set in step 3.
   3. Modify the Pattern Types field, if needed. By default, this field is populated with the pattern types that you set in Step 5.
   4. Click the Artifacts link to specify binary files for the package. You can specify files from your local drive, or from a remote location. If you specified files on your local drive, the files are uploaded to Storehouse to the relative path that you set on the Select Artifact page when the plug-in is built. If you specified a remote location, a placeholder is created in Storehouse that points to that remote location for the files.
      Important: Storing files on a remote location is recommended only for development purposes.
   5. Click the Plug-in Parameters link to specify common parameters for the software package. These parameters can be referenced by parts.
   6. Click the IM Artifacts link to specify the binary files for the package that you want to make available in the internal Installation Manager repository. You must also specify the category for the artifact in the repository. After you package the software component and import it to Cloud Pak System Software, the artifacts that you specify here are made available in Catalog > IBM Installation Manager Repository.
      • If you define operating system and architecture requirements in config.json in the following step, the plug-in is only available for the specified operating system and architecture.
      • If you do not define operating system and architecture requirements in config.json in the following step, the plug-in is available for all supported operating systems and architectures that are specified in the Installation Manager artifact.
   7. Configure the available packages, if needed.
      After you add an artifact, it is listed in the Available Packages section of the Software Package page. Select a package to configure that package in the Package Details section.

      You can configure the following details on the Image Requirements tab:

      • Name: Sets the name for the package.
        Important: This name must be unique to prevent conflicts.
      • Architecture: Specify the required architecture for the package.
      • OS: Specify the operating systems and versions that are supported for use with this package. Select the Support multiple OS check box to specify more than one operating system. You can also click Add Support in the Package section to configure support for another operating system.
      • CPU: Specify the number of processors that are required by the package.
        Note: If you want to specify a value that is not in the list, you can manually enter values into this field.
      • Storage (MB): Specify the storage that is required by the package, in megabytes.
        Note: If you want to specify a value that is not in the list, you can manually enter values into this field.
      • Memory (MB): Specify the memory that is required by the package, in megabytes.
        Note: If you want to specify a value that is not in the list, you can manually enter values into this field.

      If the package depends on any other products, specify them on the Dependent Products tab.

      Note: In addition to listing the dependent products, you must also define the component in which the prerequisite product is installed. This step requires a manual update to the config.json file. The following example shows how to define the prerequisite component:

      "requires": {
              "components": [
                  {
                      "referenceID": "WAS",
                      "type": "WAS 8.5",
                      "attributes": [
                          {
                              "id": "installDir",
                              "value": "/opt/IBM/WebSphere",
                              "locked": true
                          }
                      ],
                      "runInstall": false
                  }
              ],
             "middleware": [{"product" : "IBM Application Server",  "version": "8.5.0.*" } ]}

      Specify the product and version that the package provides, such as Apache Tomcat, on the Package Provides tab.

      Specify the parts that are included in the package in the Included parts section. The parameters for these parts can be referenced by the install.py and uninstall.py scripts for the part.

9. From the Overview page, click Configure Software Component, or change to the Components tab to define the software component information.

   Software components display in the Pattern Builder when a user creates a virtual system pattern.

   You can configure one or more software components for a software component project. You must associate a package with each software component that you define.

10. Click Add to add a software component to the project. Configure the details for the software component:
    Note: Required fields are marked with an asterisk (*). Be sure to populate all required fields or an error occurs when you build the software component.
    1. Configure the Metadata details:

       ID

       Specify the ID for the software component.

       Label

       Specify the label for the software component that displays in Pattern Builder.

       Description

       Specify a description for the software component.

       Extends

       This field is set to PART by default. You can change this value if you want to specify a custom hierarchy for the software component rather than extending the generic software component.

       Image

       Specify an image for the software component. This image displays when the software component is added to a virtual system pattern.

       Thumbnail

       Specify a thumbnail image for the software component. This image displays next to the software component in the Pattern Builder palette.

    2. If needed, click the Add attributes for Required CPU, Memory, and Disk link to add attributes for Required CPU, Required Memory, and Required Disk to the software component. When users add the software component to a pattern, these attributes are configurable in the component details.
    3. In the Attributes section, specify any attributes that the user can configure when the software component is added to a virtual system pattern. If you want the values that the user sets for these attributes to be made available to the lifecycle scripts, script packages, or other software components when the virtual system pattern is deployed, click Export as output.
    4. If needed, configure the Outputs section. If you configured an attribute to be exported as output in the Attributes section, it is added to the Outputs section. Set the ID, Type, and Label for each attribute that is configured as an output. These outputs are available to the user when they wire the data dependency links as they build a virtual system pattern that includes the software component.
    5. Configure the Required packages section:
       • On the Package tab, add the packages that are referenced by the software component in the Required packages section. You configured the software components in step 8. For example, the referenced package might be the installation binary file for the software. Set the Part key, which specifies the directory where the lifecycle scripts for the project are located.
       • If you chose to upload artifacts for the software component to IBM Installation Manager, by using the IM Artifacts page, specify a filter on the Install via IM tab so that the system can locate the package in the repository. When a user adds a software component that installs software that is stored in the Installation Manager repository, this filter is used when the system queries the repository to retrieve the installation files.
       • On the YUM packages tab, add YUM packages as needed.
       • On the License tab, add licenses as needed.
    6. Configure console links, if needed.

       Define the name and URL for console links. Console links display on the virtual system instance page in the Virtual machines > Consoles section. You can use these links to provide an easy way for a user to access a console that is used to administer the virtual machine, such as VNC or the Integrated Solutions Console for WebSphere® Application Server.

       Define a console link by specifying the name and url for the console link that displays for the virtual machine that is associated with the script package. You can define the url in several ways:

       Static link

       If the link is known before deployment, you can specify the link as a static URL:

       {
                "name" : "IBM homepage",
                 "url" : "http://www.ibm.com/ibm"
            }

       Simple link

       If the link depends on the host name or IP address of the virtual machine, you can use the public-hostname or public-ip attributes that are defined in deployment.json, for the url attribute:

            {
               "name" : "VNC",
               "url" : "https://{public-hostname}/vnc"
            },

       The value is resolved after the pattern is deployed. In the preceding example, the link is set to https://myvmhostname/vnc, where myvmhostname is the fully qualified host name for the deployed virtual machine that is associated with the script package where the console link is defined.

       You can also reference a pattern level attribute. If the pattern contains the following attributes:

       "attributes": {
           "MY_PORT_VNC": ":9082",
           "MY_VALUE_1": "&parm1=ABC"
       },

       Then you can reference these attributes in the url attribute for the console link. Surround the attribute name with square brackets ([ ]). Use a vertical bar (|) to specify the default value:

            {
                "name" : "This link references a port",
                "url" : "https://{public-hostname}:[MY_PORT_VNC|9080][MY_VALUE_1|]"
            }

       If no value is set for the attribute when the link is resolved, an empty string is used. In the preceding example, if the pattern level attributes are defined, the URL resolves to: https://servername.com:9082&parm1=ABC. If the pattern level attributes are not defined, the URL resolves to https://servername.com:9080.

       Complex link

       You can reference another virtual machine in the virtual system instance by specifying search criteria, which are surrounded by square brackets ([ ]) with each criteria followed by a colon (:) so that the system can retrieve the parameter. The available search criteria are COMPONENTS, SCRIPTS, and IMAGES. Separate multiple criteria values with a comma (,) and end the list with a semicolon (;). Define the condition for the search criteria as it displays in the user interface. For example, if you want to reference another virtual machine in the virtual system instance that contains a script that is named "Test Script", and a component that is named SC1, set the url to "url" : "https://{[SCRIPTS:Test Script;COMPONENTS:SC1]:public-ip}/console".

       You can use one or more of these criteria for the search. If they are specified, all of the criteria must be met to retrieve the parameter.

       Example:

       "consoleLinks" : [
       {
       "name" : "EA: Complex Link",
       "url" : "https://{[components:SC2]:public-hostname}/console&[NO_PARM|Cat]"
       },
       {
       "name" : "EA: Another Complex Link",
       "url" : "https://{[components:SC2;image:OS Node_1;scripts:My Test Script]:public-hostname}[APP1_PORT|]/console[NO_PARM|&parm1=Cat][PARM_TEST|][NO_PARM2|]" 
       }
       ]

11. From the Overview page, click Configure Runtime Config, or change to the Runtime Operations tab define the operations for the software component. The settings that you configure on this page are saved to an object in the operation.json file.

    There are two types of actions you can perform to manage or modify deployed roles: operations and configuration changes. The main difference between these actions is the scope. For an operation, which is defined on the Runtime Operations tab and updates the operation.json file, the action affects only currently deployed roles. For a configuration change, which is defined in tweak.json, attribute changes are saved in the topology. If a virtual machine is restarted or more virtual machines are deployed, the configuration attribute value is applied to these virtual machines. If you want to add a configuration, you can access tweak.json by clicking the tweak.json link on the Advanced tab.

    When you add an operation, you must specify the following parameters:

    Role

    Specify the role that is associated with the operation.

    You can manage virtual application instances from the Operation page of the Instance Console. This page displays roles in the selected instance, and each role provides actions that are defined in the underlying plug-ins, such as retrieving data, applying a software update, or modifying a configuration setting. The operation that you define displays on this page with the role that you associate with it.

    ID

    Specify the ID for the operation.

    Label

    Specify a label for the operation, which displays on the Operation page of the Instance Console.

    Description

    Set a description for the operation, which displays on the Operation page of the Instance Console.

    Category

    Optional. Set a category for the operation.

    Script

    Defines the Python script that is started when the operation is submitted. This script name can be followed by a method name. The operation script must be placed under the role scripts path, for example, plugin/parts/was.scripts/scripts/WAS. The script (.py file) that is referenced must exist.

    Note: Do not use exit(0) in lifecycle or operation scripts. To return an error state , set the status, such as maestro.status = 'Failed', in start.py. Using this method keeps the software component in a controlled state so that it can be set back to RUNNING by another script after the problem is resolved.

    Attributes

    Define the operation parameters that the user must input. The operation parameters can be used by the operation script.

12. Modify the lifecycle scripts, which install, configure, and start that software, as needed. You can access the lifecycle scripts by clicking the links on the Overview page, or by double-clicking the file in the Project Explorer.