Automate VMware vSphere Documentation with PowerShell and PowerCLI

0

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

Automate-VMware-vSphere-Documentation-with-PowerShell-and-PowerCLI Automate VMware vSphere Documentation with PowerShell and PowerCLI

Automate VMware vSphere Documentation with PowerShell and PowerCLI (image courtesy of VMware)

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:

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)

Download-and-extract-the-As-Built-Report-project Automate VMware vSphere Documentation with PowerShell and PowerCLI

Download and extract the As Built Report project

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.

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

Install-the-PScribo-module-in-PowerShell Automate VMware vSphere Documentation with PowerShell and PowerCLI

Install the PScribo module in PowerShell

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:

Running-the-As-Built-Report-against-VMware-vSphere-vCenter-Server Automate VMware vSphere Documentation with PowerShell and PowerCLI

Running the As Built Report against VMware vSphere vCenter Server

As-Built-Report-configuration-screen Automate VMware vSphere Documentation with PowerShell and PowerCLI

As Built Report configuration screen

Filling-out-the-As-Built-Report-Information-screen Automate VMware vSphere Documentation with PowerShell and PowerCLI

Filling out the As Built Report Information screen

As-Built-Report-Company-Information-screen Automate VMware vSphere Documentation with PowerShell and PowerCLI

As Built Report Company Information screen

As-Built-Report-Email-Configuration Automate VMware vSphere Documentation with PowerShell and PowerCLI

As Built Report Email Configuration

The-As-Built-Report-begins-running Automate VMware vSphere Documentation with PowerShell and PowerCLI

The As Built Report begins running

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.

Rerunning-As-Built-Report-with-credentials-and-configuration-parameter Automate VMware vSphere Documentation with PowerShell and PowerCLI

Rerunning As Built Report with credentials and configuration parameter

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-dev\Reports\vSphere 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
Controlling-the-As-Built-Report-Information-Detail-Level Automate VMware vSphere Documentation with PowerShell and PowerCLI

Controlling the As Built Report Information Detail Level

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

As-Built-Report-output-from-each-documentation-pull Automate VMware vSphere Documentation with PowerShell and PowerCLI

As Built Report output from each documentation pull

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.

As-Built-Report-Table-of-Contents Automate VMware vSphere Documentation with PowerShell and PowerCLI

As Built Report Table of Contents

Sections-from-the-As-Built-Report Automate VMware vSphere Documentation with PowerShell and PowerCLI

Sections from the As Built Report

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.