PowerActions v1.0. For use only by VMware and VMware Solution Providers Not a Customer Deliverable

Transcription

1 For use only by VMware and VMware Solution Providers Not a Customer Deliverable

2 Version History Date Ver. Author Description 18 Sept Alan Renouf Updated requirements and format for shared script and security 2 Sept Alan Renouf Updated docs with new format, further detail and screen captures 26 Aug Martin Marinov Initial draft docs Page 2 of 14

3 Contents 1. Overview Description of solution Installation Prerequisites Installation process What is installed Security Frequently encountered problems during installation Using the console Using the script-defined action functionality What is a script Own and shared scripts Rendering the script output Creating a new script for the My Script area Creating a new script for the Shared Scripts area The script format explained Script input parameter type Report formatting options Name and description metadata Executing a script Tips & tricks when using the library Example script Page 3 of 14

4 1. Overview PowerActions 1.1 Description of solution PowerActions integrates the vsphere Web Client and PowerCLI to provide complex automation solutions from within the standard vsphere management client. PowerActions is deployed as a plugin for the vsphere Web Client and will allow you to execute PowerCLI commands and scripts in a vsphere Web Client integrated Powershell console. Furthermore administrators will be able to enhance the native WebClient capabilities with actions and reports backed by PowerCLI scripts persisted on the vsphere Web Client. Have you ever wanted to Right Click an object in the web client and run a PowerCLI script? Now you can! For example I as an Administrator will be able to define a new action for the VM objects presented in the Web client, describe/back this action with a PowerCLI script, save it in a script repository within the Web client and later re-use the newly defined action straight from the VM object context (right click) menu. Or I as an Administrator can create a PowerCLI script that reports all VMs within a Data Center that have snapshots over 30 days old, save it in a script repository within the Web client and later execute this report straight from the Datacenter object context menu. Or better yet, why not share your pre-written scripts with the rest of the vsphere admins in your environment by simply adjusting them to the correct format and adding them to the shared script folder. Page 4 of 14

5 2. Installation PowerActions 2.1 Prerequisites The following is a list of prerequisites needed for using PowerActions, please ensure you meet these requirements as other versions may not have been tested and cannot be guaranteed to work. VMware vsphere 5.1 or later PowerShell Host Machine Windows 2003 Server or newer (*)/Vista or newer.net framework 4.0* PowerShell V1 or V2 (3 and 4 not supported) PowerCLI version supporting your current VMware vsphere version * Note:.NET framework 4.5 is not supported. Windows 2012 Server/Windows 8 and Windows 8.1 come with 4.5 by default, so a downgrade to.net Framework 4.0 is required on these versions of Windows. Administrative privileges (registering a service with VMware Lookup Service and creating a user for SSO) are required for installation, but not for use of the product. Prior to installation, ensure that the PowerShell Host machine and the machine hosting the VMware Lookup Service are synced via the same time source, otherwise cryptic error messages may appear. 2.2 Installation process Please follow the below steps to ensure PowerActions is installed correctly in your environment: Download the PowerActions MSI file and store on the machine to be used as the PowerShell host, launch the MSI file. Page 5 of 14

6 Click Next on the welcome screen Read and accept the EULA and click Next Page 6 of 14

7 Select Browse to select a new location if required, Click Next Enter the local machine's primary network identifier (IP address/hostname) and port. The PowerShell host service will listen on this address. The vsphere Web Client instances that are targets of the fling Page 7 of 14

8 should be able to connect to this machine by this address. A firewall rule will automatically be created which allows connections on this port. Enter the VMware lookup service address and credentials. The lookup service's standard location is The credentials of an SSO Administrator are required in order to register the PowerShell host service and the vsphere Web Client plugin to the lookup service and to create a solution user for PowerActions. Click Install to install PowerActions now all configuration has been provided and click Finish once the installation has been completed. Page 8 of 14

