Add-ons in the catalog

Use the console to manage virtual system pattern add-ons in the catalog. You can use the default add-ons that are provided with the system, or you can clone and modify them, or create and configure your own. You can then add them as parts to one or more virtual system patterns.

Add-ons are specialized scripts that customize your virtual machine configuration. Add-ons provide fine-tuning for hardware and operating system configurations. A set of basic add-ons with an initial configuration is provided. You can use these default add-ons, clone and modify them as needed, or create new ones.

At deployment time, all add-on operations are run before the custom script packages are run. The order in which add-ons are run at deployment cannot be specified in a virtual system pattern, unlike scripts and parts. Add-ons always run as the system is created. They are not initiated by users, and they do not run at deletion. Depending on the type of add-on, special processing is performed during deployment to add the additional hardware to the virtual machine as needed. If multiple add-ons are used, they run in this order during deployment:
  1. Add NIC add-ons
  2. Add user add-ons
  3. Add disk add-ons
Add-ons are implemented at the following levels:
  • Deployment logic provisions new hardware for disks and network interface controllers (NICs) that cannot be customized.
  • Deployment logic configures the provisioned resources. Resources are packaged as default implementation scripts that are fully customizable. For example, the Default add user add-on has a defaultadduser.zip package that contains a script to define a user account.

To view the list of add-ons that are available in the catalog, click Catalog > Add-Ons.

You can add the following types of add-ons to virtual system pattern parts:

Disk
Adds a virtual disk to the virtual machine and optionally formats the file system and mounts the disk.

A raw disk is a virtual disk that is added without partitions or formatting.

Attention: You can define the size of your volume up to the following maximum values:
  • VMFS volume: 1.8 TB
  • RAW volume: 2 TB
Restriction: A virtual machine can have a maximum of 15 volumes (disks). Be aware of this limitation as you add disk add-ons to your virtual system pattern image parts.
NIC
Adds a virtual network interface controller (NIC) to the virtual machine. NIC add-ons are deployed with environment profiles.
Restriction: Support of the VMXNET 3 virtual network adapter is limited to three addresses or less. For example, you might have the following in the image OVF file, which indicates that your image is using the VMXNET 3 virtual network adapter:
<ovf:Item>
  <rasd:AddressOnParent>1</rasd:AddressOnParent>
  <rasd:AutomaticAllocation>true</rasd:AutomaticAllocation>
  <rasd:Caption:>Ethernet adapter on &quot;Network 1&quot;</rasd:Caption>
  <rasd:Connection>Network 1</rasd:Connection>
  <rasd:ElementName>Ethernet adapter on &quot:Network 1&quot;</rasd:ElementName>
  <rasd:InstanceID>7</rasd:InstanceID>
  <rasd:ResourceSubType>Vmxnet3</rasd:ResourceSubType>
  <rasd:ResourceType>10</rasd:ResourceType>
</ovf:Item
If you plan to deploy this image with 4 or more IP addresses, you must modify the OVF file to use a different NIC type. For example:
<ovf:Item>
  <rasd:AddressOnParent>1</rasd:AddressOnParent>
  <rasd:AutomaticAllocation>true</rasd:AutomaticAllocation>
  <rasd:Caption:>Ethernet adapter on &quot;Network 1&quot;</rasd:Caption>
  <rasd:Connection>Network 1</rasd:Connection>
  <rasd:ElementName>Ethernet adapter on &quot:Network 1&quot;</rasd:ElementName>
  <rasd:InstanceID>7</rasd:InstanceID>
  <rasd:ResourceSubType>PCNet32</rasd:ResourceSubType>
  <rasd:ResourceType>10</rasd:ResourceType>
