Skip to main content
Pure1 Support Portal

Using the Pure Storage FlashArray Plugin for vRealize Orchestrator

Executive Summary

Pure Storage provides a RESTful API service on the FlashArray controllers to provide simple and standard API control of the FlashArray. In order to even further simplify the use of the RESTful API service for customers who may not be familiar with leveraging REST, Pure Storage offers a variety of plugins, modules and SDKs in an assortment of platforms in which the user might be more familiar (e.g. PowerShell, Python).

VMware offers a GUI-based orchestration engine called vRealize Orchestrator (vRO)—a tool that provides a mechanism to build workflows that can connect to and control your entire infrastructure. Through default plugins, like REST, SOAP, SSH, PowerShell and many others, vRO delivers a variety of methods to connect to the different cogs in your environment.

Pure Storage offers a FlashArray plugin for vRO that tightly integrates FlashArray provisioning and management with minimal effort. Features like inventory synchronization, built-in workflows, and actions provide most functionality right out of the box. The official VMware support listing can be found here.

Goals and Objectives

The purpose of this document is to overview the features and functions of the Pure Storage FlashArray Plugin for vRealize Orchestrator. In detail:

  • Installation and configuration
  • Inventory
  • Actions
  • Workflows
  • Custom orchestration

Audience

This document is intended for storage, VMware, automation and other types of administrators who wish to use the vRealize Orchestrator platform to manage the Pure Storage FlashArray. Familiarity with the VMware vSphere virtualization platform, vRealize Orchestrator and the FlashArray is recommended but not required before reading this document.

Requirements

The Pure Storage FlashArray plugin for vRealize Orchestrator has the following requirements:

FlashArray Models Purity//FA Version vRealize Orchestrator Versions VMware vCenter
  • FlashArray//X 
  • FlashArray//M
  • FA-400 
  • Purity//FA 4.x and higher
  • 6.0.x Single-Node
  • 7.x Single-Node
  • 7.x Multi-Node
  • 5.5.x
  • 6.0.x
  • 6.5.x

The VMware-integrated workflows require vCenter 6.x as many use SDK calls that are only supported in the 6.x version of the vCenter SDK. In order to use those workflows certain edits will need to be made to the workflows when used with vCenter 5.5. Making custom workflows with vCenter 5.5 is fully supported though by the plugin.

Installation

The Pure Storage FlashArray Plugin for vRealize Orchestrator can be downloaded from the VMware Solution Exchange: https://solutionexchange.vmware.com/store/products/pure-storage-flasharray-plugin-for-vmware-vrealize-orchestrator

The plugin is of type .vmoapp:

vmoapp.png

Installing the FlashArray Plugin with vRO 6.x

  1. Login to your vRO appliance at the following address:
    https://<vRO FQDN or IP>:8283/vco-config/
    vrop1.png
  2. Click on the “Plugins” menu button and then the search icon to find the plugin file. Click “Upload and install” to start the installation.vrop2.png
  3. Accept the EULA.
    vrop3.png
  4. Once accepted the plugin will be installed.
    vrop4.png
  5. You must now restart the core vRO service in order to activate the plugin

    Restarting the core vRO service is a disruptive operation that will kick users out of the vRO client and will terminate running workflows. Be 100% sure that there are no interfering operations before restarting the service.

    vrop5.png

    vRO 6.0.1 and 6.0.2 do not support, by default, the proper security protocol that the FlashArray requires for REST (or any method) communication. The FlashArray requires TLS 1.1 or later. Additional information on how to configure the proper TLS support in vRO can be found in the appendix Appendix I: Enabling TLS 1.1 and 1.2. vRO 6.0.3 and later are fine by default. https://www.vmware.com/support/orchestrator/doc/vrealize-orchestrator-603-release-notes.html 

Installing the FlashArray Plugin with vRO 7.x

  1. Login to your vRO appliance at the following address
    https://<vRO FQDN or IP>:8283/vco-controlcenter/#/


    vrop6.png
  2. Click on the “Plugins” menu button and then the “Browse…” button to find the plugin file. Click “Upload and install” to start the installation.
    vrop7.pngvrop8.png
  3. Accept the EULA.
    vrop9.png
  4. Once accepted the plugin will be installed.
    vrop10.png
  5. You must now restart the core vRO service in order to activate the plugin.
    vrops11.png

Restarting the core vRO service is a disruptive operation that will kick users out of the vRO client and will terminate running workflows. Be 100% sure that there are no interfering operations before restarting the service.

Uninstallation

There is no GUI-based uninstallation of plugins for vRealize Orchestrator—uninstallation requires root access to the bash shell (or Windows host). For uninstallation instructions, please refer to the following VMware Knowledge Base article:

https://kb.vmware.com/kb/2064575

Configuration

When the plugin is installed, a variety of workflows are immediately provided for use. The following categories are available:

  • FlashArray Connection Management—Adding/removing FlashArray connections into vRO.
  • FlashArray Host Management—Adding/removing/changing FlashArray hosts and host groups.
  • FlashArray Management—Configuring FlashArray-level settings.
  • FlashArray Protection Group Management-- Adding/removing/changing FlashArray local snapshot or remote replication policies with Protection Groups.
  • FlashArray REST APIs—Allows for custom and direct API interaction with the FlashArray.
  • FlashArray Snapshot Management—Adding/removing/changing FlashArray snapshots.
  • FlashArray Volume Management—Adding/removing/changing FlashArray volumes.
  • VMware ESXi and FlashArray—Built-in workflows for managing storage in a VMFS environment.

vrops12.png

In the section Built-in Workflows, the majority of these workflows will be explained in more detail. This section will focus on configuration pre-requisites to fully use the plugin. This includes three steps:

  • Adding a certificate for the FlashArray
  • Authenticating a FlashArray
  • Authenticating a vCenter

Adding a FlashArray Certificate to vRealize Orchestrator

The first step is adding the FlashArray certificate to vRO. Run the workflow “Import FlashArray certificate from URL” in the FlashArray Connection Management folder.

vrops13.png

Fill out the FQDN or IP of the FlashArray, if the certificate is self-signed, change the accept certificate with warnings option to “Yes”.  Click submit.

vrops14.png

Note that you may use the default vRO workflows to add a FlashArray certificate if you so choose—you do not need to use the FlashArray-specific certificate workflow. This workflow was provided mainly for convenience.

You can view the certificate in the “Inventory” tab under vRO Configuration -> Keystores -> CA Keystore.

vrops15.png

Adding a FlashArray to vRealize Orchestrator

To add a FlashArray to vRO, navigate to the FlashArray Connection Management folder and start the “Add FlashArray Connection” workflow.

vrops16.png

Fill out the connectivity information for the FlashArray you would like to add.

vrops17.png

The available API versions will auto-populate in the “API Version” entry drop-down after the FlashArray URL is entered and will default to the newest. The recommendation is to keep with the newest API version unless you have a reason to leverage an older API version of the FlashArray REST service. Change the autopopulate to “Yes” to retrieve the REST versions. If nothing populates, ensure the certificate was added and that the FQDN/IP is correct. The FlashArray REST service requires port 443 TCP access to function.

Submit the information and look for the FlashArray to be successfully added—indicated by a green check mark on the workflow run instance.

vrops18.png

Adding a vCenter is an optional task, but if you plan on managing VMware objects (datastores, VMs, etc.) and/or using the VMware-integrated workflows in the FlashArray plugin, it is necessary to have at least one vCenter registered. A full description of the process can be found in VMware documentation.

vrops19.png

Custom Objects and FlashArray Inventory

The FlashArray plugin for vRO introduces a few new object types into vRealize Orchestrator. These objects types have been created to allow end users a simple way to manipulate and manage FlashArray-specific objects in your actions, scripts, and workflows.

vrops20.png

This inventory screen can be accessed from any view in vRO. If an item that has been created does not appear in the inventory, please refresh the vRO interface to have the object populated.

vrops21.png

Destroyed, but not eradicated, objects are not displayed in the vRO inventory. Objects in this state are automatically eradicated from the FlashArray in 24 hours.

Custom Objects

The plugin offers a variety of new object types in to the vRO inventory:

  • PS:FlashArrayConnection
  • PS:FlashArray
  • PS:Volume
  • PS:Snapshot
  • PS:Host
  • PS:HostGroup
  • PS:ProtectionGroup

These objects represent their respective objects on the FlashArray and can be passed in and out of workflows and actions and managed in external applications like vRealize Automation. When passed into scripting objects in vRO they are represented by respective “scripting objects” which provide additional methods to manage and alter the object configurations. More information on managing scripting objects can be found in the section Using Scripting Objects and Methods.

