Home > Blogs > VMware vCenter Orchestrator Blog

vCO PowerShell plug-in

vCenter Orchestrator + PowerShell plug-in = vCenter Orchestrator on steroids. Windows PowerShell is command-line shell and scripting language designed especially for system administration, as such he has wide-spread industry support. There are PowerShell scripts already written for most of the task you will ever need. Enabling vCO user to use and reuse those scripts is one of the most exiting feature of vCO. In short vCO PowerShell plug-in is used to call PowerShell scripts and cmdlets from Orchestrator actions and workflows, and to work with the result.

PowerShell host configuration

One of the drawbacks of PowerShell is that it is windows dependant. That's why we need a Windows machine with PowerShell instaled on it (PowerShell host). Connection between the PowerShell plug-in and PowerShell host machine is established using WinRM or OpenSSH. To configure PowerShell plugin make sure that winrm service is installed on the PowerShell host and run trough following configuration steps.

Procedure

  • Run the following command to set the default WinRM configuration values.
    c:\> winrm quickconfig
  • (Optional) Run the following command on the WinRM service to check whether a listener is running, and verify the default ports.
    c:\> winrm e winrm/config/listener The default ports are 5985 for HTTP, and 5986 for HTTPS.
  • Enable basic authentication on the WinRM service.
    • Run the following command to check whether basic authentication is allowed.
      c:\> winrm get winrm/config
    • Run the following command to enable basic authentication.
      c:\> winrm set winrm/config/service/auth @{Basic="true"}
  • Run the following command to allow transfer of unencrypted data on the WinRM service.
    c:\> winrm set winrm/config/service @{AllowUnencrypted="true"}
  • Enable basic authentication on the WinRM client.
    • Run the following command to check whether basic authentication is allowed.
      c:\> winrm get winrm/config
    • Run the following command to enable basic authentication.
      c:\> winrm set winrm/config/service/auth @{Basic="true"}
  • Run the following command to allow transfer of unencrypted data on the WinRM client.
    c:\> winrm set winrm/config/client @{AllowUnencrypted="true"}
  • [Updated] Run the following command to enable winrm connections from vCO host.
    c:\> winrm set winrm/config/client @{TrustedHosts ="vco_host"} 
  • Run the following command to test the connection to the WinRM service.
    c:\> winrm identify -r:http://winrm_server:5985 -auth:basic -u:user_name -p:password -encoding:utf-8

Before start working with a PowerShell host you need to register it in vCO.

Add_a_PowerShell_host
Add a PowerShell host validates connection to PowerShell and registers the host only if connection is successful. The difference between shared and not shared mode is which user credentials are used to connect to PowerShel host

  • Shared Mode – in this mode all users are using the same credentials
  • Session Per User – in this mode the currently logged user credentials are used

Invoke a PowerShell script

Having an existing PowerShell script you can invoke it without any modifications. Invoke a PowerShell script workflow is suitable for single invocation of script. The result from execution will be available into vCO log tab. This workflow requires you to specify the target host, and the script to be executed. For example we will invoke following script trough vCO:


# Get set of adapters
$adapters  = [System.Net.NetworkInformation.NetworkInterface]::GetAllNetworkInterfaces()
# For each adapter, print out DNS Server Addresses configured
foreach ($adapter in $adapters) {
    $AdapterProperties = $Adapter.GetIPProperties()
    $dnsServers        = $AdapterProperties.DnsAddresses
    if ($dnsServers.Count -gt 0){
$adapter.Description
foreach ($IPAddress in $dnsServers) {
"  DNS Servers ............................. : {0}" -f $ipaddress.IPAddressToString
}
    }
}

This script first gets all the interface objects, then iterates throught them to get the DNS address(es) configured for each one.

Invoke_a_PowerShell_script

Check script output in Log tab.

Invoke_a_PowerShell_script_results1

Invoke an External PowerShell script

Invoke an external script workflows is suitable for running external “.ps1” scripts available on the host machine (.PS1 being the file extension for Windows PowerShell scripts). Required parameters for this workflow are “Name” and “Argument”. The “Name” parameter can be simply the name of the script for example “test.ps1” (if it is available on host machine “Path”) or full path “c:\SomeDirectory\test.ps1”. Script arguments are provided through “Arguments” parameter and the syntax is the same as the one of PowerShell.exe console.

Invoke_an_External_script
Invoke_an_External_script_results

Generate an action from a PowerShell script