</ovf:Item
Import the new image for use in deployments. All NICs in the OVF file must use the same NIC type.
For Linux
The IBM® OS Image for Red Hat® Linux® Systems, which is preinstalled in the system catalog, uses VMXNET3 as the default NIC type. Therefore, the previously mentioned restriction applies to all the deployments that use the virtual image named IBM OS Image for Red Hat Linux Systems for versions of RHEL 6.x or 7.x from Catalog. For patterns that are deployed through these Linux images, you can add up to only two NICs from Add Add-Ons > Default add NIC (or) Db2 VIP Linux add NIC of the Pattern Builder user interface. These two NICs are in addition to the two default NICs (Management and Data), which are part of the virtual image. If you want to add more than two NICs through add-ons of the Pattern Builder user interface, you must modify the OVF file inside the virtual image OVA file. Specify an NIC type other than VMXNET3, package the OVA file again, re-import into Catalog > Virtual Images and deploy the pattern again by using the updated image. Edit the OVF file inside the virtual image OVA as follows.
  1. Export the virtual image OVA file to any server from Catalog > Virtual Images > Export.
  2. Extract the OVA file by using this command:

    tar -xvf MAESTRO_RHEL7_X64.ova

    The contents are extracted to the MAESTRO_RHEL7_X64 folder.

  3. Go to the MAESTRO_RHEL7_X64 folder by using this command:

    cd MAESTRO_RHEL7_X64

  4. Open the MAESTRO_RHEL7_X64.ovf file and modify the following line and save the changes.
    <rasd:ResourceSubType>vmxnet3</rasd:ResourceSubType>
    to 
    <rasd:ResourceSubType>PCNet32</rasd:ResourceSubType>
  5. Remove the MAESTRO_RHEL7_X64.mf file and any other files that end with an .mf extension.
  6. On the command line, use the following command to repackage the OVA file.

    tar -cvf MAESTRO_RHEL7_X64.ova *

  7. Import the OVA file again at Catalog > Virtual Images > Create New > Create by importing an OVA image. Provide the remote URL by copying the OVA file to a server, which can be accessed through http or https, to the OVA file that you just re-packaged.
For Windows
Cloud Pak System Software does not ship a default virtual image with default data or Catalog. You must create your own virtual image by using the IBM OS Pattern Kit for Windows software, which can be downloaded from the welcome page of the Cloud Pak System Software console. If you want to use more than four NICs for any deployment, do not select VMXNET3 as the NIC adapter type in the base virtual machine of the vCenter server. You must select a different NIC type to support more than four NICs.
User
Defines an extra user on the virtual machine.
None
Reserved for add-ons related to block storage support. This storage is not tied to a deployment, can be attached and detached from virtual machines, and persists after a deployment is deleted.

Default add-ons

The following set of default add-ons are provided with the product:
Add disk to PureApp agent
Adds a virtual disk to the virtual machine to contain the maestro agents and the associated log files. The /opt/IBM/maestro directory is installed and run from that disk.

This add-on is based on the addmaestrodisk.zip package file.

Add disk to Cloud Pak System agent
Adds a virtual disk to the virtual machine to contain the maestro agents and the associated log files for the Cloud Pak System agent directory. The /opt/IBM/maestro directory is installed and run from that disk. This add-on is part of Cloud Pak System Version 2.3.3.
This add-on is Version 2.0.0, which is based on the addmaestrodisk.zip package file.
Note: Starting with Cloud Pak System Version 2.3.3, use this re-branded add-on.
Default add NFS
Adds a new virtual disk (network-attached storage) to the virtual machine, and optionally formats and mounts the disk.

One of the optional parameters for this add-on is ENABLE_NFS_LOCK. This option is applicable only for Linux. If you select this option, NFS file locking is enabled for the virtual disk by starting the rpcbind and nfslock services and the STATD port is opened. For AIX, NFS file locking is enabled by default.

This add-on is based on the defaultaddnfs.zip package file.

Default add NIC
Adds a new virtual network interface controller (NIC) to the virtual machine, configures its IP address information, and activates it. Use this add-on for virtual image parts that support communication by using SSH to run scripts after initial activation of the VM.

This add-on has an optional field, PORTS. Specify TCP ports to open in the firewall for the network interface that the NIC add-on creates in this PORTS field. Separate multiple values with commas.

When you deploy this add-on with your Linux image, you are prompted to associate the NIC with an IP group.

This add-on is based on the defaultaddnic.zip package file.

You can add only up to two NICs in addition to the two NICs that are included in the default virtual image. This addition is due to the previously mentioned restriction about VMXNET 3 virtual network adapter type. This type includes both, Default add NIC and DB2 VIP Linux add NIC types, or a combination of both.

Default add disk
Adds a virtual disk to the virtual machine and optionally formats and mounts the disk.

If you set the required MOUNT_POINT field to the root file system (for example, /), the newly added disk is used to expand the existing root volume group (rootvg) and file system.

