Virtual system instances

Use the command-line interface to administer virtual system instances .

Note: The virtualsysteminstances object is supported only for use with instances that were deployed from virtual system patterns, which you access through Patterns > Virtual System Instances. It is not supported for use with instances that were deployed from classic virtual system patterns, which you access through Patterns > Virtual System Instances (Classic).

`VirtualSystemInstance` object

A VirtualSystemInstance object represents a particular virtual system instance defined on PureApplication® Software. Use the VirtualSystemInstance object to query and manipulate the virtual system instance definition. Attributes of the virtual system instance and relationships between the virtual system instance and other resources on PureApplication Software are represented as Jython attributes on the VirtualSystemInstance object. Manipulate these Jython attributes using standard Jython mechanisms to make changes to the corresponding data on PureApplication Software. To get help for the VirtualSystemInstance object, pass it as an argument to the help() function, as shown in the following example:

>>> help(deployer.VirtualSystemInstance)

Virtualsysteminstances object

A virtualsysteminstances object represents the collection of virtual system instances that are defined to PureApplication Software. Objects of this type are used to create, iterate over, list and search for virtual system instances. Objects of this type are used to create, delete, iterate over, list and search for virtual system instances on IBM® PureApplication Software. The virtualsysteminstances object supports methods that are not available with the VirtualSystems object.

Help is available on the command-line interface for the virtualsysteminstances object. To get help, pass the virtualsysteminstances object as an argument to the help() function.

Example:

>>> help(deployer.virtualsysteminstances)

Methods

The VirtualSystemInstance and VirtualSystemInstances object have the following methods:

List all virtual systems

Format: deployer.virtualsysteminstances or deployer.virtualsysteminstances.list

Sample output:

>>> deployer.virtualsysteminstances()
[
{
"app_id": "a-f0049cf6-8f58-4da0-a4d9-f00000a08490",
"app_type": "application",
"appmodel": "https://10.102.180.64:9444/storehouse/user/deployments/d-15293b
0d-66bb-4d87-8d4d-3664e985fb6d/appmodel.json",
"deployment": "https://10.102.180.64:9444/storehouse/user/deployments/d-1529
3b0d-66bb-4d87-8d4d-3664e985fb6d/deployment.json",
"deployment_name": "Sample JEE web application 1",
"id": "d-15293b0d-66bb-4d87-8d4d-3664e985fb6d",
"monitorings": (nested object),
"operations": (nested object),
"role_error": False,
"start_time": "2011-03-11T19:08:39.489Z",
"status": "RUNNING",
"topology": "https://10.102.180.64:9444/storehouse/user/deployments/d-15293b
0d-66bb-4d87-8d4d-3664e985fb6d/topology.json"
},
{
"app_id": None,
"app_type": None,
"appmodel": "https://10.102.180.64:9444/storehouse/user/deployments/d-4c59d3
31-de27-4b13-9ce1-5c7ec0d19913/appmodel.json",
"deployment": "https://10.102.180.64:9444/storehouse/user/deployments/d-4c59
d331-de27-4b13-9ce1-5c7ec0d19913/deployment.json",
"deployment_name": None,
"id": "d-4c59d331-de27-4b13-9ce1-5c7ec0d19913",
"monitorings": (nested object),
"operations": (nested object),
"role_error": True,
"start_time": "2011-03-11T18:59:48.779Z",
"status": "RUNNING",
"topology": "https://10.102.180.64:9444/storehouse/user/deployments/d-4c59d3
31-de27-4b13-9ce1-5c7ec0d19913/topology.json"
}
]

Search for virtual system instances with a filter(dict format):

Format: deployer.virtualsysteminstances.list(<filter in dict format>)

Example: >>> deployer.virtualsysteminstances.list({'app_type':'application'})

Sample output:

>>> deployer.virtualsysteminstances.list({'app_type':'application'}) 
[{
"app_id": "a-f0049cf6-8f58-4da0-a4d9-f00000a08490",
"app_type": "application",
"appmodel": "https://10.102.180.64:9444/storehouse/user/deployments/d-15293b0d
-66bb-4d87-8d4d-3664e985fb6d/appmodel.json",
"deployment": "https://10.102.180.64:9444/storehouse/user/deployments/d-15293b
0d-66bb-4d87-8d4d-3664e985fb6d/deployment.json",
"deployment_name": "Sample JEE web application 1",
"id": "d-15293b0d-66bb-4d87-8d4d-3664e985fb6d",
"monitorings": (nested object),
"operations": (nested object),
"role_error": False,
"start_time": "2011-03-11T19:08:39.489Z",
"status": "RUNNING",
"topology": "https://10.102.180.64:9444/storehouse/user/deployments/d-15293b0d
-66bb-4d87-8d4d-3664e985fb6d/topology.json"
}]

Get a single virtual system instance by index:

Format: deployer.virtualsysteminstances[<index>]

Example: >>>deployer.virtualsysteminstances[0]

Sample output:

>>>deployer.virtualsysteminstances[0]
{
"app_id": "a-f0049cf6-8f58-4da0-a4d9-f00000a08490",
"app_type": "application",
"appmodel": "https://10.102.180.64:9444/storehouse/user/deployments/d-15293b
0d-66bb-4d87-8d4d-3664e985fb6d/appmodel.json",
"deployment": "https://10.102.180.64:9444/storehouse/user/deployments/d-1529
3b0d-66bb-4d87-8d4d-3664e985fb6d/deployment.json",
"deployment_name": "Sample JEE web application 1",
"id": "d-15293b0d-66bb-4d87-8d4d-3664e985fb6d",
"monitorings": (nested object),
"operations": (nested object),
"role_error": False,
"start_time": "2011-03-11T19:08:39.489Z",
"status": "RUNNING",
"topology": "https://10.102.180.64:9444/storehouse/user/deployments/d-15293b
0d-66bb-4d87-8d4d-3664e985fb6d/topology.json"
}

Get a single virtual system with a deployment ID (depl_id)

Format: deployer.virtualsysteminstances.get(<depl_id>)

Example: >>> deployer.virtualsysteminstances.get("d-15368912-20db-4d65-958b-36f54fa1e462")

Sample output:

>>> deployer.virtualsysteminstances.get("d-15368912-20db-4d65-958b-36f54fa1e462") 
{
"app_id": "a-f0049cf6-8f58-4da0-a4d9-f00000a08490",
"app_type": "application",
"appmodel": "https://10.102.180.64:9444/storehouse/user/deployments/d-15293b0d
-66bb-4d87-8d4d-3664e985fb6d/appmodel.json",
"deployment": "https://10.102.180.64:9444/storehouse/user/deployments/d-15293b
0d-66bb-4d87-8d4d-3664e985fb6d/deployment.json",
"deployment_name": "Sample JEE web application 1",
"id": "d-15293b0d-66bb-4d87-8d4d-3664e985fb6d",
"monitorings": (nested object),
"operations": (nested object),
"role_error": False,
"start_time": "2011-03-11T19:08:39.489Z",
"status": "RUNNING",
"topology": "https://10.102.180.64:9444/storehouse/user/deployments/d-15293b0d
-66bb-4d87-8d4d-3664e985fb6d/topology.json"
}

Show vm instance details of a deployed system

Format: (virtualsysteminstance).vminstances()

Example: >>> deployer.virtualsysteminstances.get("d-2e0c8abb-373f-46fc-a05f-a255af3d3120").vminstances()

Sample output:

>>> deployer.virtualsysteminstances[0].vminstances()

{
"app_id": "d-2e0c8abb-373f-46fc-a05f-a255af3d3120",
"app_type": "application",
"creator": "u-0",
"creator_name": "cbadmin",
"deployment_name": "Sample JEE web application",
"instances": (nested object),
"role_error": False,
"start_time": "2011-08-17T21:16:59.266Z",
"status": "RUNNING",
"virtual_system": (nested object)
}

