Virtual system patterns

VirtualSystemPatterns object

>>> help(deployer.virtualsystempatterns)

VirtualSystemPattern object

>>> help(deployer.virtualsystempattern)

VirtualSystemPattern attributes

patternversion

The pattern version, which can be any string. This attribute is read-only.

Note: The version attribute that was available before Cloud Pak System Version 2.0.0.0, refers to the pattern type version, not the pattern version.

readonly

Boolean value that is set to true if the pattern is read-only, and false otherwise. This attribute is read-only.

VirtualSystemPatterns methods

Create a virtual system pattern by using a Python dictionary (dict), a JSON file, or a compressed file.

Format: deployer.virtualsystempatterns.create(file)

This example passes the method a Python dictionary (dict) that contains the pattern application model:

>>> json={"model":{"name":"Test virtual system pattern", "patterntype":"vsys", "version":"1.0", "patternversion":"1.0"}}
>>> deployer.virtualsystempatterns.create(json)

This example passes the method a JSON file that contains the pattern application model:

>>> deployer.virtualsystempatterns.create("F:\\cli\\testJson.json") 

This example passes the method an exported pattern application model that was saved to a compressed file (.zip):

>>> deployer.virtualsystempatterns.create("F:\\cli\\test.zip")

If you specify a JSON or compressed file, you can also specify one or more of these optional parameters:

name

Specifies the pattern name, which overrides the pattern name that is specified in the model.

patternversion

Specifies the virtual system pattern version, which overrides any pattern version that is specified in the model. The patternversion is set to 1.0 by default if it is not specified. This parameter can be set to any string.

replace

Include this parameter and set it to true to replace an existing virtual system pattern with the same name and version. If this parameter is not included, or is set to false, the operation fails if the pattern exists.

Note: The patternversion and replace parameters are not currently supported for use with virtual application patterns.

Example:

>>> deployer.virtualsystempatterns.create("F:\\cli\\vsys.zip", name = "Test", patternversion = "2.0", replace = True)

List all virtual system patterns.

Format: deployer.virtualsystempatterns

Example:

>>> deployer.virtualsystempatterns

Get a single virtual system pattern by index.

Format: deployer.virtualsystempatterns[index]

Example:

>>> deployer.virtualsystempatterns[0] 

Search for a virtual system pattern by the pattern name

Format: deployer.virtualsystempatterns["pattern_name"]

Example:

>>> deployer.virtualsystempatterns["Red Hat Satellite Server"] 

If you only specify a portion of the pattern name, the command returns all patterns that have that text string as part of the pattern name.

For example, to return all patterns that include the string Red Hat in the pattern name, run the command:

>>> deployer.virtualsystempatterns["Red Hat"] 

Search for virtual system patterns with a filter (Python dictionary)

Format: deployer.virtualsystempatterns.list(filter in dict format)

Example:

>>> deployer.virtualsystempatterns.list({'app_name':'try1'})

Share a pattern with another user

Format: deployer.virtualsystempatterns.get(pattern ID).shareuser(user name,access rights)

Example:

>>> deployer.virtualsystempatterns.get("a-f4979c44-5a4f-42c0-bbbe-26a91a5a13cc").shareuser("tester","F")

Share a pattern with another group

Format: deployer.virtualsystempatterns.get(pattern ID).sharegroup(group name,access rights)

Example:

>>> deployer.virtualsystempatterns.get("a-f4979c44-5a4f-42c0-bbbe-26a91a5a13cc").sharegroup("users","F")

Export the specified virtual system pattern.

Format: deployer.virtualsystempatterns[0].download(file path)

Example:

>>> deployer.virtualsystempatterns[0].download("C:\\sample.zip") 

If you want to export or import a virtual system pattern and include the referenced assets, use the export_artifacts and import_artifacts methods from the deployer module. For more information, see Exporting and importing virtual system patterns and artifacts.

Update the specified virtual system pattern.

Format: deployer.virtualsystempatterns.get(ID).update(file path)

Example:

>>> deployer.virtualsystempatterns.get("a-514a41").update("C:\\sample.zip") 

List the images, script packages, add-ons, software components (plug-ins) and pattern components that are associated with a pattern.

Format: deployer.virtualsystempatterns.listAssets()

Example:

>>> pattern = deployer.virtualsystempatterns[0]
>>> pattern.listAssets()

The output of the listAssets() method is a JSON object with each type of asset that is associated with the pattern.

Clone a virtual system pattern from an existing virtual system pattern.

Format: deployer.virtualsystempatterns.get(ID).clone(name)

Example:

>>> deployer.virtualsystempatterns.get("a-514a41").clone("clonedTest") 

Deploy the specified virtual system pattern.

Format: deployer.virtualsystempatterns.get(ID).deploy(deployment name, cloud object or environment dictionary, certificate file (optional), parameters (optional))

There are two options when you deploy a virtual system pattern through the command-line interface:

1. Deploy the virtual system pattern with the placement that is determined by the system, if applicable, or by not using placement if it is not supported by the virtual system pattern. To deploy the virtual system pattern with this method, call the deploy method and do not include the placement_only parameter, or set it to False.
2. Modify the placement before you deploy the virtual system pattern, and use the modified placement for the deployment. To use this method, the deployment must be called in two phases:
   • First, call the deploy method with the placement_only parameter set to True to generate the placement and topology. This call generates a Placement object without deploying the pattern. You can modify this object to change the placement for the pattern before it is deployed.

     This parameter tells the system to generate a placement for the deployment, which is returned in response body. You can modify this placement before you pass it to the system in the second phase to deploy the pattern.

   • Then, call the deployPlacement method and pass it a dictionary object with these keys:

     placement

     This key is required. The value represents the final Placement object. The placement settings that are specified in this object are used for the deployment.

     addon_parameters

     This key is optional. Use this key to specify parameters for the add-ons in the pattern, such as the volume ID for a Default attach block disk add-on.

     topology_parameters

     This key is optional. Use this key to specify parameters for the topology, such as the IBM Spectrum Scale volume name.

This method accepts these four parameters:

1. name: Required. The name for the instance.
2. Cloud object or dictionary object: Required. You can use a cloud object or a dictionary object to describe the environment profile. The environment profile dictionary object contains these keys:

   environment_profile

   Required. An environment profile object.

   placement_only

   Optional. When placement_only is present and set to True, a Placement object is returned without deploying the pattern. You can modify the placement of the deployment by modifying this object. Then, call the deployPlacement method and pass it the modified object to use the modified settings for the deployment.

   cloud_group

   A Cloud object in the environment_profile. This attribute is optional if the pattern supports placement.

   ip_group

   An IPGroup object in the cloud_group object. This attribute is optional if the pattern supports placement.

   ip_version

   Optional. Valid values are 'IPv4' and 'IPv6'. The default value is 'IPv4'.

   os

   Optional. Operating system type. Valid values are "Linux®" and "Windows".

   productkey

   License key for the Windows Operating System. This parameter is only required when the os parameter is set to "Windows".

   password

   Windows password for Windows virtual machines. This parameter is only required when the os parameter is set to "Windows".

   The environment profile dictionary format is:

   {
   'environment_profile': <env_profile_obj> or <env_profile_id>
   'placement_only': True or False,
   'cloud_group': <cloud_group_obj> or <cloud_group_id>
   'ip_group': <ip_group_obj> or <ip_group_id>
   'ip_version': 'IPv4' or 'IPv6' 
    }

