HOW-TO: ABX/vRO Powershell actions which include additional Modules

vRealize Automation Action Based Extensibility (ABX)  and vRealize Orchestrator 8.1 now supports PowerShell as a scripting language for writing Action Based Extensibility (ABX) and Workflow code respectively.

But, how about any dependency modules that you may require for your PowerShell Based ABX & vRealize Orchestration Workflows?

Well, there are two methods of building a script for your extensibility actions:

1. Writing your script directly in the extensibility action editor in vRealize Automation Cloud Assembly or vRealize Orchestration.
2. Creating your script(s) on your local environment then bundle them with any relevant dependencies to a ZIP package, that later you could import to vRealize Automation ABX or vRealize Orchestrator.

In the first case you could simply instruct to load any needed module directly at the Action Dependencies

In this ABX example, I am loading the latest version for Azure PowerShell Modules  as a dependency, but note that this option is valid, if you had connectivity to the public repositories where the modules are stored.

In those situations, where you don’t have access to those public repositories, or simply,  you want to provide your very own modules, you could use option 2, this is, bundle your Extensibility Actions Scripts and Modules into a ZIP package.

The following procedure provides instructions to bundle your PowerShell Script and Modules into a zip that could be used for ABX and/or vRealize Orchestrator, ( we will focus on importing the bundle in ABX but same recommendations apply for doing it at vRealize Orchestrator ).

Before going ahead, couple of things to keep in mind,

Remember using extension .psm1 ( which is standard for dependencies modules for pwsh engine requirements ) , instead of the common .ps1 for the handler (entry point) function file. This is relevant as all additional dependencies packaged will be automatically loaded, meaning that all the imports statements at beginning of the file are not needed and can be removed.

Also, you may need to call public services that are only reachable behind a Proxy, in that case, you might need to implicitly specify your proxy settings in your code:

$proxyString = "http://" + $context.proxy.host + ":" + $context.proxy.port
$Env:HTTP_PROXY = $proxyString
$Env:HTTPS_PROXY = $proxyString 

These instructions will fetch the proxy settings from context object of the function handler and set it as environment property. If the cmdlets support the -Proxy parameter, you can also pass the proxy value directly to the specific PowerShell cmdlets.

Note that in the case of ABX extensibility, the same vRealize Automation Proxy settings are available.

Prerequisites

1. vRealize Automation 8.X ( tested on 8.1 ) or vRealize Automation Cloud with ABX On-Prem.
2. Ubuntu 18.04.4 LTS.
3. PowerShell 6.2.3 is the recommended version, ( however I was able to install Modules with PowerShell 7.0.0 for this example ).

Verify that you are familiar with PowerShell and PowerCLI.

I would recommend to use the same PowerShell version shipped with vRA 8.1,
which can be found here: https://hub.docker.com/r/vmware/powerclicore/

More details here: https://github.com/vmware/powerclicore

It is important to mention that the runtime of ABX and vRealize Orchestrator Extensibility  is Linux-based, therefore, any PowerShell dependencies compiled in a Windows environment might make the generated ZIP package unusable for the creation of extensibility actions, always use a Linux shell ( Photon OS preferable but Ubuntu 18.04 would work ).

Install Powershell

In Ubuntu 18.04 you can install PowerShell for Linux as follows:

sudo apt update
sudo apt -y upgrade
sudo apt-get install -y powershell

check the version of by typing:

pwsh --version

Output

   PowerShell 7.0.0

Pre-install your Powershell Modules in your action root folder

In your local staging system create your ABX action root folder

mkdir abx-powershell
cd abx-powershell
mkdir Modules

Install your modules from PSGallery Repository

pwsh -c Get-PSRepository

Name                      InstallationPolicy   SourceLocation
----                      ------------------   --------------
PSGallery                 Untrusted            https://www.powershellgallery.com/api/v2

In this example, the Az Modules will be used