9 The PowerCLI Console and PowerCLI Scripts section should now be available via the web client. 2.3 What is installed On the Windows machine that runs the PowerShell host service: A folder is created under C:\ProgramData\VMware\myNGC. It has a couple of sub-folders: o Logs contains the log files of the PowerShell host service o Scripts contains the "shared" scripts (see the Script Library section of this document). A machine user (service user) under whose credentials the PowerShell host service will run. Change of state concerning VMware lookup service/sso: A solution user, named "myngc" is registered with VMware SSO. This user is not granted special privileges. Two services are registered with lookup service: the PowerShell host service and the vsphere Web Client plugin. Both services are owned by the aforementioned solution user. 2.4 Security The SSO admininistrator credentials provided at installation are only used during installation, these are not saved anywhere. These are only provided so that the back-end service can register with vcenter (this allows the UI plug-in to locate the service). The registration process creates a dedicated "PowerAction SSO Solution User" that is the owner of the registration. All post-installation interaction with the SSO service uses this solution user. Page 9 of 14

10 The password for the PowerAction SSO Solution User is prepopulated by VMware but in some circumstances this may not meet your security requirements and you may receive a similar error to the below: Error Failed to create user due to invalid password. ( MyNgcServiceUser ) If this is the case you can specify a password to use through the MYNGCSERVICEPASSWORD MSI property, e.g.: msiexec /i PowerActions_ msi MYNGCSERVICEPASSWORD=Th!$R0CK$! 2.5 Frequently encountered problems during installation. [Q] During installation, I receive an "invalid principal myngc" error. [A] This is most probably due to an existing user with the same name, either due to another existing installation on the same lookup service instance, or due to the user having been created by other means. [Q] Installation fails after inputting the credentials for the lookup service, yet the credentials are valid. [A] This is most probably due to a clock skew between the machine you're installing the fling on and the VMware Lookup Service/SSO machine. [Q] After installation the Icons for PowerCLI Console and PowerCLI Scripts are not shown in the web client. [A] Restart the web client service or server to allow the service to register itself. 3. Using the console After PowerActions is successfully installed, you can expect a "PowerCLI console" link to appear in the vsphere Web Client's side menu and home page. The console has separate input and output panels. When a command is executed, the results of its execution are displayed in the output panel. During execution, a spinner is displayed in the bottom right corner of the output panel. Some useful information on using the console: The execution of the first command may take longer than expected - it has to wait for logging in the VC. There is a pop-up that contains the standard keyboard shortcuts for using the console. The CLS command is not implemented and will throw an error. However, there is a button which clears the output pane. When a prompt is displayed, the standard keyboard shortcuts (as well as the enter and escape keys) should still work, so no mouse clicking is required to answer prompts. The console has the native PowerShell autocomplete functionality, accessed by using the tab button. The console supports command history (up to N commands). The Page Up and Page Down buttons are used to cycle through the command history. When PowerShell prompts for an object, if the requested type is a known vsphere type, an object selector is available. Page 10 of 14

11 4. Using the script-defined action functionality A "PowerCLI Scripts" link is available after successfully installing PowerActions. Clicking this menu item will lead to a master-details view of the defined scripts. 4.1 What is a script An action defined by a script is, in essence, a PowerCLI scriptblock, which accepts a known VI object type as its first parameter. A script can be interactive and query the user for additional input after its execution has started. 4.2 Own and shared scripts On the top left of the script library, there is a drop-down menu with two options: "My scripts" and "Shared scripts". "My scripts" should contain the scripts that the user themselves has created. These scripts are only visible to the user that has created them, and are completely editable by said user. "Shared scripts" contains scripts which are read-only through the UI and are visible to, and executable by all users. They are backed by ".ps1" files located in the folder. Additional scripts can be added there by putting new files in said folder. The exact format of the files is specified in section 4.5. A restart of the PowerShell host service is needed for the newly added scripts to be visible to users. 4.3 Rendering the script output The fling allows for rendering the output of the script in two formats: action and report Action All the output is rendered as text in a smaller console window Report The output is rendered in a standard web client grid. The output is expected to be homogeneous (otherwise, the fields of the first object are selected as a schema). If the type of the output objects is a managed object, or is a custom object with only one managed object field, then the result rows are firstclass web client objects, and a context menu can be invoked on them, for either further PowerCLI operations, or native vsphere Web Client operations. 5. Creating a new script for the My Script area A new script can be created by clicking the new script icon in the script list. A wizard will be invoked. Argument type: on the first page, the argument type has to be input. Checking the "Expects multiple objects" checkbox will make the script show in the execution dialog for multiple context objects of the selected type in the web client. Otherwise, the script will only be displayed when invoking the action on a single object of the selected type. Name and description: you can input the name, description and output type on this page. Page 11 of 14

