Add-ons

You can administer add-ons in the catalog using the Cloud Pak System command-line interface.

AddOns object
AddOn object
AddOn attributes
Addons methods
Addon methods
Archive methods
Environment methods

AddOns object

An AddOns object represents the collection of add-ons defined to Cloud Pak System. Objects of this type are used to create, delete, iterate over, list and search for add-ons on Cloud Pak System. To get help for the AddOns object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.addons)

AddOn object

An AddOn object represents a particular add-on defined on Cloud Pak System. Use the AddOn object to query and manipulate the add-on definition on Cloud Pak System. Attributes of the add-on and relationships between the add-on and other resources on Cloud Pak System are represented as Python attributes on the AddOn object. Manipulate these Python attributes using standard Python mechanisms to make changes to the corresponding data on Cloud Pak System. To get help for the AddOn object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.addon)

AddOn attributes

The AddOn object has the following attributes:

acl

The access control list for this add-on. For additional help on using this object, enter the following command:

>>> help(deployer.acl)

This field is read-only.

archive

An archive object represents the archive file associated with a particular add-on on Cloud Pak System. This object provides mechanisms to query and manipulate the add-on archive on Cloud Pak System. This field is read-only. For more information, see Archive methods.

command

The command to be run for this add-on.

commandargs

The arguments that are passed to the command.

created

The creation time of the add-on, as the number of seconds since midnight January 1, 1970 UTC. When the add-on is displayed, this value is shown as the date and time in the local timezone. This field is read-only.

currentstatus

The current status of the add-on.

currentstatus_text

The textual representation of the currentstatus. This field is read-only.

description

The description of the add-on.

environment

The environment property holds the add-on keys and default values for the add-on. It is used much like a Python dict object, as shown in the following example:

 {
 "addonkey1": "value for addonkey1",
 "addonkey2": "value for addonkey2"
 }
 >>> myaddon.environment['addonkey1']
 'value for addonkey1'
 >>> myaddon.environment['foo'] = 'bar'
 >>> myaddon.environment
 {
 "foo": "bar",
 "addonkey1": "value for addonkey1",
 "addonkey2": "value for addonkey2"
 }
 >>> del myaddon.environment['foo']
 >>> myaddon.environment
 {
 "addonkey1": "value for addonkey1",
 "addonkey2": "value for addonkey2"
 }

This field is read-only. See Environment methods for more information.

id

The ID of the add-on. This field is read-only.

label

The label for the add-on. This field is read-only.

location

The directory, on the virtual machine, into which files for this add-on package are to be placed.

locations

This attribute is present if you used the "location" filter on the list() method to retrieve objects from one or more systems in a multisystem management domain. When present, this attribute is a list of dictionaries with the following keys. One dictionary appears in the list for each system from which this object was retrieved:

isLocal: This boolean value is set to true if the object exists on the local system; otherwise, the object originates at a remote system.
location: This value is a string containing the name of the location in the multisystem domain on which the object resides.
message: If present, this is a status message about connection to the remote location.
metaSignature: This value is a string containing a unique signature for the object's metadata.
signature: This value is a string containing a unique signature for the object.
status: If present, this value is an HTTP status code about connection to the remote location.
subdomain: If present, this value is a string containing the name of the multisystem subdomain in which the system providing this artifact resides.

log

The directory, on the virtual machine, that is to contain the log files generated by this add-on.

name

The name associated with this add-on. Each add-on must have a unique name.

timeout

The maximum amount of time to wait for this add-on to finish running on a virtual machine. Specify the timeout as the number of milliseconds to wait, or 0 to wait indefinitely for the add-on to complete.

type

The type of add-on. This attribute must have a string value equal to one of the following constants:

deployer.DISK_ADDON
deployer.NIC_ADDON
deployer.USER_ADDON

updated

The time the add-on was last updated, as number of seconds since midnight, January 1, 1970 UTC. When the add-on is displayed, this value is shown as the date and time in the local timezone. This field is read-only.

version

The version of the add-on. This attribute is read only.

Restriction: Multiple versions of the same add-on are not supported for use with classic virtual system patterns.

Addons methods

The Addons object has the following methods:

create

Creates an add-on by uploading an add-on archive file. The cbscript.json in the archive file must contain the script package name, add-on type, and can optionally contain the version. This method has one required parameter: archivepath and three optional parameters:

name: Use this parameter to override the add-on name in cbscript.json.
type: Use this parameter to override the add-on type in cbscript.json. Valid values are: ADDON_NIC, ADDON_DISK, and ADDON_USER.
version: Use this parameter to override the add-on version in cbscript.json.
replace: Boolean value. If this parameter is present and set to True, replace only the add-on archive if the add-on exists and is unlocked.

Examples:

Create an add-on by uploading an add-on archive file:

>>> deployer.addons.create({'archivepath' : 'C:\\myScriptsDirectory\\myArchive.zip'})

Create an add-on by uploading an add-on archive file and override the add-on name that is defined in cbscript.json:

>>> deployer.addons.create({'archivepath' : 'C:\\myScriptsDirectory\\myArchive.zip', 'name' : 'newName'})

Create an add-on by uploading an add-on archive file and override the add-on name and version that is defined in cbscript.json:

>>> deployer.addons.create({'archivepath' : 'C:\\myScriptsDirectory\\myArchive.zip', 'name' : 'newName', 'version' : 'newVersion'})

Create an add-on by uploading an add-on archive file and override the add-on type that is defined in cbscript.json:

>>> deployer.addons.create({'archivepath' : 'C:\\myScriptsDirectory\\myArchive.zip', 'type' : 'ADDON_NIC'})

Replace only the archive file if the add-on exists:

>>> deployer.addons.create({'archivepath' : 'C:\\myScriptsDirectory\\myArchive.zip', 'replace' : False})

list

Lists the add-ons on this system or, optionally, on other systems in the multisystem management domain to which you have access. This method takes one optional parameter, which is a dictionary of attributes on which to filter.

Examples:

>>> deployer.addons.list()

You can filter by type:

>>> deployer.addons.list({'type': 'ADDON_NIC'})

With appropriate privileges, you can display all add-ons in your multisystem subdomain:

>>> deployer.addons.list({'location': 'domain'})

With the location option, you can also display connection status in your multisystem subdomain. The connection status data with artifact name None is added to the list of add-ons containing a nested object name location.

>>> deployer.addons.list({'location': 'domain',
'includeStatusData': 'true'})

Addon methods

The Addon object has the following methods:

copyTo

Given appropriate permission, copy an add-on from this system to another system in your multisystem management domain. This method accepts one parameter, a dictionary, with the following keys:

location: Set this value to the name of the system to which the resource will be copied.

syncTo

Given appropriate permission, update an existing add-on on another system in your multisystem management domain based on this object. This method accepts one parameter, a dictionary, with the following keys:

location: Set this value to the name of the system to which the resource will be synchronized.
metadataOnly: Optional. If present, set this to true to synchronize only metadata such as access control lists. Set it to false or omit it to synchronize the entire object. If the add-on on the target system is read-only, only metadata can be synchronized.

Archive methods

The Archive object has the following attributes:

get

This method retrieves the archive currently associated with the add-on. This method has one required parameter that indicates where the add-on archive should be saved. It can be either of the following values:

A string containing the name of a file in which to save the archive. The .zip file type is automatically appended to the file name if the file name does not end in .zip.
A Python file object. You must ensure that the file object can correctly handle binary data.

The add-on archive is returned in a compressed file format, as shown in the following example:

>>> myaddon.archive.get('/path/to/foo.zip')

__lshift__

This method is invoked implicitly when the Archive object is used as the left argument of a left shift operator (<<). It calls set() with the right argument of the operator, as shown in the following example:

>>> myaddon.archive << '/path/to/file'

__rshift__

This method is invoked implicitly when the Archive object is used as the left argument of a right shift operator (<<). It calls get() with the right argument of the operator, as shown in the following example:

 >>> myaddon.archive >> '/path/to/file.zip'

set

This method sets the archive associated with the add-on. It has one required parameter that indicates the source of the add-on archive to be uploaded. It can be either of the following values:

A string containing the name of a file from which to get the archive.
A Python file object.

You must ensure that the file object can correctly handle binary data, as shown in the following example:

>>> myaddon.archive.set('/path/to/foo')

Environment methods

The Environment object has the following attributes:

isDraft: Indicates if this add-on is in draft mode.
isReadOnly: Indicates if this add-on is read-only.
makeReadOnly: Makes this add-on read-only. When the add-on is read-only, it cannot be modified.
clone: Creates a copy of this add-on with all of the same files, fields, and settings. The new add-on has the name provided and an empty ACL.