Before IBM Cloud Pak System 2.3.3.3 version, if you request a default add-on disk of size 0 bytes at deployment time, then a disk of 0-byte size gets created in the deployed virtual machine. However, in IBM Cloud Pak System 2.3.3.3 or later, a 0-bytes disk request is ignored and is not mounted. This feature accommodates hypervisors with maximum disk size and allows the allocation of multiple disks. Though the maximum disk size of a virtual machine is 1 TB, deployments might need virtual machines with more or less disk space. For example, some deployments need virtual machines with 4 TB of storage, while other deployments need virtual machines with only 1 TB:
  • In IBM Cloud Pak System 2.3.3.0, you must create two different patterns, one with four 1-TB-sized disks added, and another with one 1-TB-sized disk added.
  • In IBM Cloud Pak System 2.3.3.3 or later, you can create one pattern with four disks added. At deployment time, if the virtual machine needs only 1 TB, then you can set the size for the three extra disks to 0 bytes, and they are ignored during the deployment of the virtual machines. For virtual machines that require 4 TB, all disk sizes can be set to 1000 G, and all four disks get allocated.
This add-on has the following optional fields:
OWNER
If a valid user name is entered in this field at the deployment time or pattern creation time, the new mount point directory that the add-on creates is owned by the specified user.
VOLUME_GROUP
The volume group will be created if it does not exist and will be extended with the new physical volume.

This add-on is based on the defaultadddisk.zip package file.

Note:

This add-on does not enforce any rules on the mount point. If you set the mount point to a reserved directory such as /opt/IBM, the virtual machine activation might fail.

Add maestro disk
Adds a virtual disk to the virtual machine to contain the maestro agents and the associated log files. The /opt/IBM/maestro directory is installed and run from that disk.

This add-on is based on the addmaestrodisk.zip package file.

Default add user
Defines an extra user on the virtual machine. The default add-on script runs a simple add user command. No additional account configuration is performed.

This add-on is based on the defaultadduser.zip package file.

Default attach block disk
Attaches existing block storage at deployment and optionally formats and mounts the disk. This disk can be detached and reattached after deployment, and persists after the deployment is deleted. You can also create a new block disk at deployment time. To ensure that the add-on is deployed successfully, specify a block disk size of 2 MB or larger.
CAUTION:
Although the user interface does not place restrictions on the mount points that can be used, the following mount points will cause the deployment of the default IBM OS images to fail: /var, /opt, /opt/AE, /opt/python-2.6.4, /opt/ibm, /opt/ibm/ae, /opt/ibm/fixnetwork, /opt/ibm/scp, /opt/IBM/AE, opt/IBM/maestro, usr/local. If you choose to use these mount points, be aware of the following caveats:
  • If you are using the default IBM OS images, your deployment will fail if these mount points are used.
  • Whether these mount points work with a custom OS image depends on whether the path is an existing mount point in the image, as opposed to just a directory. If the path is an existing mount point, the add-on causes the volume to be expanded and does not impact the deployment's success or failure. If it is not, the deployment fails just like it would if you were using the default IBM OS image.

The data in the block storage is persisted even when the pattern instance that is using the storage is deleted or if the storage is detached from the pattern instance. When you reattach the same block storage to a different pattern deployment, the existing data is not deleted. In some cases, the persisted data might affect your pattern deployment. Unless you want to reuse the data that is in block storage, create a new block storage and use this new block storage for your pattern deployments.

The attach block add-on supports logical volumes for the Linux operating system. When you attach a block disk by using the attach block disk add-on that is provided with version 2.3.0.0 and later, the disk is mounted as a logical volume. The disk is mounted as a logical volume only if the Linux instance root partition is also mounted as a logical volume. Any disks that were mounted on Linux instances before version 2.3.0.0 continue to be mounted as non-logical volumes. If you attach a logical volume disk by using the attach block disk add-on to a Linux instance that does not use a logical volume for the root partition, the system throws an error and fails to mount the disk to the virtual machine.

Starting in version 2.3.0.0, if you mount any new disk by using the attach block disk add-on, online expansion is supported.

Complete the following steps to perform an online expansion:
  1. Click Cloud > Volumes.
  2. Select the volume to expand.
  3. Click the Expand link and increase the size of the volume.
  4. Click Patterns > Virtual System Instances to open the Virtual System Instances page.
  5. Select the virtual system instance.
  6. Expand the virtual machine in the Virtual machine perspective section.
  7. In the block storage table, click Refresh Size in the Actions column.
Note: If you expand a block storage volume that is greater than or equal to 2 TB that was previously formatted to Logical Volume Manager (LVM), you must expand the logical volume that is mounted on the virtual machines manually. In this case, the Refresh Size action does not expand the logical volume and produces an error. For more information, see Expanding volume size for LVM volumes.