See the section, Building a New Action for more details on using objects.

Read on for a detailed description of these object types:

  • PS:FlashArrayConnection: This is an object that defines a specific connection to a FlashArray and is the highest level object. This object has the following properties:
    • Username—the username of the user who created the connection. If this user is deleted from the FlashArray the connection will be broken.
    • FlashArray Connection—the friendly name specified upon creation of the connection
    • Display name—a combination of the display name and the URI used to connect to the FlashArray.
    • Credentials—a more detailed description of the user name who authenticated the session and an internal session ID for the connection
    • Base URI—the URL used for the REST connection, this will specify the REST version at the end of the URL string

vrops22.png

 

  • PS:FlashArray—an object that represents the FlashArray specified in the FlashArray connection. This information is not tied to a single session. Properties includes:
    • Name—the name of the FlashArray
    • ID—the unique identifier of the FlashArray
    • Display name—this is the friendly name of the FlashArray
    • Version—Purity Operating Environment version
    • Revision—specific Purity version build information

vrops23.png

  • PS:Volume—this is a new object type that represents a FlashArray volume. Properties are:
    • Name—the volume name
    • Size—the provisioned size in bytes of the volume
    • Display name—the volume name (currently will always be the same as the name)
    • Source—if the volume was copied from another volume this will have the source volume name. Will be null if it is an original volume
    • Created—time in UTC format when the volume was created
    • Serial—the serial number of the volume

vrops24.png

  • PS:Snapshot—this is a new object type that represents a FlashArray snapshot. Properties are:
    • Name—the snapshot name—if it is a one off snapshot it will be in the form of <volume name>.<snapshot name> (e.g., “myVolume.mySnapshot”), if it is a snapshot from a protection group, it will be in the form of <protection group name>.< snapshot name >.< volume name> (e.g., “myPGroup.mySnapshot.myVolume”)
    • Size—the size in bytes of the data being preserved by the snapshot
    • Display name—the snapshot name—if it is a one off snapshot it will be in the form of <volume name>.<snapshot name> (e.g., “myVolume.mySnapshot”), if it is a snapshot from a protection group, it will be in the form of <protection group name>.< snapshot name >.< volume name> (e.g., “myPGroup.mySnapshot.myVolume”)
    • Source—the name of the volume the snapshot was created from
    • Serial—the serial number of the snapshot

vrops25.png

  • PS:Host— this is a new object type that represents a FlashArray host. Properties are:
    • Name—the name of the host
    • Display Name—the host name (currently will always be the same as the name)
    • Host Group—the name of the host group if the host is in a host group
    • IQN—the IQNs assigned to this host. This is an array of strings
    • WWN—the WWNs assigned to this host. This is an array of strings.

vrops26.png

  • PS:HostGroup— this is a new object type that represents a FlashArray host group. Properties are:
    • Name—the name of the host group
    • Display Name—the host group name (currently will always be the same as the name)
    • Hosts—a list of the hosts in that host group. This is an array of strings.

