vDocumentation provides a community-created set of PowerCLI scripts that produce infrastructure documentation of vSphere environments in CSV or Excel file format. It was presented for general public use in VMworld 2017, session SER2077BU. You can watch the video here
https://www.youtube.com/watch?v=-KK0ih8tuTo
Original slides are here as well as the mindmap we used to create this talk. We are passionate about this subject so please use the slides or let us know what you would like to add to the MindMap, and we can continue improving this presentation.
Paste in a PowerShell window that has been Run as Administrator and answer Y
Set-ExecutionPolicy RemoteSigned
Set-PowerCLIConfiguration -InvalidCertificateAction Ignore
You can now close the PowerShell window that ran as Administrator
In a new normal PowerShell console paste all of the below answering Y (this only affects your user, and it may take a while)
Install-Module -Name VMware.PowerCLI -Scope CurrentUser
Install-Module ImportExcel -scope CurrentUser
Install-Module vDocumentation -Scope CurrentUser
vDocumentation is now installed! You can verify with
Get-Module vDocumentation -ListAvailable | Format-List
The vDocumentation module gives you four new PowerCLI Commands you can use to create documentation of a vSphere environment
Before you can use them, connect to your vCenter(s) using PowerCLI
Connect-VIServer [IP_or_FQDN_of_vCenter] # Connect to one, or repeat for many vCenters
When prompted for credentials use a vCenter Administrator-level account. Once connected you can execute these commands:
| Command | Description |
|---|---|
| Get-ESXInventory | Document host hardware inventory and host configuration |
| Get-ESXIODevice | Document information from HBAs, NICs and other PCIe devices including PCI IDs, MACs, firmware & drivers |
| Get-ESXNetworking | Document networking configuration information such as NICs, vSwitches, VMKernel details |
| Get-ESXStorage | Document storage configurations such as iSCSI details, FibreChannel, Datastores & Multipathing |
Each script will output the corresponding data to terminal, and optionally create a file (XLSX, CSV) with the command name and a timestamp. You can use command switches to customize CSV or Excel output, file path (default is powershell working directory), and the command scope (report on all connected vCenters or just cluster or host).
Running a command without switches will
- report on all virtual datacenters in all connected vCenters
- output to PowerShell terminal only
- include all data tabs for each command
To change this behaviour use these switches:
| Scope | Switch | Description |
|---|---|---|
| Target | -esxi | Get information from a particular host (for several, use commas) |
| Target | -cluster | Get information from a particular cluster (for several, use commas) |
| Target | -datacenter | Get information from a particular virtual datacenter (for several, use commas) |
| Output | -folderPath | Specify the path to save the file name |
| Output | -ExportCSV | The output will be written to a CSV file |
| Output | -ExportExcel | The output will be written to a XLSX file (if ImportExcel module is not installed will do CSV) |
| Info Tab | -Hardware | For Get-ESXInventory: explicitly outputs the Hardware tab |
| Info Tab | -Configuration | For Get-ESXInventory: explicitly outputs the Configuration tab |
| Info Tab | -VirtualSwitches | For Get-ESXNetworking: explicitly outputs the VirtualSwitches tab |
| Info Tab | -VMkernelAdapters | For Get-ESXNetworking: explicitly outputs the VMkernelAdapters tab |
| Info Tab | -PhysicalAdapters | For Get-ESXNetworking: explicitly outputs the PhysicalAdapters tab |
| Info Tab | -StorageAdapters | For Get-ESXStorage: explicitly outputs the StorageAdapters tab |
| Info Tab | -Datastores | For Get-ESXStorage: explicitly outputs the Datastores tab |
You can see the full syntax with the Get-Help command
get-help Get-ESXInventory -ShowWindow
Get-ESXInventory -Hardware
Get-ESXInventory -Configuration
Get-ESXIODevice (only has one tab)
Get-ESXNetworking -VirtualSwitches (standard switch)
Get-ESXNetworking -VirtualSwitches (distributed switch)
Get-ESXNetworking -VMKernelAdapter
Get-ESXNetworking -PhysicalAdapters
Get-ESXStorage -StorageAdapters
Get-ESXStorage -Datastores
iSCSI output thanks to @michael_rudloff, see his
CSV outputs thanks to @magneet_nl, see his
Document your vSphere environment? Yes you can! Blog article with Excel outputs thanks to @mwVme
If the prompt returns without doing anything, you are running latest.
Update-Module VMware.PowerCLI
Update-Module ImportExcel
Update-Module vDocumentation
Uninstall-Module vDocumentation
What if I don't have internet?
- A great guide to follow is https://blogs.vmware.com/PowerCLI/2017/04/powercli-install-process-powershell-gallery.html
How do I know which PowerShell version I am running?
| OS | Default Version | Upgradeable to 5.x |
|---|---|---|
| Windows 7 | 2.0 | Yes, manually |
| Windows Server 2008 R2 | 2.0 | Yes, manually |
| Windows 8 | 3.0 | Yes, manually |
| Windows Server 2012 | 3.0 | Yes, manually |
| Windows 10 | 5.0 | Included |
| Windows Server 2016 | 5.0 | Included |
To upgrade follow links such as https://docs.microsoft.com/en-us/powershell/scripting/setup/windows-powershell-system-requirements?view=powershell-5.1
What if I can't run PowerShell 5.x?
- If ESXi and vCenter are hardened to only talk on TLS v1.2, you need .Net 4.5 or above for PowerShell to support this.
What is the ImportExcel module?
Does this run on PowerCLI core?
- We'd love to know! We haven't tested it yet; expect an update soon.
Why do I get a warning about deprecated features when running the script?
- This is native from PowerCLI as they plan future changes. vDocumentation does not use any feature that is known to be in deprecation plans. You can disable the warnings with
Set-PowerCLIConfiguration -DisplayDeprecationWarnings $false -Scope User
v2.00 Major update, on the backend, mostly safe for actual users
Code cleaning:
Each script module exists now in its own .ps1 file which will allow easier editing by the community
Scripts code optimization and formatting updated
@jpsider championed the removal of the CLS command that would clear screen before starting screen output, and contributed the code, which was included in this release.
Removed:
Get-ESXInventory function (and thus, a report column) removed: Deprecated script Cmdlet - Software/Patch Name(s) from host configuration has been deprecated. What Patches gets pushed can be manually verified using the Build ID
Additions:
@jpsider championed the addition of a -passthru option and contributed the code, which was included in this release.
Get-ESXInventory - Host Configuration script now has the following:
- Gather ESXi Installation Type and Boot source
- Gather ESXi Image Profile
- Gather ESXi Software Acceptance Level
- Gather ESXi Uptime (thanks to the person who asked in #SER2077BU, send us your name to give you credit!)
- Gather ESXi Install Date
Get-ESXIODevice - NIC and HBA script now has the following:
- Updated string match to check for HPSA firmware, as it changed between 5.5, and 6.0 and possibly between firmware versions.
Bug Fixes:
Fixed Get-ESXNetworking script Cmdlet when querying UCS environment, or 3rd party Distributed switches. While the information retrieved is not the same (due to the powershell command, not because of vDocumentation) the script will no longer fail, and will produce what it can.
v1.04 new functionality added:
Updated export-excel so that it does no number conversion (IP addresses are now text) on any of the columns and it auto sizes them. Thanks to @magneet_nl for helping us discover this bug!
v1.03 new functionality added:
Get-ESXInventory: Added RAC Firmware version, BIOS release date.
Get-ESXIODevice: Added support to get HP Smart Array Firmware from PowerCLI
1.02 Formatting & Manifest changes
1.01 Changes to support displaying datastore multipathing
1.0 First release to PowerShell Gallery with 4 commands: Get-ESXInventory, Get-ESXIODevice, Get-ESXNetworking & Get-ESXStorage
Hi! I'm Ariel Sanchez (https://twitter.com/arielsanchezmor) and this is the result of a dream and the power of the vCommunity. I started a documentation template effort, which can be found here. There is a lot of work pending to be able to call the effort complete, but one very important component that my friend Edgar Sanchez ( https://twitter.com/edmsanchez13 ) has advanced dramatically is the PowerCLI scripting. This repository stores them, and publishes them to the world so they can start being used. We open-sourced and placed in GitHub so they can be further improved by the vCommunity!
The main motivation for this project was the sad state of vSphere infrastructure documentation accessible to many vSphere administrators. It is demoralizing to start a new job, ask for documentation, and find there is none. The situation is bad enough when the documentation is outdated, but even worse when it's plain wrong. It's also challenging to be tasked with creating documentation, realizing that creating it manually would take a long time, and that collecting and customizing all the scripts will take a long time as well.
Thus, our goal is to be able to easily produce documentation "direct from vCenter" that is relevant to what your manager or another VMware administrator wants to see. The best part is, you only need to run the scripts and they create the needed CSV or Excel file for you. This means you can update your documentation at a moment's notice, and even better, review it to identify things in your environment that may not have been easily visible before.
The license on these scripts is a MIT style license - use as you will. Like all the PowerCLI greats have told us before, steal and modify whatever you find useful. We definitely have stolen from all over the internet to create these (and have tried to credit those who we stole from). Special shout-outs to Luc Dekens, William Lam, Alan Renouf, Kyle Ruddy - and many more in the vCommunity.
Our goal is that this project is useful to others and it will be accepted in the official VMware PowerCLI examples. Please, let us know if you found this useful, had trouble running it, or anything that you want to see changed. We are new to GitHub but actively learning - use GitHub or reach out to us on twitter or in the VMware Code Slack (https://code.vmware.com/web/code/join)
To a future where walking into a new place and asking for documentation is greeted with "Yup, we use vDocumentation" and the interested party replies "Perfect!" :)
Get-Help Get-ESXInventory
NAME Get-ESXInventory
SYNOPSIS Get basic ESXi host information
SYNTAX Get-ESXInventory [[-esxi] ] [[-cluster] ] [[-datacenter] ] [-ExportCSV] [-ExportExcel] [-Hardware] [-Configuration] [[-folderPath] ] []
DESCRIPTION Will get inventory information for a vSphere Cluster, Datacenter or individual ESXi host The following is gathered: Hostname, Management IP, RAC IP, ESXi Version information, Hardware information and Host configuration
RELATED LINKS https://github.com/arielsanchezmora/vDocumentation
REMARKS To see the examples, type: "get-help Get-ESXInventory -examples". For more information, type: "get-help Get-ESXInventory -detailed". For technical information, type: "get-help Get-ESXInventory -full". For online help, type: "get-help Get-ESXInventory -online"
Get-Help Get-ESXIODevice
NAME Get-ESXIODevice
SYNOPSIS Get ESXi vmnic* and vmhba* VMKernel device information
SYNTAX Get-ESXIODevice [[-esxi] ] [[-cluster] ] [[-datacenter] ] [-ExportCSV] [-ExportExcel] [[-folderPath] ] []
DESCRIPTION Will get PCI/IO Device information including HCL IDs for the below VMkernel name(s): Network Controller - vmnic* Storage Controller - vmhba* Graphic Device - vmgfx* All this can be gathered for a vSphere Cluster, Datacenter or individual ESXi host
RELATED LINKS https://github.com/arielsanchezmora/vDocumentation
REMARKS To see the examples, type: "get-help Get-ESXIODevice -examples". For more information, type: "get-help Get-ESXIODevice -detailed". For technical information, type: "get-help Get-ESXIODevice -full". For online help, type: "get-help Get-ESXIODevice -online"
Get-Help Get-ESXNetworking
NAME Get-ESXNetworking
SYNOPSIS Get ESXi Networking Details.
SYNTAX Get-ESXNetworking [[-esxi] ] [[-cluster] ] [[-datacenter] ] [-ExportCSV] [-ExportExcel] [-VirtualSwitches] [-VMkernelAdapters] [-PhysicalAdapters] [[-folderPath] ] []
DESCRIPTION Will get Physical Adapters, Virtual Switches, and Port Groups All this can be gathered for a vSphere Cluster, Datacenter or individual ESXi host
RELATED LINKS https://github.com/arielsanchezmora/vDocumentation
REMARKS To see the examples, type: "get-help Get-ESXNetworking -examples". For more information, type: "get-help Get-ESXNetworking -detailed". For technical information, type: "get-help Get-ESXNetworking -full". For online help, type: "get-help Get-ESXNetworking -online"
Get-Help Get-ESXStorage
NAME Get-ESXStorage
SYNOPSIS Get ESXi Storage Details
SYNTAX Get-ESXStorage [[-esxi] ] [[-cluster] ] [[-datacenter] ] [-ExportCSV] [-ExportExcel] [-StorageAdapters] [-Datastores] [[-folderPath] ] []
DESCRIPTION Will get iSCSI Software and Fibre Channel Adapter (HBA) details including Datastores All this can be gathered for a vSphere Cluster, Datacenter or individual ESXi host
RELATED LINKS https://github.com/arielsanchezmora/vDocumentation
REMARKS To see the examples, type: "get-help Get-ESXStorage -examples". For more information, type: "get-help Get-ESXStorage -detailed". For technical information, type: "get-help Get-ESXStorage -full". For online help, type: "get-help Get-ESXStorage -online"
Copyright (c) <2017> Ariel Sanchez and Edgar Sanchez
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
The scripts run inside a PowerShell window using PowerCLI modules. Powershell is available in all modern windows OS, with PowerShell core available for Mac and Linux. Make sure you have the latest PowerCLI installed (you can check here for a video on how to install https://blogs.vmware.com/PowerCLI/2017/05/powercli-6-5-1-install-walkthrough.html)
From the video, these are the useful commands you should have completed before installing vDocumentation:
$psversiontable [enter] = gives you the PowerShell version
get-module VMware* -ListAvailable [enter] = Lists all installed PowerCLI modules, if return empty, install PowerCLI
Find-Module -Name VMware.PowerCLI = checks connectivity to PowerShell Gallery and updates NuGet if needed (yes is default)
Install-Module -Name VMware.PowerCLI -Scope CurrentUser = install PowerCLI as long as you answer Y or A
Make sure that your execution policy allows you to run scripts downloaded from the internet. You do this with a command run in a powershell window that has been launched with "Run as Administrator"
Set-ExecutionPolicy RemoteSigned
and click Y or A
Unless you have proper certificates in your vSphere environment, some of the data collections may fail silently due to a certificate warning. Run this command so you never have to wonder:
Set-PowerCLIConfiguration -InvalidCertificateAction Ignore
Y is default
While not required, having this module installed is recommended, as you can export direct to Excel. Read about ImportExcel module.
Install-Module ImportExcel -scope CurrentUser
vDocumentation was created as a PowerShell module as well, and it's published in the PowerShell Gallery, so we can use the Install-Module command:
Install-Module vDocumentation -scope CurrentUser
If you can't use the online method, use this manual process:
1 Download the two files inside the vDocumentation folder.
2 Browse to the %USERPROFILE%\Documents\WindowsPowerShell\Modules and copy the files inside a folder named vDocumentation
3 Close all PowerShell windows
4 Launch PowerShell again, you should be able to use the vDocumentation functions now
Execute these lines in a PowerShell window that is in your home directory (tested with PS 5)
mkdir Documents\WindowsPowerShell\Modules\vDocumentation
(new-object Net.WebClient).DownloadString("https://raw.githubusercontent.com/arielsanchezmora/vDocumentation/master/powershell/vDocument/vDocument.psd1") > Documents\WindowsPowerShell\Modules\vDocument\vDocumentation.psd1
(new-object Net.WebClient).DownloadString("https://raw.githubusercontent.com/arielsanchezmora/vDocumentation/master/powershell/vDocument/vDocument.psm1") > Documents\WindowsPowerShell\Modules\vDocument\vDocumentation.psm1
exit