tonto22 / vDocumentation

vDocumentation provides a community-created set of PowerCLI scripts that produce infrastructure documentation of vSphere environments in CSV or Excel file format.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

vDocumentation

vDocumentation provides a community-created set of PowerCLI scripts that produce infrastructure documentation of vSphere environments in CSV or Excel file format.

Quickstart for VMworld 2017

First time usage on a brand new machine with PowerShell 5.x and an internet connection

Paste in a PowerShell window that has been Run as Administrator and answer Y

Set-ExecutionPolicy RemoteSigned
Set-PowerCLIConfiguration -InvalidCertificateAction Ignore

Run PowerShell as Administrator

Enable remote scripts and ignore certificate warnings

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

Install PowerCLI, ImportExcel and vDocumentation modules

vDocumentation is now installed! You can verify with

Get-Module vDocumentation -ListAvailable | Format-List

Confirm vDocumentation installation

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).

Command switch options

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-Help Example

Example Outputs

Get-ESXInventory -Hardware

Get-ESXInventory -Hardware

Get-ESXInventory -Configuration

Get-ESXInventory -Configuration

Get-ESXIODevice (only has one tab)

Get-ESXIODevice

Get-ESXNetworking -VirtualSwitches (standard switch)

Get-ESXNetworking -VirtualSwitches

Get-ESXNetworking -VirtualSwitches (distributed switch)

Get-ESXNetworking -VirtualSwitches

Get-ESXNetworking -VMKernelAdapter

Get-ESXNetworking -VMKernelAdapter

Get-ESXNetworking -PhysicalAdapters

Get-ESXNetworking -PhysicalAdapters

Get-ESXStorage -StorageAdapters

Get-ESXStorage -StorageAdapters

Get-ESXStorage -Datastores

Get-ESXStorage -Datastores

iSCSI output thanks to @michael_rudloff, see his full output

michael_iscsi_physical
michael_iscsi_VMKernel
michael_iscsi_iSCSI
michael_iscsi_datastore

CSV outputs thanks to @magneet_nl, see his full output

magneet_csv1
magneet_csv2
magneet_csv3
magneet_csv4

Document your vSphere environment? Yes you can! Blog article with Excel outputs thanks to @mwVme

Upgrading from a previous version

If the prompt returns without doing anything, you are running latest.

Update-Module VMware.PowerCLI
Update-Module ImportExcel
Update-Module vDocumentation

Upgrade Commands

Uninstalling the vDocumentation script

Uninstall-Module vDocumentation

Uninstall vDocumentation

FAQ

What if I don't have internet?

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

Module Changelog

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

vDocumentation backstory

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!" :)

Syntax

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"

Licensing

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.

Installation

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

Installing 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

Execution Policy and Certificate Warnings

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

Excel Module

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

Adding the vDocumentation module

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

install_vDocumentation_1.03

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

One method to copy the needed files from Github to your PC using PowerShell:

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

About

vDocumentation provides a community-created set of PowerCLI scripts that produce infrastructure documentation of vSphere environments in CSV or Excel file format.

License:MIT License


Languages

Language:PowerShell 100.0%