12 Script body: the script block's body can be edited on this page. It has a pre-generated params statement, reflecting the script's input object type, and, optionally, a report meta-annotation (see 2.5, "The script format explained"). 6. Creating a new script for the Shared Scripts area A shared script is backed by a.ps1 file in the Scripts ProgramData folder of the PowerShell host. Because it is self-contained, its name and description must be specified in the script itself (see the following section). 6.1 The script format explained The following metadata of a script can be retrieved from the script body (in the case of a shared script, this is all the metadata): Its input parameter type Its output format and additional output formatting options Its name and description 6.2 Script input parameter type All information on the script's input is inferred from its params statement. By convention, the type of its first argument is the type of objects the script is available for. Any additional parameters will be prompted for after selecting the script for execution. They must be marked as mandatory. 6.3 Report formatting options In the first comment block of the script, if the ".MYNGC_REPORT" statement is present, the script will be rendered as a report (see section 4.3.2). It may, or may not, be followed by additional formatting options: the list of columns to display the report and the column to be designated as a key. The columns to display in the report may not be explicitly specified. Then the following strategy is used: If the base type of the row's PSObject is a VI object, If the base type of the row's PSObject is a primitive type, a single column with a field corresponding to the object is displayed. Otherwise, all the object's fields are displayed as rows. The "key" column is the column whose value will be used to identify the row - invoking a context menu on said row will create a context menu for the object that is the column's value, if it is a managed object. If this value is not present, the context object for the row is: If the base type of the row's PSObject is a VI object, the object itself is used as a context object for the column. If the row is a PSCustomObject, and it has exactly one field which is a managed object, it is used as a context object for the column. Specifying the key column is done by adding a KEY(<column-name>) line. The grammar for the report statement (in Backus-Naur form) is: report-statement := <report-header> <report-header><eol><report-options> report-options := <report-columns> <report-columns><eol><key-column> report-columns := <report-columns><eol><column-name> "" Page 12 of 14

13 key-column := KEY(<column-name>) report-header :=.MYNGC_REPORT Examples of valid report statements:.myngc_report KEY(Host).MYNGC_REPORT VM Host Cluster.MYNGC_REPORT Host Cluster ParentFolder KEY(ParentFolder) 6.4 Name and description metadata A script's name and description can be specified in the header as well. The name is found under the.label annotation, and the description is found under the.description annotation. For example: <#.LABEL Power off VM.DESCRIPTION Powers off said virtual machine. #> Shared scripts should at least contain a.label declaration. 6.5 Executing a script A script can be executed on an object by invoking the context menu on an object, selecting the PowerCLI sub-menu and clicking on "Execute Script...". A pop-up dialog with the available scripts for execution for this object is displayed. Next to the script is an icon denoting its output type. When executing a script, it may interact with the user and prompt for additional input, using the same user interface as the console prompts. 6.6 Tips & tricks when using the library - The script list part of the library, as well as the scripts-to-execute list have filtering functionality, which can be used for quickly focusing on the needed script(s). Page 13 of 14

14 6.7 Example script The following example enables a right click report that outputs the Hosts selected to the screen. <#.MYNGC_REPORT PowerActions.LABEL Sample Example Script.DESCRIPTION Example script to use as template. #> param ( [Parameter(Mandatory=$true)] [VMware.VimAutomation.ViCore.Types.V1.Inventory.VMHost] $vhost ); $vhost Page 14 of 14