PowerShell plug-in allows you to preserve PowerShell script as an action that could be used later in your custom workflows, and even executed on different PowerShell hosts. To achieve this run “Generate an action from a PowerShell script” workflow providing the script. Script customization can be achieved using placeholders. The syntax for defining a placeholder is {#ParamName#}. For each placeholder corresponding action parameter of type string is created in generated action. During action invocation the placeholder is replaced with actual value provided as action parameter.

Generate_an_action_from_a_PowerSHell_script

Generated action looks like.

Generate_an_action_from_a_PowerShell_script_Action

Sample workflow for running the generated action will be generated if “Generate Workflow” option is “Yes”. The workflow will be generated in provided folder and the name of the workflow will be “Invoke Script ” followed by name of generated action.

Generate_an_action_from_a_PowerShell_script_SampleWorkflow

Generate an action for a PowerShell cmdlet

Another feature of the vCO PowerShell plug-in is the ability to generate action based on PowerShell cmdlet. This way you are able to use functionality that is already available in PowerShell inside vCO. To generate action for given PowerShell cmdlet select the cmdlet from inventory tree, and specify which parameter set will be used during action generation.

Generate_an_action_for_a_PowerShell_CmdLet

 

  • More info about VMware vCenter Orchestrator Plug-In for Microsoft Windows PowerShell: release notes, documentation and download
  •  

     



    vCO PowerShell plug-in

    vCenter Orchestrator + PowerShell plug-in = vCenter Orchestrator on steroids. Windows PowerShell is command-line shell and scripting language designed especially for system administration, as such he has wide-spread industry support. There are PowerShell scripts already written for most of the task you will ever need. Enabling vCO user to use and reuse those scripts is one of the most exiting feature of vCO. In short vCO PowerShell plug-in is used to call PowerShell scripts and cmdlets from Orchestrator actions and workflows, and to work with the result.

    PowerShell host configuration

    One of the drawbacks of PowerShell is that it is windows dependant. That's why we need a Windows machine with PowerShell instaled on it (PowerShell host). Connection between the PowerShell plug-in and PowerShell host machine is established using WinRM or OpenSSH. To configure PowerShell plugin make sure that winrm service is installed on the PowerShell host and run trough following configuration steps.

    Procedure

    • Run the following command to set the default WinRM configuration values.
      c:\> winrm quickconfig
    • (Optional) Run the following command on the WinRM service to check whether a listener is running, and verify the default ports.
      c:\> winrm e winrm/config/listener The default ports are 5985 for HTTP, and 5986 for HTTPS.
    • Enable basic authentication on the WinRM service.
      • Run the following command to check whether basic authentication is allowed.
        c:\> winrm get winrm/config
      • Run the following command to enable basic authentication.
        c:\> winrm set winrm/config/service/auth @{Basic="true"}
    • Run the following command to allow transfer of unencrypted data on the WinRM service.
      c:\> winrm set winrm/config/service @{AllowUnencrypted="true"}
    • Enable basic authentication on the WinRM client.
      • Run the following command to check whether basic authentication is allowed.
        c:\> winrm get winrm/config
      • Run the following command to enable basic authentication.
        c:\> winrm set winrm/config/service/auth @{Basic="true"}
    • Run the following command to allow transfer of unencrypted data on the WinRM client.
      c:\> winrm set winrm/config/client @{AllowUnencrypted="true"}
    • [Updated] Run the following command to enable winrm connections from vCO host.
      c:\> winrm set winrm/config/client @{TrustedHosts ="vco_host"} 
    • Run the following command to test the connection to the WinRM service.
      c:\> winrm identify -r:http://winrm_server:5985 -auth:basic -u:user_name -p:password -encoding:utf-8

    Before start working with a PowerShell host you need to register it in vCO.

    Add_a_PowerShell_host
    Add a PowerShell host validates connection to PowerShell and registers the host only if connection is successful. The difference between shared and not shared mode is which user credentials are used to connect to PowerShel host

    • Shared Mode – in this mode all users are using the same credentials
    • Session Per User – in this mode the currently logged user credentials are used

    Invoke a PowerShell script

    Having an existing PowerShell script you can invoke it without any modifications. Invoke a PowerShell script workflow is suitable for single invocation of script. The result from execution will be available into vCO log tab. This workflow requires you to specify the target host, and the script to be executed. For example we will invoke following script trough vCO:

    
    # Get set of adapters
    $adapters  = [System.Net.NetworkInformation.NetworkInterface]::GetAllNetworkInterfaces()
    # For each adapter, print out DNS Server Addresses configured
    foreach ($adapter in $adapters) {
        $AdapterProperties = $Adapter.GetIPProperties()
        $dnsServers        = $AdapterProperties.DnsAddresses
        if ($dnsServers.Count -gt 0){
    $adapter.Description
    foreach ($IPAddress in $dnsServers) {
    "  DNS Servers ............................. : {0}" -f $ipaddress.IPAddressToString
    }
        }
    }
    

    This script first gets all the interface objects, then iterates throught them to get the DNS address(es) configured for each one.

    Invoke_a_PowerShell_script

    Check script output in Log tab.

    Invoke_a_PowerShell_script_results1

    Invoke an External PowerShell script

    Invoke an external script workflows is suitable for running external “.ps1” scripts available on the host machine (.PS1 being the file extension for Windows PowerShell scripts). Required parameters for this workflow are “Name” and “Argument”. The “Name” parameter can be simply the name of the script for example “test.ps1” (if it is available on host machine “Path”) or full path “c:\SomeDirectory\test.ps1”. Script arguments are provided through “Arguments” parameter and the syntax is the same as the one of PowerShell.exe console.

    Invoke_an_External_script
    Invoke_an_External_script_results

    Generate an action from a PowerShell script

    PowerShell plug-in allows you to preserve PowerShell script as an action that could be used later in your custom workflows, and even executed on different PowerShell hosts. To achieve this run “Generate an action from a PowerShell script” workflow providing the script. Script customization can be achieved using placeholders. The syntax for defining a placeholder is {#ParamName#}. For each placeholder corresponding action parameter of type string is created in generated action. During action invocation the placeholder is replaced with actual value provided as action parameter.

    Generate_an_action_from_a_PowerSHell_script

    Generated action looks like.

    Generate_an_action_from_a_PowerShell_script_Action

    Sample workflow for running the generated action will be generated if “Generate Workflow” option is “Yes”. The workflow will be generated in provided folder and the name of the workflow will be “Invoke Script ” followed by name of generated action.

    Generate_an_action_from_a_PowerShell_script_SampleWorkflow

    Generate an action for a PowerShell cmdlet

    Another feature of the vCO PowerShell plug-in is the ability to generate action based on PowerShell cmdlet. This way you are able to use functionality that is already available in PowerShell inside vCO. To generate action for given PowerShell cmdlet select the cmdlet from inventory tree, and specify which parameter set will be used during action generation.

    Generate_an_action_for_a_PowerShell_CmdLet

     

  • More info about VMware vCenter Orchestrator Plug-In for Microsoft Windows PowerShell: release notes, documentation and download
  •  

     

    12 thoughts on “vCO PowerShell plug-in

    1. Mitch Ullman

      Something that is missing from this documentation is the fact that, when using HTTP rather than HTTPS, winrm requires TrustedHosts be populated with the clients (ie: your vcOrchestrator box).
      The way to do that is this:
      c:\> winrm set winrm/config/client @{TrustedHosts =”host1, host2, host3″}

    2. Hans Drolshagen

      Assume WinRM has been configured for HTTPS and that WinRS has been successfully tested with AD credentials. What syntax is used to supply AD credentials in the “Add a Powershell Host” process?

    3. K. Chris Nakagaki

      I’ve tried using user@domain, domain\user, etc, and can’t get it to work. I’m able to successfully connect via HTTPS and Kerberos/Negotiate from a windows client, just not from vCO. Even turning on basic doesn’t seem to work. Certs are all applied correctly.

    4. Ivo Gaydajiev

      Sorry, My previous comment is a bit misleading.
      When using WinRM with Basic authentication it is not possible to use domain users.
      There is a PowerShell plugin update getting ready for release that includes the functionality for Kerberos authentication and will allow usage of domain users.

    5. AnuragR

      Hi,
      I am trying to execute PowerShell script to run the Adfsset.exe through VCO PowerShell plug-in workflow (“Invoke an external script”) on PowerShell host machine(Windows 2008 R2 64bit), workflow complete successfully but it wouldn’t execute AdfsSetup.exe. It start executing script without error but it throws following error when it run AdfsEtup.exe on PowerShell host
      Installing with WUSA: ‘c:\…\KB981002.msu
      Installation of KB981002.msu failed. Error Access Denied
      The PowerShell script file exeSetup.ps1 contains following commandlets
      Echo “executing AdfsSetup”
      &”C:\AdfsSetup.exe” /quiet /logfile “C:\execLog.log”
      If I run the same PowerShell script file though PowerShell console while logged into the PowerShell host machine, it works fine.
      Is there a setting you can change to allow to be installed/execute remotely through VCO workflow?
      -AnuragR

    Comments are closed.