3. file path of the public key for the instance: Optional. You can use ssh-keygen to generate SSH keys and save the public key in a file.
4. A dictionary object (dict) for parameterized deployment.
   The format for <params> is:

   { "node_link_id.attributeId": attributeValue
     "groups":{"node_link_id.groupId": True/False} (optional) }. 

   You can use the listConfig method to determine which parameters are configurable. For example, mypattern.listConfig().

   You must specify "groups" if there is group definition in the plug-in metadata.

   Example of a one-stage deployment:

   sample= deployer.virtualsystempatterns.get('a-b62aeddb-6b43-4421-a0b6-df41b44c5407')
   env=deployer.environmentprofiles[0]
   cloud = env.clouds.keys()[0]
   ipgroup=env.clouds[cloud].ipgroups.keys()[0]
   deployOptions = {
       "environment_profile" : env,
       "cloud_group": cloud,
       "ip_group": ipgroup,
       "ip_version": "IPv4"
   }
   vsys = sample.deploy('env_test', deployOptions)

Note:

• Because placement is handled by the system, you do not have to specify a cloud group or IP group if an environment profile is specified. If the pattern cannot use placement, then the cloud group and IP group parameters are required. For example, if some of the plug-ins in the pattern do not require Foundation 2.1, the application cannot use placement. In this scenario, the cloud group and IP group are required. If you do not specify these parameters for a pattern that cannot use placement, the deployment fails.
• If "placement_only":True is provided, but placement is not supported for the pattern, that parameter is ignored by the system. The pattern is deployed as if the placement_only was not specified, or was set to False.

Example of a two-stage deployment where the placement object is not modified:

>>> deploymentOptions = { "environment_profile":env, "placement_only":True }
>>> sys=deployer.virtualsystempatterns.list({"sys_name":"Sample System"})[1]
>>> vsys=sys.deploy("test",deploymentOptions)    // First stage deployment that returns placement object
>>> p=vsys._getPlacement()
>>> vsys.deployPlacement({'placement':p})    // Second stage deployment using the returned placement.

Example of a two-stage deployment where the placement object is modified:

>>> deploymentOptions = { "environment_profile":env, "placement_only":True }
>>> sys=deployer.virtualsystempatterns.list({"sys_name":"Sample System"})[1]
>>> vsys=sys.deploy("test",deploymentOptions) // First stage deployment to collect placement
>>> p=vsys._getPlacement()

Modify the placement object as needed. Then call deployPlacement and pass it the updated placement object:

>>> vsys.deployPlacement({'placement':p}) // Second stage of the deployment with updated placement

Example of a two-stage deployment where the placement object is modified and the optional topology_parameters key is used:

>>> sample= deployer.virtualsystempatterns.get('a-b62aeddb-6b43-4421-a0b6-df41b44c5407') // get your pattern
>>> env=deployer.environmentprofiles.list({"name":"System36"})[0]  // get env profile
>>> deployOptions={"environment_profile":env, "placement_only":True}  // set deploy options and other parameters
>>> v=sample.deploy("test",deployOptions, sshFile, params)  // deploy first stage with sshFile and GPFS parameters
>>> p=v.getPlacement()  // get placement
>>> deployOptionsForSecondStage={'placement':p, 'topology_parameters':{"GPFS-Manager.GPFS_Manager.Volume_Name_Main":["c0291f19-516a-4aeb-b9e1-351d913937c9"]}}
>>> v.deployPlacement(deployOptionsForSecondStage)  // deploy final

Make the pattern read-only so that it cannot be modified.

Format: deployer.virtualsystempatterns[index].makeReadOnly(check_unlocked_components)

Set the optional check_unlocked_components parameter to True to check for unlocked components before the pattern is made read-only, or False (the default value) to skip that check. If this parameter is set to True, the command fails if the pattern contains any unlocked script packages, add-ons, or images.

Note:

• The command fails if the pattern is already read-only.
• If the check_unlocked_components parameter is omitted or set to False, any unlocked script packages, add-ons, or images in the pattern can still be modified even though the pattern itself is read-only.

Important: Making a pattern read-only cannot be undone.

Examples:

>>> deployer.virtualsystempatterns[0].makeReadOnly()

>>> deployer.virtualsystempatterns[0].makeReadOnly("check_unlocked_components" : True)

Delete the specified virtual system pattern.

Format: deployer.virtualsystempatterns.delete(ID)

>>> deployer.virtualsystempatterns.delete("a-6aa5bf17-0c1e-457c-b135-7c8d19401109")