Get placement recommendation

Retrieve placement recommendation object from a placement-only deployment.

Format: deployer.virtualsysteminstances.get(<depl_id>).getPlacement()

Example: deployer.virtualsysteminstances.get("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c").getPlacement()

Retrieve the topology from a placement-only deployment

Format: deployer.virtualsysteminstances.get(<depl_id>).getTopology()

Example: deployer.virtualsysteminstances.get("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c").getTopology()

Retrieve the add-ons of the pattern that is being deployed

This will be part of returned object of a placement-only deployment.

Format: deployer.virtualsysteminstances.get(<depl_id>).getAddons()

Example: deployer.virtualsysteminstances.get("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c").getAddons()

Perform final deployment after placement-only deployment.

This method accepts a dictionary object containing the following keys:

placement: This key is required. The value represents the final placement object.
addon_parameters: This key is optional.
topology_parameters: This key is optional.

Format: deployer.virtualsysteminstances.get(<depl_id>).deployPlacement(dict object with keys)

Example: deployer.virtualsysteminstances.get("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c").deployPlacement({'placement':'placement_object'})

Modify an instance's expiration time

Provide the new time in the form of milliseconds since the Epoch.

Format: deployer.virtualsysteminstances.get(<depl_id>).setExpirationTime(<expiration time>)

Example:

 >>>deployer.virtualsysteminstances.get('d-86148d3c-8e85-42f0-b975-db75e84b1dd7').setExpirationTime('10000000000')

Add time to an instance's expiration.

Provide the number of hours to be added.

Format: deployer.virtualsysteminstances.get(<depl_id>).addExpirationTime(<expiration time>)

Example:

 >>>deployer.virtualsysteminstances.get('d-86148d3c-8e85-42f0-b975-db75e84b1dd7').addExpirationTime('1000')

Return an instance's expiration time in milliseconds since the Epoch.

Format: deployer.virtualsysteminstances.get(<depl_id>).getExpirationTime()

Example:

 >>>deployer.virtualsysteminstances.get('d-86148d3c-8e85-42f0-b975-db75e84b1dd7').getExpirationTime()

Return the time that is left until an instance expires, in milliseconds.

Format: deployer.virtualsysteminstances.get(<depl_id>).timeLeft()

Example:

 >>>deployer.virtualsysteminstances.get('d-86148d3c-8e85-42f0-b975-db75e84b1dd7').timeLeft()

Create a snapshot for an instance

Format: deployer.virtualsysteminstances.get(<depl_id>).createSnapshot()

Example:

 >>>deployer.virtualsysteminstances.get('d-86148d3c-8e85-42f0-b975-db75e84b1dd7').createSnapshot()

Get the snapshots for an instance

Format: deployer.virtualsysteminstances.get(<depl_id>).listsnapshots()

Example:

 >>>deployer.virtualsysteminstances.get('d-86148d3c-8e85-42f0-b975-db75e84b1dd7').listsnapshots()

Revert a snapshot description for an instance

Revert a snapshot description for an instance. This method accepts the following parameter:

snapshotid: The snapshotid to revert. This parameter is required.

Format: deployer.virtualsysteminstances.get(<depl_id>).restoresnapshot("bf89b2e871cfa30")

Example:

 >>>deployer.virtualsysteminstances.get('d-86148d3c-8e85-42f0-b975-db75e84b1dd7').restoresnapshot("bf89b2e871cfa30")

Update a snapshot description for an instance

Update a snapshot description for an instance. This method accepts the following parameters:

snapshotid: The snapshotid to delete. This parameter is required.
desc: The description of the snapshot. This parameter is required.

Format: deployer.virtualsysteminstances.get(<depl_id>).updatesnapshot("bf89b2e871cfa30", "test")

