Automate VMware vSphere Documentation with PowerShell and PowerCLI

Let’s face it, documentation is something that none of us get too excited about. We all know it is a necessary evil, and you are glad when you have it, but if you are like me, you hate to have to create it. In reviewing the top VMWorld sessions, there was a session that caught my attention very quickly and piqued my curiosity – “Documenting Your Virtual Infrastructure with PowerShell and PowerCLI“. All VMware vSphere admins know just how powerful PowerCLI can be in managing and administering vSphere, however, can it possibly be used to automate the process of documentation? After watching the session, I have to say that I was excited to try out the tools and GitHub project that was presented in the session. Let’s take a look at how to Automate VMware vSphere Documentation with PowerShell and PowerCLI to get an introduction to the tools themselves and see how we can use them to quickly and easily document entire vSphere environments in great detail.

The Tools – As Built Report and PScribo

In the session at VMWorld 2018, the prensentation “Documenting Your Virtual INfrastructure with PowerShell and PowerCLI” shed light on the problem that we have all faced – documenting environments is a cumbersome process filled with a hodge-podge of various tools and scripts that we may have all used in times past.  The challenge with documentation is often the presentation of the information.  It is easy to pull various information, but how do you do this quickly and easily in a way that you can produce the desired documentation in a format that is easily readable/consumable?

The presentation highlighted a great Project created by Tim Carman, the author and one of the presenters called the As Built Report.

Presenter Information:

Tim Carman
@tpcarman
timcarman.net
github.com/tpcarman

Matt Allford
@mattallford
virtualtassie.com
github.com/mattallford

Watch the Session here:  https://videos.vmworld.com/searchsite/2018/videoplayer/22416

The As Built Report as I will summarized from Tim’s blog here is a configuration document framework based on PowerShell and a module called PScribo that can automate the process of generating documentation in various formats including HTML, XML, text, and Microsoft Word documents.

This framework allows easily running and getting reports from various environments including VMware vSphere but includes the ability for report creation any IT vendor that supports PowerShell and/or RESTful API interfaces.

Summary of Features:

• Multiple formats outpuit
• Custom styling
• Health Checks
• Date and Time stamps
• Email report delivery

PScribo is an open source module for PowerShell written by Iain Brighton that is able to create documents in standardized formats and creates structure within PowerShell scripts without the need for handling formatting.  Straight from the GitHub page:

PScribo (pronounced ‘skree-bo’) is an open source project that implements a documentation domain-specific language (DSL) for Windows PowerShell, used to create a “document” in a standardised format. The resulting “document” can be exported into various formats by “plugins”, for example, text, HTML, XML and/or Microsoft Word format.

Now that we have a basics of the components of the framework and the required modules, let’s look at what this actually looks like to get up and running with the As Built Report pulling information from a vSphere environment.

Automate VMware vSphere Documentation with PowerShell and PowerCLI

One of the things that really stands out with this project is how easy it is to get up and running.  Part of the design requirements as mentioned in the presentation was to have a solution that was easy to install and used readily available tools.  With that requirement, PowerShell/PowerCLI was the obvious choice.  Getting up and running with the As Built Report is super easy and really only involves two steps:

• Download the As Build Report ZIP file from GitHub
• Install the PScribo module in PowerShell

Once you download the ZIP file, extract it to your working directory (doesn’t matter where, you just need to choose a working directory for pathing, etc)

Now that we have the actual project files in place, let’s make sure we have the PScribo module installed in Powershell.  This can be easily installed from the PowerShell gallery via the normal means using the install-module cmdlet.

Install-Module PScribo

Use the cmdlet to install the module.  You will need to confirm the installation from the untrusted repository.

Once you have the files in place as well as have installed the PScribo module, it is simply a matter of running the PowerShell command.  That simple!  A basic run of the script against a VMware vSphere vCenter Server looks like the following:

.New-AsBuiltReport.ps1 -Target <your vCenter Server> -username <vcenter user> -Password <password> -Type vSphere -Format Word,Html -Timestamp -Path <output path> -Healthchecks

You may be wondering if you have to enter the report configuration information each time.  Actually, there is a parameter built in for this.  After you have run through the configuration once, the configuration json file gets created that can be referenced via the AsBuiltConfigPath parameter with each subsequent run.  Also, as you see below, you can also use the Credentials parameter to make use of stored credentials by way of the Get-Credential cmdlet.

Also, a point to note here – you can control the detail level that is pulled with the As Built Report via the vSphere.json file that is found in the .As-Built-Report-devReportsvSphere directory.  By default the InfoLevel section is set to 3 – Detailed.  This can be changed with the following options:

• 0 – Disabled
• 1 – Summary
• 2 – Information
• 3 – Detailed
• 4 – Adv Detailed
• 5 – Comprehensive

After the As Built Report runs, as you can see you have files created in the formats specified in the parameters.

The final result, the reports themselves, are absolutely beautiful!  I can’t imagine creating this level of detailed reports for a vSphere environment with formatting already taken care of like the As Built Report is able to do.  You get a professional looking report, with table of contents and clickable links in the HTML report for each section.

Takeaways

For me this will absolutely change the way I do documentation for vSphere environments and any others that allow RESTful API interaction.  The ease of which you can generate professional reports for environments is unreal.  Without any PowerCLI or other coding knowledge and only a basic understanding of modifying files, you can easily query and document vSphere to a level of detail and output that you would be hard pressed to find anywhere else, in any other utility.  Do yourself a favor and start using the As Built Report today as it will change the way you document your environment.