pwsh -c "Save-Module -Name Az -Path ./Modules/ -Repository PSGallery"  

This instruction will download all the default Az Modules and save them into the Modules folder at my script root level, you can manually remove the ones you don’t need and/or install specifically the ones your script requires ( for loading it faster into execution ).

root@ubuntu_server:~/abx-powershell/Modules#  ls -lrt
drwxr-xr-x 3 root root 4096 May 22 02:50 Az.Maintenance
drwxr-xr-x 3 root root 4096 May 22 02:50 Az.Media
drwxr-xr-x 3 root root 4096 May 22 02:50 Az.Monitor
drwxr-xr-x 3 root root 4096 May 22 02:50 Az.OperationalInsights
drwxr-xr-x 3 root root 4096 May 22 02:50 Az.PrivateDns
drwxr-xr-x 3 root root 4096 May 22 02:50 Az.RecoveryServices
drwxr-xr-x 3 root root 4096 May 22 02:50 Az.Resources
drwxr-xr-x 3 root root 4096 May 22 02:50 Az.ServiceBus
drwxr-xr-x 3 root root 4096 May 22 02:50 Az.ServiceFabric
......
drwxr-xr-x 3 root root 4096 May 22 02:50 Az.Accounts
drwxr-xr-x 3 root root 4096 May 22 02:50 Az.Accounts
drwxr-xr-x 3 root root 4096 May 22 02:50 Az.Advisor
root@ubuntu_server:~/abx-powershell/Modules# 

My principal and only PowerShell Script is

handler.psm1

Here’s an extract of the whole script, note that the Proxy related instructions since my vRealize Automation is behind a proxy and PowerShell needs to load the proxy settings from environment, also there is no need to explicitly indicate to load any modules, this will be done automatically.

handler.psm1

function handler {
  Param($context, $inputs)
  $inputsString = $inputs | ConvertTo-Json -Compress
  $DebugPreference = "Continue"

  $proxyString = "http://" + $context.proxy.host + ":" + $context.proxy.port
  $Env:HTTP_PROXY = $proxyString
  $Env:HTTPS_PROXY = $proxyString

  Write-Host $proxyString
  $proxyUri = new-object System.Uri($proxyString)
  [System.Net.WebRequest]::DefaultWebProxy = new-object System.Net.WebProxy ($proxyUri)
  Write-Host "Inputs were $inputsString"
  # From this point it is my script making calls to MS Azure
  .......

Now let’s package the main handler.psm1 script with the customized installed Modules, once again, your script and dependency elements must be stored at the root level of the ZIP package,

when creating the ZIP package in a Linux environment, you might encounter a problem where the package content is not stored at the root level, make sure to create the package by running the zip -r command in your command-line shell.

root@ubuntu_server:~/powershell/abx-powershell# zip -r --exclude=*.zip -X VRA_Powershell_vro_05.zip .

At this point we can use the ZIP package to create an extensibility action script by importing it at vRealize Automation ABX or vRealize Orchestrator,

In ABX, go to  Cloud Assembly,  Extensibility,  Actions, Create a New Action and associate to your Project

Select PowerShell and Instead of Write Script, Select Import Package and import your zip file. ( e.g. VRA_Powershell_vro_05.zip is a pre-staged working action )

Define inputs required by the script ( see defaults below ) , note that for all actions, whether they are executed in ABX or vRealize Orchestration, they need to have the Main Function matching the name of the script file that contains the entry point function and the actual name of entry point function, in this case handler.handler.

Select your preferred FaaS Provider as On Prem

Save and Test your ABX Action, click on See Details to review your PowerShell Script execution, the first time it will take more time to execute than on regular operation, due to it needs to create and load your action the first time with all its dependencies, subsequent executions will be faster.

In vRealize Orchestration, you can simply create a new Action with similar settings as indicated before for ABX:

Of course, on both cases, you could change the input, set the custom timeout and limits as needed.