This add-on is based on the defaultattachblockdisk.zip package file.

Note: To deploy patterns using the attach block disk add-on, all components in your pattern must use IBM Foundation Pattern Version 2.1.0.0 or later.
Default configure NIC
Adds a new virtual network interface controller (NIC) to the virtual machine, and configures its IP address information as part of initial virtual machine activation. This is not an executable add-on script. Use this add-on for virtual image parts that do not support communication by using SSH to run scripts after initial activation of the virtual machine.

When a Windows system is deployed by Cloud Pak System with 3 or more network interfaces, only one IPv4 or IPv6 default gateway is configured to avoid the possibility of data being routed to an unintended network. As a best practice, routing through other network interfaces is achieved by configuring static routes. If backup default routing is required, other network interfaces can be configured to have a default gateway with a larger gateway metric than that of the one default gateway that is configured during deployment. You can configure static routes or add default gateways by using script packages that run during deployment, or manually after deployment.

The Delete icon is disabled for this add-on because deleting this default version from the catalog might affect virtual application deployments.

This add-on is based on the defaultconfigurenic.zip package file.

Default raw disk
Adds a virtual disk to the virtual machine. The disk is added raw, that is, without partitions or formatting. The Delete icon is disabled for this add-on, because deleting this default version from the catalog might affect virtual application deployments.

This add-on is based on the defaultaddrawdisk.zip package file.

Default Windows add disk
Adds a virtual disk to the Windows virtual machine, formats the disk, and assigns a drive letter.

This add-on is based on the defaultwinadddisk.zip package file.

Default Windows attach block disk
Attaches existing block storage at deploy time and optionally formats and mounts the disk. This disk can be detached and reattached after deployment, and persists after the deployment is deleted. You can also create a new block disk at deployment time. To ensure that the add-on is deployed successfully, specify a block disk size of 2 MB or larger.

This add-on is based on the defaultwinattachblockdisk.zip package file.

Default Windows add NIC
Adds a new virtual network interface controller (NIC) to the Windows virtual machine, configures its network connection, and activates it. Use this add-on for virtual image parts that support communication by using RXA/SMB to run scripts after initial activation of the VM.

This add-on has an optional field, PORTS. Specify TCP ports to open in the firewall for the network interface that the NIC add-on creates in this PORTS field. Separate multiple values with commas.

When you deploy this add-on with your Windows image, you are prompted to associate the NIC with an IP group.

When a Windows system is deployed by Cloud Pak System with 3 or more network interfaces, only one IPv4 or IPv6 default gateway is configured to avoid the possibility of data being routed to an unintended network. As a best practice, routing through other network interfaces is achieved by configuring static routes. If backup default routing is required, other network interfaces can be configured to have a default gateway with a larger gateway metric than that of the one default gateway that is configured during deployment. You can configure static routes or add default gateways by using script packages that run during deployment, or manually after deployment.

This add-on is based on the defaultwinaddnic.zip package file.

Ignition Configuration

In IBM Cloud Pak System 2.3.3.3, as a pattern developer, you can click a CoreOS node and select the Ignition Configuration add-on. It adds an ignition configuration to a CoreOS virtual machine. This add-on must only be added to Core OS VM images.

It allows a CoreOS node to be initialized with an append ignition string that can be specified during deployment. The append ignition string contains only enough information for the CoreOS to contact a HTML server where the full configuration details of the virtual machine can be accessed.

The configured ignition data gets applied to all clones of the virtual machine that this add-on is assigned to. If the deployer must create a set of Core OS virtual machines with the same ignition configuration, then a pattern can be created with just a scaled Core OS image and this add-on. The scaling applies only to the initial creation of the virtual machines and cannot be changed after the initial deployment.

Specify the following attributes for the Add ignition configuration:
  • START_IMMEDIATE

    Checks whether IBM Cloud Pak System starts the virtual machine or not. The DNS and DHCP servers must be started as a prerequisite for a CoreOS virtual machine. If the servers are already running, then specify true for this attribute. The value enables the CoreOS virtual machine to start automatically when the virtual machine is created. If this is set to false, then the virtual machine is defined with the configured ignition data string, however, it does not get started. It is usually used when the infrastructure (i.e. DNS, DHCP, etc) of the virtual machine is also created by the same pattern. After the pattern deployment is complete, manually start the virtual machine from the IBM Cloud Pak System user interface, or a REST API, or CLI command.

  • IGNITION_DATA_ENCODING:

    The type of encoding that is used for the ignition data. By default, this value is base64 and you cannot change it.

  • IGNITION_DATA:

    The encoded ignition data that is used by the virtual machine when it is first started. Enter the append ignition string for the CoreOS virtual machine. You can get this string from whomever is controlling the control plane for the cluster that this CoreOS virtual machine worker node is going to be a part of.