Example:

 >>>deployer.virtualsysteminstances.get('d-86148d3c-8e85-42f0-b975-db75e84b1dd7').updatesnapshot("bf89b2e871cfa30", "test")

Disable or enable snapshots for an instance

This method takes one parameter: a string representation of disable or enable: 'Y' for disable, 'N' for enable.

Format: deployer.virtualsysteminstances.get(<depl_id>).enablesnapshot('Y')

Example:

 >>>deployer.virtualsysteminstances.get('d-86148d3c-8e85-42f0-b975-db75e84b1dd7').enablesnapshot('Y')

Delete a snapshot for an instance

Delete a snapshot for an instance. This method accepts the following parameter:

snapshotid: The snapshotid to delete. This parameter is required.

Format: deployer.virtualsysteminstances.get(<depl_id>).deletesnapshot("bf89b2e871cfa30")

Example:

 >>>deployer.virtualsysteminstances.get('d-86148d3c-8e85-42f0-b975-db75e84b1dd7').deletesnapshot("bf89b2e871cfa30")

Terminate a deployed system

Format: deployer.virtualsysteminstances.terminate(<depl_id>)

Example: >>> deployer.virtualsysteminstances.terminate("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c")

Sample output:

>>> deployer.virtualsysteminstances.terminate("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c") 
>>>

Delete a deployed system

Format: deployer.virtualsysteminstances.get(<depl_id>).delete()

Example: deployer.virtualsysteminstances.get("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c").delete()

Sample output:

>>> deployer.virtualsysteminstances.delete("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c") 
>>>

Note: You can specify that you do not want to delete deployment history by calling deployer.virtualsysteminstances.get(<depl_id>).delete(False).

Update the priority of a deployed system

Format: deployer.virtualsysteminstances.get(<depl_id>).updatePriority("high"|"medium"|"low")

Sample output:

>>> vs = deployer.virtualsysteminstances.get("d-7b5ea7ab-5cca-4994-8682-034c98798a6b")    
>>> vs.priority
u'high'
>>> vs.updatePriority("low")
>>> vs.priority
u'low'
>>>

Note: Virtual system instances report their priority as a string.

Share a virtual system with another user

Format: deployer.virtualsysteminstances.get(<depl_id>).shareuser(<username>,<access rights>)

Example:

>>>deployer.virtualsysteminstances.get("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c").shareuser("tester","F")

Share a virtual system with another group

Format: deployer.virtualsysteminstances.get(<depl_id>).sharegroup(<username>,<access rights>)

Example:

 >>>deployer.virtualsysteminstances.get("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c").sharegroup("users","F")

Start a virtual machine

Format: deployer.virtualsysteminstances.get(<depl_id>).startvm(<node_id>)

Example:

 >>>deployer.virtualsysteminstances.get('d-86148d3c-8e85-42f0-b975-db75e84b1dd7').startvm('database-db2.11304523030092')

Get the virtual machine roles

Format: deployer.virtualsysteminstances.get(<depl_id>).operationroles(<node_id>)

Example:

>>>deployer.virtualsysteminstances.get('d-86148d3c-8e85-42f0-b975-db75e84b1dd7').operationroles('database-db2.11304523030092')

Get the configuration metadata and attributes of the virtual machine role

Format: deployer.virtualsysteminstances.get(<depl_id>).configurationattributes(<node_id>)

Example:

>>>deployer.virtualsysteminstances.get('d-86148d3c-8e85-42f0-b975-db75e84b1dd7').configurationattributes('database-db2.11304523030092')

Get the operation metadata of the virtual machine role

Format: deployer.virtualsysteminstances.get(<depl_id>).operationmeta(<node_id>)

Example:

>>>deployer.virtualsysteminstances.get('d-86148d3c-8e85-42f0-b975-db75e84b1dd7').operationmeta('database-db2.11304523030092')

Stop a virtual machine

Format: deployer.virtualsysteminstances.get(<depl_id>).stopvm(<node_id>)