vrops27.png

  • PS:ProtectionGroup— this is a new object type that represents a FlashArray protection group. Properties are:
    • Display Name—the name of the protection group. If this is local to the FlashArray it will just be the protection group name. If it is remote to the FlashArray (i.e., replicating to it) it will be in the form of “<FlashArray target name>:<protection group name>” (e.g., “FlashArrayNYC:MyPGroup”
    • Source—the name of the FlashArray the protection group resides on
    • Volumes—the volumes currently in the protection group. If the protection group is remote to the FlashArray the volume name will be appended to the source FlashArray name after a colon (e.g., “FlashArrayNYC:MyVolume”). This is an array of strings.
    • Hosts—the hosts currently in the protection group. If the protection group is remote to the FlashArray the hosts name will be appended to the source FlashArray name after a colon (e.g., “FlashArrayNYC:MyHost”). This is an array of strings.
    • Host Groups—the host groups currently in the protection group. If the protection group is remote to the FlashArray the host group names will be appended to the source FlashArray name after a colon (e.g., “FlashArrayNYC:MyHostGroup”). This is an array of strings.
    • Target—the FlashArrays that the protection group is replicating to and whether that connection is enabled.

vrops28.png

Scripting Objects

The FlashArray plugin also offers scripting objects that allow for easier management of FlashArray provisioning tasks above and beyond the object types mentioned before. Scripting objects offer a variety of methods that provide additional operations that can be executed against that object type. Objects mentioned in the previous section are respective scripting objects when passed into a scriptable task in vRO (JavaScript). Furthermore, there are scripting objects that do not have mapped object types.

The main difference between standard object types and scripting objects, is that object types can be passed between actions and workflows. Scripting objects can only be leveraged in JavaScript for custom operations. Certain scripting objects can be passed out of between actions if it has a corresponding object type.

For a detailed description of scripting objects, please refer to the section Using Scripting Objects and Methods.

Running Workflows from Objects

In the inventory view of vRealize Orchestrator, it is possible to right-click on an object and then run a workflow from that specific object.

For instance, if you click on a FlashArray connection, choose “Run Workflow”.

vrops29.png

Then choose a workflow to run against that FlashArray connection.

vrops30.png

Whichever input matches that input type will be auto-populated with the object you originally clicked on.

vrops31.png

Note that the right-click menu is not an exhaustive list of workflows that take that object type in. It is also not dynamic—creating new workflows that take in that object type will not auto-populate. Requests to add menu options can be sent to Pure Storage, by contacting support@purestorage.com.

Once the wizard is completed, a dialog box will appear until the workflow completes. You can close the box to allow the workflow to run in the background and you can then monitor its process in the normal fashion.

vrops32.png

Built-in Actions

The FlashArray plugin for vRealize Orchestrator includes a variety of actions to make custom workflow creation much easier. These actions are used by the built-in workflows and can also be used by your own workflows.

The plugin actions can be found under the “com.purestorage.flasharray.xxx” namespace.

vrops33.png

Action Descriptions

This section will detail the actions built into the FlashArray plugin for vRealize Orchestrator. There are nine sections:

  • Connection actions
  • Host actions
  • Host group actions
  • Array management actions
  • Protection group actions
  • Custom REST actions
  • Snapshot actions
  • Volume actions
  • VMware actions

Connection Actions

Action name

Description

Inputs

Return value

addFlashArrayConnection

Adds a new FlashArray connection to vRO

Name [string]

FQDN/IP [string]

Username [string]

Password [SecureString]

Connection object [PS:FlashArrayConnection]

getAllSupportedApiVersions

Identifies all supported REST versions supported by a FlashArray

Connection object [PS:FlashArrayConnection]

REST versions [Array of string]

getFlashArrayConnection

Returns a connection

Name [string]

Connection object [PS:FlashArrayConnection]

getFlashArrayConnections

Returns all connections

None

Connection objects [Array of PS:FlashArrayConnection]

removeFlashArrayConnection

Removes a FlashArray connections

Connection object [PS:FlashArrayConnection]

Success result [boolean]

updateFlashArrayConnection

Updates a FlashArray connection

Connection object [PS:FlashArrayConnection]

Name [string]

FQDN/IP [string]

Username [string]

Password [SecureString]

Connection object [PS:FlashArrayConnection]

validateFlashArrayConnection

Validates connection information

Name [string]

FQDN/IP [string]

REST version [string]

Username [string]

Password [SecureString]

Discover REST versions [boolean]

Success result [boolean]

Host Group Actions

Action Name

Description

Inputs

Return Value

connectVolumeToHostGroup

Connects a volume to a host group

Volume [PS:Volume]

Host group [PS:HostGroup]

FlashArray [PS:FlashArrayConnection]

Success state [boolean]

createFlashArrayHostGroup

Creates an empty host group

Host group name [string]

FlashArray [PS:FlashArrayConnection]

Host group [PS:HostGroup]

 

createFlashArrayHostGroupWithHostList

Creates a host group with a selection of hosts

Host group name [string]

Hosts [Array of PS:Host]

FlashArray [PS:FlashArrayConnection]

Host group [PS:HostGroup]

 

getAllFlashArrayHostGroups

Returns all host groups on a FlashArray

Connection object [PS:FlashArrayConnection]

Host groups [Array of PS:HostGroup]

getHostGroupsOfAllConnections

Returns all host groups on all FlashArrays

None

Host groups [Array of PS:HostGroup]

getSpecificHostGroup

Returns a specific host group

Host group name [string]

FlashArray [PS:FlashArrayConnection]

Host group [PS:HostGroup]

 

removeFlashArrayHostGroup

Deletes an empty host group from the FlashArray

Host group [PS:HostGroup]

 

Name of host group [string]

removeFlashArrayHostGroupWithHosts

Deletes a host group from the FlashArray even if it has hosts in it

Host group [PS:HostGroup]

 

Name of host group [string]

updateFlashArrayHostGroupName

Changes a host group name

New name [string]

Host group [PS:HostGroup]

Host group [PS:HostGroup]

 

FlashArray Management Actions

Action Name

Description

Inputs

Return Value

getAllFlashArrays

Return all FlashArrays

None

FlashArrays [array of PS:FlashArray]

renameFlashArray

Renames a FlashArray

FlashArray [PS:FlashArray]

New name [string]

Success result [boolean]

Host Protection Group Actions

Action Name

Description

Inputs

Return Value

createFlashArrayProtectionGroup

Creates an empty protection group

Protection group name [string]

FlashArray [PS:FlashArrayConnection]

Protection group [PS:ProtectionGroup]

 

eradicateFlashArrayProtectionGroup

Permanently removes a destroyed protection group

Protection group [PS:ProtectionGroup]

Name of protection group [string]

getProtectionGroupsForDatastore

Returns all protection groups of a given datastore

Datastore [VC:Datastore]

Protection groups [Array of PS: ProtectionGroup]

getFlashArrayProtectionGroups

Returns all protection groups of a given FlashArray

FlashArray [PS:FlashArrayConnection]

Protection groups [Array of PS: ProtectionGroup]

getProtectionGroupsOfAllConnections

Returns all protection groups on all FlashArrays

None

Protection groups [Array of PS: ProtectionGroup]

getSpecificFlashArrayProtectionGroup

Returns a specific protection group

Protection group name [string]

FlashArray [PS:FlashArrayConnection]

Protection group [PS:ProtectionGroup]

 

removeFlashArrayProtectionGroup

Deletes a protection group from the FlashArray

Protection group [PS:ProtectionGroup]

 

Protection group name [string]

 

updateFlashArrayProtectionGroupName

Changes a protection group name

New name [string]

Protection group name [string]

Protection group name [string]

 

Run REST API Actions

Action Name

Description

Inputs

Return Value

runAPI

Runs a REST API call to a FlashArray that is not built into the plugin

FlashArray [PS:FlashArray]

Resource URI [string]

HTTP method [string]

JSON body [string]     

JSON result [string]

For more information on the REST API action, refer to the section, Running Direct REST API Calls to a FlashArray

Snapshot Actions

Action Name

Description

Inputs

Return Value

createSnapshotFromSingleVolume

Creates a snapshot of a volume

Name suffix [string]*

FlashArray volume [PS:Volume]

Snapshot [PS:Snapshot]

getAllSnapshots

Retrieves all snapshots from a specific FlashArray

FlashArray [PS:FlashArrayConnection]

Snapshots [Array of PS:Snapshot]

getSnapshot

Retrieves a specific snapshot from a FlashArray

Snapshot name [string]

FlashArray [PS:FlashArrayConnection]

Snapshot [PS:Snapshot]

getAllSnapshotsOfAllConnections

Retrieves all snapshots from all FlashArrays

None

 

Snapshots [Array of PS:Snapshot]

destroySnapshot

Destroys a snapshot. The snapshot is not eradicated.

Snapshot [PS:Snapshot]

Deleted snapshot name [string]

eradicateSnapshot

Permanently removes a destroyed snapshot.

Snapshot [PS:Snapshot]

Eradicated snapshot name [string]

renameSnapshot

Renames a snapshot

Snapshot [PS:Snapshot]

New name [string]

Snapshot [PS:Snapshot]

Volume Actions

Action Name

Description

Inputs

Return Value

createNewVolume

Creates a new FlashArray volume

Name [string]

Size [string]

FlashArray [PS:FlashArrayConnection]

Volume [PS:Volume]

createVolumeByCopySource

Creates a new volume by copying it from a snapshot or a volume

Name [string]

Source [string]

FlashArray [PS:FlashArrayConnection]

Volume [PS:Volume]

destroyVolume

Destroys a volume

Volume [PS:Volume]

Volume name [string]

disconnectDestroyVolume

Disconnects volume if it connected to host or host groups. After disconnecting it destroys volume. Optionally can eradicate the volume.

Volume [PS:Volume]

Eradicate option [boolean]

Volume name [string]

disconnectVolume

Disconnects volume if it connected to host or host groups.

Volume [PS:Volume]

 

Removed objects [properties]

eradicateVolume

Permanently remove a volume

Volume [PS:Volume]

 

Volume name [string]

eradicateVolume

Permanently remove a volume from its name

Name [string]

FlashArray [PS:FlashArrayConnection]

Volume name [string]

getAllVolumes

Retrieve all volumes from a FlashArray

FlashArray [PS:FlashArrayConnection]

Volumes [array of PS:Volume]

 

getAllVolumesOfAllConnections

Retrieve all volumes from all FlashArrays

None

Volumes [array of PS:Volume]

 

getAllVolumesPendingEradication

Retrieve all volume names of all volume pending eradication from a FlashArray

FlashArray [PS:FlashArrayConnection]

Volumes [array of string]

 

getVolume

Retrieve a specific volume from a FlashArray

Name [string]

FlashArray [PS:FlashArrayConnection]

Volume [PS:Volume]

increaseVolumeSize

Increases the size of a FlashArray volume

Volume [PS:Volume]

Size [string]

Volume [PS:Volume]

overwriteVolume

Copies one volume to another

Source name [string]

Target volume [PS:Volume]

Volume [PS:Volume]

renameVolume

Renames a volume

Name [string]

Volume [PS:Volume]

Volume [PS:Volume]

VMware Actions

Action Name

Description

Inputs

Return Value

getAvailableDisksWithCapacity

Returns a list of NAA numbers of devices that are available for VMFS formatting on an ESXi host.

ESXi [VC:HostSystem]

NAA numbers [array of string]

getFASnapshotsOfVolume

Returns all snapshots of a VMFS datastore

Datastore [VC:Datastore]

Snapshots [array of PS:Snapshot]

getHostGroupNamefromvCenterCluster

Returns a valid name of a FlashArray host group by removing any special characters in a cluster name

Cluster [VC:ClusterComputeResource]

Host group name [string]

Built-in Workflows

The FlashArray plugin offers built-in workflows for users to execute subsequent to installation of the plugin and registering of at least one FlashArray. These workflows are separated into seven categories:

  • FlashArray Connection Management—this includes all of the workflows to add/change/remove a FlashArray connection inside of vRO.
  • FlashArray Host Management—these workflows control creating/changing/removing FlashArray hosts and host groups
    • Host Group Management
    • Host Management
  • FlashArray Management—this includes workflows for altering array-level settings
  • FlashArray Protection Group Management—these workflows control creating/changing/removing FlashArray protection groups
  • FlashArray REST APIs—workflows for running custom REST API calls to the FlashArray
  • FlashArray Snapshot Management—these workflows control creating/changing/removing FlashArray snapshots
  • FlashArray Volume Management—these workflows control creating/changing/removing FlashArray volumes
  • VMware ESXi and FlashArray—these workflows are targeted at integrating VMware provision tasks with FlashArray ones to provide end-to-end provisioning

All workflows are in the Pure Storage folder in vRO and are separated into corresponding folders.

Workflow Descriptions

FlashArray Connection Management

Workflow Name

Description

Inputs

Outputs

Add FlashArray Connection

This workflow adds a FlashArray connection to vRO.

Friendly name [string]

IP/FQDN of FlashArray [string]

Discover REST version [boolean]*

REST API version [string]

FlashArray username [string]

FlashArray password [secure string]

FlashArray connection object [PS:FlashArrayConnection]

Get All FlashArray Connections

Returns all FlashArray connection objects in the vRO inventory

None

FlashArray connections [array of PS:FlashArrayConnection]

Get FlashArray Connection

Returns the connection object for a given FlashArray name

FlashArray name [string]

FlashArray connection [PS:FlashArrayConnection]

Import FlashArray certificate from URL

Imports the certificate for a FlashArray into vRO

FlashArray URL [string]

Accept certificate with warnings [boolean]

None

Remove FlashArray Connection

Removes a specific FlashArray connection

FlashArray connection [FlashArrayConnection]

Operation success [boolean]

Update FlashArray Connection

This workflow updates a FlashArray connection in vRO.

FlashArray connection [PS:FlashArrayConnection]

Friendly name [string]

IP/FQDN of FlashArray [string]

Discover REST version [boolean]*

REST API version [string]

FlashArray username [string]

FlashArray password [secure string]

FlashArray connection object [PS:FlashArrayConnection]

All inputs marked with an asterisk (*) are optional. All others are mandatory.

FlashArray Host Management - Host Group Management

Workflow Name

Description

Inputs

Outputs

Create FlashArray Host Group

Creates an empty host group

Host group name [string]

FlashArray [PS:FlashArrayConnection]

Host group [PS:HostGroup]

Create FlashArray Host Group With Hosts

Creates a host group and adds input hosts

Host group name [string]

List of hosts [array of PS:Host]

FlashArray [PS:FlashArrayConnection]

Host group [PS:HostGroup]

Get All FlashArray Host Groups

Retrieves all host groups from a specific FlashArray

FlashArray [PS:FlashArrayConnection]

Host groups [Array of PS:HostGroup]

Get Specific FlashArray Host Group

Retrieves a specific host group from a FlashArray

Host group name [string]

FlashArray [PS:FlashArrayConnection]

Host group [PS:HostGroup]

Remove FlashArray Host Group

Removes a host group with no hosts

Host group [PS:HostGroup]

Removed host group name [string]

Remove FlashArray Host Group With Hosts

Removes a host group with hosts. The hosts themselves are not deleted

Host group [PS:HostGroup]

Removed host group name [string]

 

Rename Host Group

Renames a host group

Host group [PS:HostGroup]

New name [string]

Host group [PS:HostGroup]

FlashArray Host Management - Host Management

Workflow Name

Description

Inputs

Outputs

Create FlashArray Host

Creates an empty host

Host name [string]

FlashArray [PS:FlashArrayConnection]

Host [PS:Host]

Create FlashArray Host Group With IQNs or WWNs

Creates a host and adds input initiators

Host name [string]

List of IQNs [array of string]*

List of WWNs [array of string]*

FlashArray [PS:FlashArrayConnection]

Host [PS:Host]

Get All FlashArray Hosts

Retrieves all hosts from a specific FlashArray

FlashArray [PS:FlashArrayConnection]

Hosts [Array of PS:Host]

Get Specific FlashArray Host

Retrieves a specific host from a FlashArray

Host name [string]

FlashArray [PS:FlashArrayConnection]

Host [PS:Host]

Remove FlashArray Host

Removes a host

Host [PS:Host]

Removed host name [string]

Rename Host

Renames a host

Host [PS:Host]

New name [string]

Host [PS:Host]

FlashArray Management 

Workflow Name

Description

Inputs

Outputs

Rename FlashArray

Renames the actual name of the FlashArray

New name [string]

FlashArray [PS:FlashArray]

Success result [boolean]

FlashArray Protection Group Management

Workflow Name

Description

Inputs

Outputs

Add FlashArray Protection Group

Creates a new empty protection group

Protection group name [string]

FlashArray [PS:FlashArrayConnection]

Protection group [PS:ProtectionGroup]

Destroy FlashArray Protection Group

Destroy a protection group and puts it into the deleted items folder.

Protection group [PS:ProtectionGroup]

Removed protection group name [string]

Get All FlashArray Protection Groups

Retrieves all protection groups from a specific FlashArray

FlashArray [PS:FlashArrayConnection]

Protection groups [Array of PS: ProtectionGroup]

Get Specific FlashArray Protection Group

Retrieves a specific protection group from a FlashArray

Protection group name [string]

FlashArray [PS:FlashArrayConnection]

Protection group [PS: ProtectionGroup]

Rename Protection Group

Renames a protection group

Protection group [PS:ProtectionGroup]

New name [string]

Protection group [PS:ProtectionGroup]

 

FlashArray Rest APIs

Workflow Name

Description

Inputs

Outputs

Run REST API

Runs any REST API supported by the FlashArray to a specific FlashArray.

FlashArray [PS:FlashArray]

Resource URI [string]

HTTP method [string]

JSON body [string]

Result [string]

More information on the “Run REST API” workflow in the section Running Direct REST API Calls to a FlashArray

FlashArray Snapshot Management

Workflow Name

Description

Inputs

Outputs

Create Snapshot

Creates a snapshot of a volume

Name suffix [string]*

FlashArray volume [PS:Volume]

Snapshot [PS:Snapshot]

Create Snapshot of Multiple Volumes

Creates a snapshot of multiple volumes

Name suffix [string]*

FlashArray volumes [Array of PS:Volume]

FlashArray [PS:FlashArrayConnection]

Snapshots [Array of PS:Snapshot]

Get All Snapshots

Retrieves all snapshots from a specific FlashArray

FlashArray [PS:FlashArrayConnection]

Snapshots [Array of PS:Snapshot]

Get Specific Snapshot

Retrieves a specific snapshot from a FlashArray

Snapshot name [string]

FlashArray [PS:FlashArrayConnection]

Snapshot [PS:Snapshot]

Destroy Snapshot

Destroys a snapshot. The snapshot is not eradicated.

Snapshot [PS:Snapshot]

Deleted snapshot name [string]

Rename Snapshot

Renames a snapshot

Snapshot [PS:Snapshot]

New name [string]

Snapshot [PS:Snapshot]

FlashArray Volume Management

Workflow Name

Description

Inputs

Outputs

Create Volume

Creates a volume

Name [string]

Size [number]

Size unit (KB, MB, GB, TB, PB) [string]

FlashArray [PS:FlashArrayConnection]

Volume [PS:Volume]

Destroy Volume

Destroys a volume. The volume is not eradicated.

Volume [PS:Volume]

Destroyed volume name [string]

Eradicate Volume

Eradicates a destroyed volume. This cause the volume to be unrecoverable.

Volume name [string]

FlashArray [PS:FlashArrayConnection]

Eradicated volume name [string]

Get All Volumes

Retrieves all volumes from a specific FlashArray

FlashArray [PS:FlashArrayConnection]

Volumes [Array of PS:Volume]

Get Volume

Retrieves a specific volume from a FlashArray

Volume name [string]

FlashArray [PS:FlashArrayConnection]

Volume [PS:Volume]

Increase Volume Size

Increases the allocated capacity of a volume

Volume [PS:Volume]

Size [number]

Size unit (KB, MB, GB, TB, PB) [string]

Volume [PS:Volume]

Rename Volume

Renames a volume

Volume [PS:Volume]

New name [string]

Volume [PS:Volume]

VMware ESXi and FlashArray

Workflow Name

Description

Inputs

Outputs

Add Datastore to FlashArray Protection Group

This takes in a VMFS datastore and then adds the corresponding FlashArray volume to a given protection group

Datastore [VC:Datastore]

Protection group [PS:ProtectionGroup]

Volume [PS:Volume]

Protection group [PS:ProtectionGroup]

Create a FlashArray Host Group from a vCenter Cluster

Takes in a VMware cluster and then creates corresponding hosts and then a host group and adds the host to it.

vCenter cluster [VC:ClusterComputeResource]

FlashArray [PS:FlashArrayConnection]

Host group [PS:HostGroup]

Create FlashArray Snapshot of a VMFS Datastore

Takes in a VMFS datastore and creates a snapshot of the corresponding FlashArray volume

VMFS datastore [VC:Datastore]

Snapshot name [string]

Snapshot [PS:Snapshot]

Identified volume [PS:Volume]

Create VMFS Datastore from FlashArray Snapshot

Creates a datastore copy from a snapshot of a VMFS. This will mount it to the specified cluster and resignature the datastore. The datastore will be renamed to the entered name.

Snapshot [PS:Snapshot]

Datastore name [string]

vCenter cluster [VC:ClusterComputeResource]

 

Volume [PS:Volume]

Resignatured datastore [VC:Datastore]

Create VMFS Datastore on Existing FlashArray volume

Creates a datastore on a volume that is already provisioned to an ESXi host.

ESXi host [VC:HostSystem]

NAA of a disk [string]

Datastore name [string]

Datastore [VC:Datastore]

Create VMFS Datastore on New FlashArray volume

Creates a new volume, connects it to the correct host group for a VMware cluster and formats it as VMFS. Works with VMFS 5 and VMFS 6. Chooses the highest available VMFS version for that cluster.

vCenter cluster [VC:ClusterComputeResource]

Name [string]

Size [number]

Size unit (KB, MB, GB, TB, PB) [string]

FlashArray [PS:FlashArrayConnection]

Volume [PS:Volume]

Datastore [VC:Datastore]

Delete VMFS Datastore

This will unmount a datastore and then detach it from all of connected ESXi hosts. It will then destroy it or destroy it and eradicate it depending on what the user chooses.

Destroy option [string]

Datastore [VC:Datastore]

Destroyed volume name [string]

Expand VMFS Datastore

This will increase the FlashArray volume size and then rescan the cluster and perform a VMFS volume grow to use the additional capacity.

Datastore [VC:Datastore]

Size [number]

Size unit (KB, MB, GB, TB, PB) [string]

 

Volume [PS:Volume]

Datastore [VC:Datastore]

Remove Datastore from FlashArray Protection Group

This takes in a VMFS datastore and then removes the corresponding FlashArray volume from a given protection group

Datastore [VC:Datastore]

Protection group [PS:ProtectionGroup]

Volume [PS:Volume]

Protection group [PS:ProtectionGroup]

Removes a FlashArray Host Group from a vCenter Cluster

Takes in a VMware cluster and then removes the corresponding hosts and host group.

vCenter cluster [VC:ClusterComputeResource]

FlashArray [PS:FlashArrayConnection]

Host group name [string]

Restore VMFS Datastore from FlashArray snapshot

Takes in a VMFS datastore and restores it from a snapshot—the process will resignature the VMFS if needed. Default behavior is to unmount/detach/disconnect the datastore before refreshing. This process can be skipped if desired.

Datastore [VC:Datastore]

Snapshot [PS:Snapshot]

Skip unmount [boolean]

Volume [PS:Volume]

Datastore [VC:Datastore]

Snapshot [PS:Snapshot]

 

Running a Workflow

Workflows can be run from the inventory screen (as shown in the above section) or from the workflow listing in the vRO inventory. All workflows require some level of input in order to run, a volume, a datastore, a FlashArray, a capacity, and etc. For example, the create VMFS datastore workflow takes in the following information:

  • vCenter Cluster—a VMware cluster to provision to.
  • A FlashArray—which FlashArray should host the new volume.
  • VMFS name—this will be the volume name and the VMFS label.
  • Capacity—a capacity for the volume
  • Unit—choose a capacity unit, either KB, MB, GB, TB (default), or PB.

Some of these are text fields, some are inventory-related fields. If you have added a vCenter already, your clusters can be selected by drilling-down to the cluster objects.

vrops34.png

vrops35.png

vrops36.png

The workflow will run when submitted and you can monitor the progress in the “Schema” tab of that workflow instance run.

vrops37.png

Editing a Built-in Workflow

Built-in workflows are not editable by vRO users—these can only be changed and updated by Pure Storage. The main reason behind this is to make support of these workflows much easier for both customers and Pure Storage. That being said you can indirectly edit them. By duplicating the workflows you can create a copy that can be edited as needed.

vrops38.png

Building Custom Actions and Workflows

A lot of common workflows required by the average user are included by default in the plugin, but in some cases customizations might be required. These customizations might be small, but in other situations, entirely new functionality is required and this might dictate the need for new actions and/or workflows.

In this section, the process of building new actions, customizing existing workflows and building new workflows will be discussed.

This section is for more advanced users of vRealize Orchestrator who are interested in custom design of workflows. At least an introductory understanding of scripting, in particular Javascript is recommended. For full understanding of vRO operations refer to VMware documentation.

 Building a New Action

When new functionality is required, the first thought that should be examined is what is the end result of this workflow? If the end result is one object, or one type of object, an action is probably preferable to a workflow. Furthermore, if this is a function that is likely to be needed by many other workflows, an action is generally a better choice.

This section will focus on building a new action.

The first step is creating a new folder for your action, in this case I will create one under my own custom folder named “com.purestorage.flasharray.myactions".

vrops39.png

Right-click that folder and then choose “Add action…”

vrops40.png

Assign the new action a name. In this case, I want to obtain all of the timestamps of the snapshots of a certain datstore (or really the FlashArray volume that hosts it), so I will call it “getDatastoreSnapshotTimestamps”.

vrops41.png

The first thing you need to decide is what inputs are required of this action—what objects do you want to send it? A volume? A vCenter datastore? A virtual machine? A snapshot? In this case, I want to take in a VMware datastore, so I will add one input, a VC:Datastore and call the input “datastore”. On the scripting tab, click to add a new variable.

vrops42.png

Rename the input to something that makes sense and then click on the “Type” and change it to the appropriate type. In this case VC:Datastore.

vrops43.png

Now you can start adding scripting. My action needs to do the following things:

  1. Take in a datastore and figure out what FlashArray volume hosts it
  2. Figure out the snapshots for that volume
  3. Extract the timestamps of those snapshots

In order to get this information you can build it yourself using the FlashArray plugin scripting objects and methods (documented in vRO itself or at http://www.vroapi.com). But often, there are already actions (or workflows) that do all or part of what you need, so it is usually easier to re-use those.

So let’s start with figuring out the FlashArray snapshots of a datastore. With built-in functionality of the plugin we have two options:

  • Use the action vmfsVolumeToFAVolume to translate the datastore to a FlashArray volume and then use the volume method “getSnapshots()” to get the snapshots.
  • There is also a built-in action to do both at once called “getFASnapshotsofVolume” which takes in a datastore and returns all of the snapshots of the corresponding FlashArray volume.

Either method is fine, but number two is easier, so let’s do that.

Navigate to this action in the left-hand pane and then you can right-click on it and choose “copy”:

vrops44.png

In the scripting windows, you can then right-click and choose “paste”. This will automatically generate the Javascript that is required to call the workflow.

vrops45.png

You will also note that it automatically puts in the “datastore” input as the input to the method. Which is exactly what this needs. In other situations, if the automatic choice is not correct, you can always change it.

Since this module returns an array (list) of snapshots (PS:Snapshot) and we need to store that object, we need to store it in a variable. We can do this by setting that action call we just pasted to a new variable. I will call it “snapshots”. Add a semi-colon to the end of the statement to complete it. So it will look like this:

var snapshots = System.getModule("com.purestorage.flasharray.vmware.vcenter").getFASnapshotsOfVolume(datastore);

Now that we have all of the snapshots of that volume stored in a variable we can pull the information out that we need. This is an array of snapshots, and if you look at the FlashArray snapshot object listed section called Custom Objects, you can see the properties of a snapshot object. I want to return the timestamp of its creation (PS:Snapshot.created) and will also return the name (PS:Snapshot.name) to give context. Both properties are strings—so will join them together. If the name is “mysnapshot” and the timestamp is “2016-12-21T16:13:02Z” I will put the name first, followed by a colon, then the timestamp, so it would look like:

mysnapshot: 2016-12-21T16:13:02Z

So I will now write the Javascript to iterate through all of the snapshots and building my custom name/timestamp string for each one. I will then store each value in an array object I created called “snapTimestamps”. Finally I want to return the array of timestamp strings, so I will return that final variable out of the scripting object. If the volume has no snapshots I will just return text indicating there are no snapshots, skipping the iteration.

var snapshots = System.getModule("com.purestorage.flasharray.vmware.vcenter").getFASnapshotsOfVolume(datastore);
var snapTimestamps = [] ;
if (snapshots.length > 0)
{
    for (i=0; i<snapshots.length; i++)
    {
        var snapTimestamp = snapshots[i].name + ":" + snapshots[i].created;
        snapTimestamps.push(snapTimestamp);
    }
    return snapTimestamps;
}
else
{
    return "This datastore has no snapshots";
}

The last part is to change the output (return type) to the appropriate type. This is an array of objects, and these objects are all string values, so the return type should be an array of strings.

vrops48.png

The action is now complete.

Note that for simplicity of explanation, error/exception handling is not included in the script in this action. It is important, though, to include that in your scripts whenever possible. Error/exception handling explanation is beyond the scope of this document.

Understanding Workflows

Workflows are essentially scripts that you can run. Workflows take in parameters (a name, a virtual machine etc.) and then return a result (success or failure, or a virtual machine or many virtual machines etc.).

Inside of a workflow, just like a script are multiple functions, workflows have internal objects often referred to as tasks. These tasks can be many different things, they can be decisions, iteration logic, scripts, actions or other workflows even.

vrops49.png

Variables

In order to provide the tasks with the information they need, the workflow can take the variables it has and pass them into and out of those tasks. There are three types of variables in a workflow:

  • Inputs—a variable that a user enters into the workflow when they run it. This variable is a constant— it cannot be written to—it can only be read from by tasks.

vrops50.png

  • Outputs—what the workflow returns to the user. The object that was created for instance, information about an object, or a result. An output cannot be read—it can only be written to by tasks.

vrops51.png

  • Attributes—a variable that can be hard coded or empty when the workflow is first run. Can be passed in and out of objects in a workflow and its value can be changed in the process. This is read/write accessible to tasks. An attribute cannot be passed into, or out of, a workflow.

vrops52.png

Once a workflow has inputs or outputs, for a task to be able to use them, you must explicitly pass them into (or out from) the task. Details on this process can be found in the next few sections.

vrops53.png

Scriptable Tasks

Workflows, actions and generic tasks are sometimes not specific enough to manipulate the data in the way that you might want. This is where the “scriptable task” comes in.

vrops54.png

Scriptable tasks provide a scripting environment to make custom and detailed handling of objects inside of vRO. Scriptable tasks exclusively use Javascript which provides direct access to built-in objects and methods from the various plugins.

vrops55.png

Creating a FlashArray Workflow

Occasionally users may want to build their own custom workflows to fit their use case. This can be easily done with the FlashArray plugin for vRealize Orchestrator. Let’s look at the situation where you want to create a FlashArray volume and also connect it to a host group.

First, create a workflow. I will call it “Create Volume and Connect to Host Group”. Very creative.

vrops56.png

Once the workflow has been created, you can start building the logic. The first step is to include an action to create a volume. There are two ways to do this:

  1. You can create a scriptable task and copy/paste the action into it
  2. Directly import the action into the workflow

To see an example of the first option, please refer to the section Using an Action Inside of a Scriptable Task. For this example we will use option two.

  1. Add the create volume action. Navigate to the Pure Storage action folder and drag and drop the createNewVolume action.

vrops57.png

  1. Click the “Setup” button that appears to configure the inputs and outputs of the action.

vrops58.png

  1. Accept the input defaults. You can rename things if you want, as shown below. When done, click “Promote”.

vrops59.png

  1. Now follow the same process for the “connectVolumeToHostGroup” action.

vrops60.png

  1. The variable setup is very similar. This action takes in a volume name, a host group name and FlashArray. The volume name and FlashArray connection inputs will default to the ones already added. vRO intelligently matches the input and outputs that are already there. If the “type” of the object (a string, a datastore, an array, etc.) is already there as an input or output it will default to that. You can of course separate them, but in this case the inputs for the create volume (the FlashArray and volume name) and the add to host workflow (FlashArray and volume name) are supposed to be the same, so they can be re-used as is the default. The only inputs/outputs that are new are the result of adding to the host group and the host group name. This is denoted by the green plus sign. When done, click promote.

vrops61.png

  1. The workflow will now completely function without any additional work!

vrops62.png

vrops63.png

Creating a FlashArray and VMware Workflow

The Pure Storage FlashArray Plugin for vRealize Orchestrator includes larger workflows that provide VMware-integrated operations out of the box. The following workflows are included automatically:

vrops64.png

These workflows run FlashArray operations, but from a VMware (VMFS) context. Instead of inputting a FlashArray volume, you can give it a VMFS datastore, and the workflow will perform the FlashArray operation (like creating a snapshot) on the volume that hosts it. The workflow figures out the translation (which FlashArray hosts the VMFS datastore and which volume is it on). The larger majority of the common workflows you might do are already built in. But how do you create your own?

For example, maybe you want to create a simple workflow that renames the VMFS but also renames the FlashArray volume. How would that be done? The plugin includes some helper actions that can achieve this:

vrops65.png

Let’s walk through building this workflow.

  1. Create a new workflow and add the vmfsVolumeToFAVolume action. Click setup to configure the variables. Change the variable names if you want something more descriptive. Below the output has been changed from actionResult (which is the identified FlashArray volume) to flasharrayVolume. Also change the output type from an output to a local variable (frequently referred to as an attribute). This will allow the resulting volume to be passed to another action or object inside of the workflow.

vrops66.png

  1. Now import the “renameVolume” action.

vrops67.png

  1. In the variable setup for this action change the “volumeObject” input to the local variable from before (flasharrayVolume), the returned volume object. This will take the returned object of the previous action, vmfsVolumeToFAVolume, and send it to the rename action.

vrops68.png

  1. Now, we need to create an object to rename the VMFS datastore. There is no built-in workflow, so we need to create a new one. Drag in a “Scriptable task” object from the inventory section labeled “Generic”. Drag it anywhere onto the workflow path.

vrops69.png

  1. Now edit the scriptable object. Rename it to something that makes sense, like “Rename VMFS” on the “Info” tab.

vrops70.png

  1. Add a new input that is a datastore on the “IN” tab when the edit screen appears.

vrops71.png

  1. Click the connector button to bind a new variable to this object. We need to “bring in” the datastore from the overall workflow to this new object.

vrops72.png

  1. Click on the datastore (type VC:Datastore) object. Also choose the “newVolumeName” (type string). This will associate the datastore to be renamed and the new name with the custom scripting object.

vrops73.png

  1. In the “Scripting” tab add the following Javascript to rename the volume:
    1. datastore.rename_Task(newVolumeName);

vrops74.png

  1. Now save and run the workflow. It will now rename both objects!

 vrops75.png

vrops76.png

Workflow Presentation Layer

Once the logic has been completed for a workflow, the presentation layer can be customized. The presentation layer controls how the user interacts with configuring inputs when running a workflow. This allows the designer to control what is entered by the user and also to assist them when choosing options.

There are some basic controls, advanced, dynamic inputs and also methods to validate inputs before running a workflow.

Basic Input Control

For the majority of inputs, basic controls will suffice. In the presentation layer, you can view all of your workflows inputs.

vrops77.png

If you click on a variable you can control how the input for that variable is presented to the user. If you click on the property addition symbol (the triangle with a plus sign) you can add controls.

vrops78.png

If you make the input mandatory, the user will not be able to execute the workflow until that input it entered.

vrops79.png

When the workflow is run, that input will have a red asterisk next to it and the submit button will be gray until it is populated.

vrops80.png

Furthermore, you can force certain selections of inputs by hard-coding some choices. If I want to enforce a LUN ID to be one of a few numbers I can add them into the “Pre-defined answers” option.

vrops81.png

When run, they will get a drop-down of these choices.

vrops82.png

This is just a sub-set of what can be done with the basic input presentation controls. Refer to VMware documentation for more information. But what about if you want something that isn’t static? Choices that depend on previous inputs the user has entered? Dynamic inputs is the option for that.

Dynamic Inputs

Dynamic inputs allow you to provide choices for an input based on some other variable that the user has entered. Let’s take the example of restoring a datastore from a snapshot. When the user enters a datastore, I want the snapshot restore point to only list snapshots that belong to the FlashArray volume hosting that datastore.

This can be achieved by linking an action to an input. When the appropriate field is filled out, an action will run with that input (in this case a datastore) and return an array of objects that can be selected from.

In the presentation tab, choose the snapshot input and add a property for “Predefined list of elements”.

vrops83.png

Click on the blue puzzle piece icon to link an action.

vrops84.png

A list of possible actions will appear—the return value of the action must be an array of the input you are configuring—in this case a snapshot. vRO will filter the actions that are compatible.

vrops85.png

The workflow, getFASnapshotsofVolume, takes in a datastore and returns the respective snapshots. So I will choose that one. When selected, you must tell it in the line entry which input it should act upon. The input must match the input of the action. In this case the datastore input.

vrops86.png

When apply is clicked, the process is complete.

vrops87.png

When the wizard is run and the datastore is chosen, the correct snapshots will appear as options.

vrops88.png

Custom Validation

Another option for using actions in the presentation layer of a workflow is via custom validation. Custom validation allows the workflow to check and verify input as soon as the input is entered and before the workflow run is actually submitted. This will greatly increase the rate of successfully run workflows. Examples of custom validation could be:

  1. Checking that an input size is in a valid range
  2. Checking to see that a name is not in-use
  3. See if an object has a required relationship

Let’s look at an example of number two—creating a new volume and checking first that the name is unique.

The important thing to understand is how vRO custom validation decides if the input is invalid or valid. If, when run, the action returns null the validation succeeds. If the action returns anything else, the input is considered invalid and the validation fails. Ideally, you want to return a string in the case of an error. If you return a string, the string will be interpreted as an error message and will be surfaced in the wizard. You can technically return anything else but it will not be particularly informative.

Example of returning a string:

vrops89.png

Example of returning an object:

vrops90.png

It is apparent that returning a string for a failure is much more helpful to the requestor.

So back to our action. I want to create a new volume, but before I complete the volume creation wizard to start the workflow, I want to make sure that the name is not in use by another volume on that FlashArray.

In this case, I have a simple action to use for checking this. This action takes in a FlashArray connection and a name and looks through all of its volumes to see if that name is in use.

vrops91.png

I have a workflow called “Create FlashArray Volume”. This workflow takes in a FlashArray connection, a name and a size.

The first step is to choose the input in the workflow you want to validate and configure its presentation layer. Add a property to the “name” input and choose “Custom validation”.

vrops92.png

Then configure the validation by clicking on the puzzle piece icon.

vrops93.png

Type in the name of your action in the search box and the select it—in this case my action is called “checkVolumeUniqueName”.

vrops94.png

Then you need to link the inputs of the workflow to the action used in the validation. This is in the below box.

vrops95.png

It lists all of the required inputs of the action, you need to associate inputs of the workflow to each mandatory input of the action—they must be the same type. In this case, there are two action inputs, a name (a string) and a FlashArray connection. The name input is the input you are validating so enter #__current (note that is two underscores preceding “current”) into the box for “name”.  Since you are not hardcoding the name you should change the input type from static to OGNL in the drop down.

vrops96.png

The other input “flashArrayConnection” needs to be linked to a different input of the initial workflow to bring in the FlashArray connection. You can either type in the variable name with a preceding # or click the pencil icon and select the proper one.

vrops97.png

vrops98.png

Now that the validation is complete I can run the workflow and if I enter a name that is in-use there immediately is an error:

vrops99.png

If I make it unique, the error goes away:

vrops100.png

Troubleshooting

Logs

You must collect the following logs in case you need to contact the Pure Storage support team. List of logs to be collected Collect the following logs if you need to contact the support team for any issue:

  1. Workflow Execution Logs (Include both Information logs and Debug logs)
  2. Server.log

How to Collect Logs

Collect the logs that you need to send to the support team as follows:

Workflow Execution Logs

Info Logs

  1. From the Logs tab of the Workflow execution, select Info in the drop-down list.
  2. Select All the messages and send it as Info logs.

Debug Logs

  1. From the Logs tab of the Workflow execution, select Debugin the drop-down list.
  2. Select All the messages and send it as Debug logs.

 Server.log

  1. Go to the Orchestrator Control Center of vRO server.
  2. From the Monitor and Control section, click on the File System Browser.
  3. From the File System Browser, click on the app-server-logs
  4. From app-server-logs, download the server.log file and send it as server.log

Advanced Techniques

Using an Action Inside of a Scriptable Task

To execute an action into a scriptable task you need to first add a scriptable task into the workflow. Generally it is preferred to just add the action directly into your workflow as its own object to make logic easier to follow, but occasionally actions are used so frequently or the action is simple enough it is better to make a direct call inside of a scriptable task.

This can be done by finding the task in the left-hand pane and dragging and dropping it onto the appropriate place in the schema.

vrops101.png

Next, edit the task and go to the scripting tab. Navigate to the action you want to use or use the search function to auto-locate it by name. Right-click on the action and choose copy.

vrops102.png

Then right-click in the scripting pane and choose paste.

vrops103.png

The line to call the action will be added and it will include suggested variable names that need to be passed into the action. In this case a volume to snapshot (PS:Volume object variable called volume) and a snapshot suffix (string variable called suffix). I have two inputs in this workflow, one for the volume which is called volume and another for the suffix which is called snapSuffix:

vrops104.png

The input for the volume is right so it will stay named “volume” the other I will rename to match my variable “snapSuffix”.

vrops105.png

The action returns a snapshot object, so if I want to reuse that object, I can set the whole operation to store the result (a snapshot) in a variable I will call snapshot.

var snapshot = System.getModule("com.purestorage.flasharray.snapshot").createSnapshotFromSingleVolume(volume,snapSuffix)

Using Scripting Objects and Methods

The FlashArray plugin for vRealize Orchestrator offers custom objects and methods that provide functionality that offer additional functionality above and beyond what the built-in actions and workflows can do. These are used inside of scripting objects of a workflow or inside of an action through JavaScript. This section will overview how to use these objects and their methods.

Available Objects and Methods

The available list of scripting objects and their methods can be found at the following URL:

http://www.vroapi.com/Plugin/PS/1.0.0

Additionally documentation of these can be find inside of vRO itself. When in a scripting window, there is an object explorer to help find workflows and actions, but it can also show scripting objects and their methods. The Pure Storage one can be found under PS:

vrops107.png

When expanded you can see the available objects, scripting objects and methods. Objects are already defined earlier—these can be variables that can be passed into and out of a workflow. These objects are based on scripting objects, which is essentially a custom variable that has certain property names and types that are pre-defined. These scripting objects can be instantiated and their properties populated. Each object also has methods that can be run against it to perform a certain operation. The gray items are regular objects and the green ones are scripting objects. Scripting objects may have properties and methods, some just have methods and some just have properties.

When you expand a scripting object, you will see the properties of it, as well as the methods. The methods describe what inputs they require when invoked, and also what the methods returns when successfully run.

vrops108.png

Using Scripting Object Methods

In this section, I will use scripting objects and methods to update a protection group. Specifically, I will be updating a protection group replication schedule to replicate once an hour instead of every four hours. The current protection group looks like this:

vrops109.png

The vRO plugin does not have a built-in action to change this, so you need to use the vRO plugin scripting actions and methods to do so. The PS:ProtectionGroup object refers to the ProtectionGroup scripting object. That object has a variety of methods, one is called update. So if I have a protection group object stored in a scripting object called pgroup, I can run the method on it.

vrops110.png

The update method takes in another type of scripting object called PSProtectionGroupRequest. This object has the following properties:

vrops111.png

So, I need to create the PSProtectionGroupRequest before I can update the protection group. This can be done by copying and pasting the scripting object into the scripting window:

vrops112.png

My workflow has the following inputs:

vrops113.png

So I am asking the user for a replication interval in either minutes, hours or days, so depending on the input I need to enter the proper information. The replication interval is taken in as seconds, so I need to convert what they are entering into seconds, so if they choose “hours” I will multiply that number by 3600 to get it into seconds and so on. This is achieved through a switch statement.

var myPSProtectionGroupRequest = new PSProtectionGroupRequest ();
switch (replicationUnit) {
    case "days":
        replicationInterval = replicationInterval*86400;
        break;
    case "hours":
        replicationInterval = replicationInterval*3600;
        break;
    case "minutes":
        replicationInterval = replicationInterval*60
;
}

You can click on the property to find more information:

vrops115.png

You can also lookup that value in the FlashArray REST API guide for more information as well.

vrops116.png

The next part is to add the replication interval as the value in my scripting object (which is now just empty). So I set the scripting object replication_interval property equal to my identified new value:

myPSProtectionGroupReques.replicate_frequency = replicationInterval;

My full script is below:

var myPSProtectionGroupRequest = new PSProtectionGroupRequest ();
switch (replicationUnit) {
    case "days":
        replicationInterval = replicationInterval*86400;
        break;
    case "hours":
        replicationInterval = replicationInterval*3600;
        break;
    case "minutes":
        replicationInterval = replicationInterval*60
;
}
myPSProtectionGroupRequest.replicate_frequency = replicationInterval;
pgroup.update(myPSProtectionGrouprequest);

Now when I run my workflow, I can change it to 2 hours:

vrops119.png

It is now changed:

vrops120.png

Running REST API Calls to FlashArray

In some situations, it might be necessary to make direct REST API calls to a FlashArray. This is necessitated when the built-in workflows, actions, or scripting objects and their respective methods do not provide the functionality you need, like if a new feature has been released on the FlashArray subsequent to the latest vRO plugin, that introduces new respective REST API calls.

In order to use newer features, or something custom that happens to not be included, you can leverage the built-in REST functionality inside of the FlashArray vRO plugin to do anything that you need.

There are two options for this:

  1. REST API Workflow
  2. REST API Action

Both methods leverage the same underlying process—the workflow encapsulates the action, the action encapsulates a scripting object method. Whichever you use is entirely a matter of preference and personal familiarity.

REST API Required Inputs

Regardless to the method you use (workflow or action) both require a few inputs to run:

  • FlashArray target: The FlashArray to which the REST API call should be directed.
  • Uniform Resource Identifier (URI) Suffix: The URI defines the type of object, and often the specific object to act upon and is the HTTP URL that is used to make the call.
  • HTTP Method: This is the type of operation being performed; GET, POST, PUT or DELETE.
  • JSON Body: This is additional information often included in POST, PUT or DELETE REST calls.

FlashArray Target

Any REST call should be targeted at a specific FlashArray—generally this is dictated in the URI (discussed in the next sub-section) but in vRO, a FlashArray object must be chosen from the inventory.

vrops121.png

Please note that what is required here is not a FlashArray Connection (PS:FlashArrayConnection) object, like many workflows, but instead a FlashArray (PS:FlashArray) object is required in this instance.

Uniform Resource Identifier (URI) Suffix

A standard REST call includes a full URI, which has a FlashArray IP/FQDN, an API version and then the information for the specific REST call like below:

https://pure-001.example.com/api/1.7/array?space=true

When using the vRO REST feature in the FlashArray plugin, all that is needed is the string after the REST API version. So instead of the full URI above, you just enter:

/array?space=true

Yes, include the preceding forward slash. In this you put object names, types, filters, query parameters etc.

For more information on building URI’s please refer the FlashArray REST API documentation.

HTTP Method

The third input is the HTTP method. While there are many types of HTTP method the following are the one supported by the FlashArray:

  • GET: List resources
  • POST: Create a resource
  • PUT: Modify a resource
  • DELETE: Delete a resource

JSON Body

For most POST, PUT and DELETE operations, it is required to also submit a body with certain parameters populated. The body is formatted using JavaScript Object Notation (JSON). More info on JSON can be found here http://www.json.org/.

There are a variety of different data types used in JSON, the following are the most common.

Data Type

Description

Example

boolean

A parameter that is either true or false

{"eradicate": true}

object

A special parameter with custom variable names and values

{"replicate_blackout": {"end": 14400,"start": 7200}}

list

A variable with multiple values

{"nameservers": ["192.168.1.1","192.168.0.1"]}

number

A variable that is a number only

{"per_day": 12}

string

A variable that can be a series of characters

{"domain": "example.com"}

Note that it is very important to pay special attention to the placement and proper use of the special characters (brackets, colons, double quotes, etc.) or the JSON will be invalid and REST calls will fail or create unintended results.

An example of a JSON body for a REST call to create a snapshot of two different volumes respectively named myvolume and yourvolume is below:

{
      "snap": true,
     "source": ["myvolume","yourvolume" ]
}

Using the REST API Workflow

For this example, we will use the PUT operation that enables an alert recipient on the FlashArray. Details can be found in your REST API guide for the FlashArray under alert management.

The “Run REST API” workflow is in the “FlashArray REST APIs” folder. To execute the workflow, right click and click “Run workflow”.

vrops122.png

In the first screen, enter the FlashArray object you want to run the REST API against. 

vrops123.png

Then click Next.

vrops124.png

Enter your resource URI, HTTP Method, and a Body in JSON if applicable.

In this case the alert watcher I want to enable is the email address vroadmin@purestorage.com.

vrops128.png

The URI suffix would be:

/alert/vroadmin@purestorage.com

The method is PUT. The request body would be:

{ "enabled": true }

vrops126.png

Click submit to run the workflow. The workflow completes and the now enabled status of that recipient is returned:

vrops127.png

The return result is stored as a string inside of the output named actionResult. The string is formatted in the form of JSON. Refer to the section, Parsing the REST API Response with JavaScript, for details on how to manage that output if it is passed into a JavaScript-based scriptable task.

vrops125.png

Using the REST API Action

Using the REST API action by including the action as an object directly in a workflow (the process of doing so is shown in the section Creating a FlashArray Workflow) is no different in concept to the previous section on running the REST API workflow—as the workflow is only the REST API action by itself inside of a workflow. Include the action into a workflow and then follow the steps from previous section.

If you are calling the action directly from JavaScript like the method described in the section, Using an Action Inside of a Scriptable Task, then follow these steps.

In this example, we will use the same situation as described in the previous section—enabling an email address as a FlashArray alert recipient. What the workflow will do is take in a FlashArray and an alert recipient (an email address) and then enable that recipient. The workflow is already built with two inputs:

vrops129.png

The workflow has a single scriptable task where the REST API action will be called directly via JavaScript. Both inputs are passed into the scriptable task.

vrops130.png

The action takes in four inputs:

  • FlashArray
  • URI
  • HTTP Method
  • JSON Body

When the action is called in the JavaScript directly it suggests some variable names (flashArray, httpMethod, body and uri).

System.getModule("com.purestoreage.flasharray.restapi").runAPI(flashArray,httpMethod,body,uri)

Since I used the variable name “FlashArray” instead of the suggested “flashArray” I will change the suggested to match mine (JavaScript is case sensitive). I will re-use the other variable names.

System.getModule("com.purestorage.flasharray.restapi").runAPI(FlashArray,httpMethod,body,uri)

When the variable matches an input name, it will change to the pink color as seen above.

Now I need to choose my HTTP method, which is PUT. So I will declare the httpMethod variable that was suggested (any variable needs to be declared if it is not directly passed into the JavaScript from an input) and set it equal to PUT.

var httpMethod = "PUT";

Now I will build my URI. All I need is the following to be sent to the action:

/alert/vroadmin@purestorage.com

As the alert recipient I want to enable is vroadmin@purestorage.com. I can do this by also declaring the uri variable and building this string through concatenation:

 var uri = "/alert/" + alertWatcher;

Finally, I will need to build the body. The body need to look like:

{ "enabled": true }

There are a couple ways to create this. You could literally set the body equal to that string—this would be the simplest option. Though at scale doing this can be tedious and error prone—making it easy to mess up syntax. I recommend building the data types separately as their own variables first. Then using the JSON.stringify() method to build the proper syntax.

Using the JSON.stringify() method, you can build the variety of properties in the body request using standard JavaScript variable types (strings, booleans, arrays, objects) and then have them automatically formatted with proper JSON.

In this case I only have one boolean property called enabled that I need to set to true. So first I will declare a new object variable:

var enabledVar = new Object ();

Then add the boolean value of false to a new property called enabled:

enabledVar.enabled = true;

Then “stringify” it and store it in a newly declared variable (as suggested by the action) called body which will store the information for the body request as a JSON string.

var body = JSON.stringify(enabledVar);

Lastly, I will call the action using my variables (FlashArray, httpMethod, body, and uri):

System.getModule("com.purestorage.flasharray.restapi").runAPI(FlashArray,httpMethod,body,uri);

The action returns a string object in the form of JSON, so if you want to use or log the response, declare a new variable and set the action equal to it:

var.restResponse = System.getModule("com.purestorage.flasharray.restapi").runAPI(FlashArray,httpMethod,body,uri);

My whole script looks like:

var httpMethod = "PUT";
var uri = "/alert/" + alertWatcher;
var enabledVar = new Object();
enabledVar.enabled = true;
var body = JSON.stringify(enabledVar);
var.restResponse = System.getModule("com.purestorage.flasharray.restapi").runAPI(FlashArray,httpMethod,body,uri);

If desired you can log out the response, or pass it to another part of your workflow.

The returned JSON string can be easily converted back to JavaScript standard objects for easier reference and indexing. The JSON.parse() method can be run on the object and the result stored into a new variable. This will return an object, array etc. depending on the REST result.

Save it, and then run it:

 vrops133.png

vrops134.png

Appendix I: Enabling TLS 1.1 and 1.2

The FlashArray Purity Operating Environment requires a more secure form of communication than vRealize 6.0.2 and earlier use by default. While this is fixed in vRO 6.0.3 and later, a change needs to be made to vRO 6.0.2 and earlier to get the plugin communication to the FlashArray to function. The FlashArray does not support TLS versions earlier than 1.1.

Linux Appliance

SSH into vRO and VI into /var/lib/vco/app-server/bin/setenv.sh

vrops135.png

Using VI, edit the line starting with JVM_OPTS=”. Add at the start (after the double quote) the following:

-Dhttps.protocols=TLSv1,TLSv1.1,TLSv1.2

Then a space before the next value. Should look like below:

vrops136.png

Save it and then reboot your vRO appliance.

Windows:

If you are running the Windows version of vRO it is a little different. You need to edit two files:

  1. Open the file with notepad “C:\Program Files\VMware\Orchestrator\app-server\bin\wrapper.conf
  2. Add the following line:

java.additional.21=”-Dhttps.protocols=TLSv1,TLSv1.1,TLSv1.2″

vrops137.png

  1. Add the exact same line to the file named “wrapper-auto.conf” in the same directory.
  2. Reboot the vRO Windows machine

About the Author

vrops138.png

Cody graduated from the Pennsylvania State University with a bachelors degreee in Information Sciences & Technology in 2008. Special areas of focus include core ESXi storage, vRealize (Orchestrator, Automation and Log Insight), Site Recovery Manager and PowerCLI. Cody has been named a VMware vExpert from 2013 through 2016.

Blog: www.codyhosterman.com

Twitter: www.twitter.com/codyhosterman

YouTube: https://www.youtube.com/codyhosterman