Add-ons for attached storage support

Some plug-ins, such as for DB2®, allocate additional volumes automatically. In other cases you can attach an add-on disk resource that allocates and mounts an additional volume for you. These volumes are tied to the deployment, meaning they cannot be detached, and they are deleted when the deployment is deleted.

The Default attach block disk add-on is referred to as attached storage, and provides different capabilities. This type of add-on allocates attached storage to virtual machines at deploy time. Existing attached storage can also be mounted at deploy time.

After deployment, attached storage can be unmounted and detached from virtual machines, or can be attached and mounted again as needed. Attached storage is not deleted when the deployment is deleted.

For backup and restore operations, as well as replication and recovery, attached volumes are managed differently than traditional disks and volumes that are associated with a deployment. Attached storage is not included in snapshots, and can be independently replicated or backed up.

Add-ons for network interface controllers

As a content provider or image creator, you might have multiple network interface controllers that you want configured and enabled when your virtual system pattern is deployed. Typically you can include one or more Default add NIC or Default Windows add NIC add-ons in your selected virtual image part when you create your virtual system pattern to provide this function. When the virtual system pattern is deployed, these add-ons are configured after the virtual machine is started.

Certain virtual image parts might have restrictions on your ability to add add-ons. For example, DataPower® virtual images do not support access to the virtual machine by using SSH. Because of this restriction, most add-ons, including Default add NIC and Default Windows add NIC, cannot be added to this type of image. If you attempt to include an add-on to this type of image, the add-on is not added, and the following error message is displayed:
Neither script package nor add-ons can be added to this kind of image part.

In this situation, you need to define the number of network interface controllers that you need in your OVA image file. These multiple NICs are then configured as part of the initial activation of the virtual machine, instead of being configured through SSH (or RXA/SMB, for virtual machines running Windows) after the virtual machine is started. This type of NIC is referred to as a Default configure NIC. This is not an executable script like the Default add NIC or Default Windows add NIC add-on.

When you include a virtual image part with multiple NICs defined in your virtual system pattern, the NICs are also shown in the graphical display of the virtual image part, and you can configure them as needed, or delete NICs that you do not need. To add more NICs to the image, select the Default configure NIC add-on from the available list in the Pattern Editor. These NICs are then configured during initial activation of the VM when the pattern is deployed.
Important: The Default configure NIC add-on can have an impact on computer name and host name assignment because the computer name and host name are derived from the DNS domain name that is given to the non-management NIC. When an extra non-management NIC is introduced by the Default configure NIC add-on during image deployment, the system might choose to get the computer name and host name from a non-management NIC with an undesired DNS domain name.

The Delete icon is disabled for the Default configure NIC add-on.

To summarize:
  • Use the Default add NIC add-on with most virtual image parts that support by using SSH (or, similarly, use Default Windows add NIC for Windows parts that support by using RXA/SMB) to run the add-on scripts after initial activation of the virtual machine during deployment.
  • Use the Default configure NIC add-on for virtual images like DataPower that do not support an ssh connection. You can define the number of NICs as part of the OVA image file so that their scripts are run and configured as part of the initial activation of the VM. Select the Default configure NIC add-on to add more network interface controllers to your image part as needed.
ADD ON Platform Variant
Db2 VIP AIX add NIC POWER
Db2 VIP Linux add NIC INTEL
Note: The above NIC add-on packages are installed along with IBM DB2 with BLU Acceleration Pattern Type version 1.2.3.0.
Use case: These Db2 VIP NIC add-ons are to be used to configure Virtual IPs for Db2 HADR patterns.
  • The NIC add-on should only be attached to the primary VM.
  • One NIC add-on reserves and provides one IP.
  • User needs to explicitly provide the database name for which virtual IP needs to be configured. This is done through the input field of the NIC add-on.
  • In a multi-rack deployment environment, the sub-net address of IPs on both racks should be the same when utilizing this Db2 VIP NIC add-on