Example:

>>>deployer.virtualsysteminstances.get('d-86148d3c-8e85-42f0-b975-db75e84b1dd7').stopvm('database-db2.11304523030092')

Refresh the cached attribute values

Note: Call this method before getting the status of the instance.

Format: deployer.virtualsysteminstances.get(<depl_id>).refresh()

Example:

>>>deployer.virtualsysteminstances.get('d-12bbc2a0-9e6e-453c-b6bc-fce578fc5873').refresh()

Put a virtual system instance in maintenance mode

Format: deployer.virtualsysteminstances.get(<depl_id>).maintain()

Example:

>>>deployer.virtualsysteminstances.get('d-12bbc2a0-9e6e-453c-b6bc-fce578fc5873').maintain()

Resume a virtual system instance from maintenance mode

Format: deployer.virtualsysteminstances.get(<depl_id>).resume()

Example:

>>>deployer.virtualsysteminstances.get('d-12bbc2a0-9e6e-453c-b6bc-fce578fc5873').resume()

Upgrade the pattern type of a virtual system instance to the latest

Format: deployer.virtualsysteminstances.get(<depl_id>).upgrade()

Example:

>>>deployer.virtualsysteminstances.get('d-12bbc2a0-9e6e-453c-b6bc-fce578fc5873').upgrade()

Check whether plug-ins with a higher version are available.

Format: deployer.virtualsysteminstances.get(<depl_id>).checkupgrade()

Example:

>>>deployer.virtualsysteminstances.get('d-12bbc2a0-9e6e-453c-b6bc-fce578fc5873').checkupgrade()

Commit the upgrade of an instance

Format: deployer.virtualsysteminstances.get(<depl_id>).commit()

Example:

>>>deployer.virtualsysteminstances.get('d-12bbc2a0-9e6e-453c-b6bc-fce578fc5873').commit()

Revert the upgrade of an instance

Format: deployer.virtualsysteminstances.get(<depl_id>).revert()

Example:

>>>deployer.virtualsysteminstances.get('d-12bbc2a0-9e6e-453c-b6bc-fce578fc5873').revert()

List the fixes for the virtual system instance

Format: deployer.virtualsysteminstances.get(<depl_id>).findFixes()

Example:

>>> vsysinst0 = deployer.virtualsysteminstances[0]
>>> vsysinstfixes = vsysinst0.findFixes()

Example output from this command:

[
{
   "applicableto": [ "SourceNode" , "TargetNode"],
   "appliedto": [  ],
   "created": 1394115928843,
   "currenteditionid": 140,
   "currentmessage": None,
   "currentstatus": "RM01012",
   "description": "",
   "filename": "fix.zip",
   "fixprereqs": [
     {
       "created": 1394115951541,
       "fixid": 61,
       "id": 62,
       "middlewarename": "IBM WebSphere Application Server Liberty",
       "middlewareversion": "8.5.5.0",
       "updated": 1394115951541
     }
   ],
   "hasservicefile": "TRUE",
   "id": 61,
   "installtype": "WCA",
   "name": "testfix",
   "ownerid": 1,
   "scriptid": 140,
   "severity": "RM10388",
   "target": "APPLICATION",
   "type": "IFIX",
   "updated": 1394447441222
}  ]

Install the specified fixes to the virtual system instance

First, create a Python dictionary object to specify the fixes that you want to install. Then, install the fixes by calling the applyFixes(Python dictionary object) method.

Format: deployer.virtualsysteminstances.get(<depl_id>).applyFixes(Python dictionary object)

Example:

>>> vsysinst0 = deployer.virtualsysteminstances[0]
>>> vsysinstfixes = vsysinst0.findFixes()
>>> fixes = [{"vmtemplate":"SourceNode", "vmfixes":[vsysinstfixes[0] ]  }, {"vmtemplate":"TargetNode","vmfixes": [vsysinstfixes[0] ] } ]
>>> vsysinst0.applyFixes(fixes)

Notes:

You can get the value for vmtemplate, such as SourceNode and TargetNode, from the output of the findFixes() method. For an example, see the entry for the findFixes() method.
If you want to apply a new fix, you must include not only that fix, but also all previously applied maintenance fixes (both emergency fixes and interim fixes) in the Python dictionary object.
If you want to reapply a fix, you must import it again with a different name.

Remove the specified fixes from the virtual system instance

First, create a Python dictionary object to specify the fixes that you want to remove. Then, remove the fixes by calling the removeFixes(Python dictionary object) method.

Format: deployer.virtualsysteminstances.get(<depl_id>).removeFixes(Python dictionary object)

Example:

>>> vsysinst0 = deployer.virtualsysteminstances[0]
>>> vsysinstfixes = vsysinst0.findFixes({"appliedto":["SourceNode", "TargetNode"]})
>>> fixes = [{"vmtemplate":"SourceNode", "vmfixes":[vsysinstfixes[0]]}, {"vmtemplate":"TargetNode","vmfixes": [vsysinstfixes[0]]}]
>>> vsysinst0.removeFixes(fixes)

Note: You can get the value for vmtemplate, such as SourceNode and TargetNode, from the output of the findFixes() method. For an example, see the entry for the findFixes() method.

List the fix packs for the virtual system instance

Format: deployer.virtualsysteminstances.get(<depl_id>).findFixpacks()

Example:

>>> vsysinst0 = deployer.virtualsysteminstances[0]
>>> vsysinstfixpacks = vsysinst0.findFixpacks()

Example output from this command:

{
    "candidate_fixpacks": {
        "IBM WebSphere Application Server Network Deployment": [
            {
                "version": "8.5.5.5",
                "fixpack": {
                    "version": "8.5.5.5",
                    "repositoryUrl": "http://[fd8c:215d:178e:17e2:5054:4071:faeb:1b6a]:8585/IMRepository/Compo",
                    "offeringId": "com.ibm.websphere.ND.v85",
                    "installtype": "IM",
                    "offeringVersion": "8.5.5005.20150220_0158"
                }
            }
        ]
    },
    "current_fixpacks": {
        "StandAloneNode": {
            "IBM WebSphere Application Server Network Deployment": {
                "version": "8.5.5.4",
                "fixpack": {
                    "version": "8.5.5.4",
                    "repositoryUrl": "http://[fd8c:215d:178e:17e2:5054:4071:faeb:1b6a]:8585/IMRepository/Compo",
                    "requireInstall": false,
                    "offeringId": "com.ibm.websphere.ND.v85",
                    "installtype": "IM",
                    "middlewareName": "IBM WebSphere Application Server Network Deployment",
                    "offeringVersion": "8.5.5004.20141119_1746"
                }
            }
        }
    }
}

Install the specified fix packs to the virtual system instance

Format: deployer.virtualsysteminstances.get(<depl_id>).applyFixpacks(middleware name, fix pack Version)

Example:

deployer.virtualsysteminstances.get('d-94277ab9-46d2-48e9-bd8c-e7e7f0c2f4c1').applyFixpack("IBM WebSphere Application Server Network Deployment", "8.5.5.5")

Stop a deployed system

Format: deployer.virtualsysteminstances.get(<depl_id>).stop()

Example:

>>>deployer.virtualsysteminstances.get("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c").stop()

Store a stopped system

Format: deployer.virtualsysteminstances.get(<depl_id>).store()

Example:

>>>deployer.virtualsysteminstances.get("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c").store()

Start a deployed system

Format: (virtual system).start()

Example:

>>>deployer.virtualsysteminstances.get("d-0d1ede95-f0cf-4d71-9b2e-ffa3bf80871c").start()

Virtual system instances

VirtualSystemInstance object

Virtualsysteminstances object

Methods

`VirtualSystemInstance` object