Step by Step: How to document your environment with the As-Built report by Tim Carman (PowerShell/PowerCLI/PScribo)

So many of us have seen the As Built Report by Tim Carman.  It’s a fantastic resource but if you’re not a strong Powershell/PowerCLI user there are a few steps you may be unaware of.  Follow along from a new workstation perspective and we’ll go through everything you need. This is specific to a basic report using a Windows workstation and VMware vCenter. The As-Built has much more functionality to explore!

First and foremost of course is Powershell. Every newer Windows install will have it by default, let’s check it out.  Click on your START button and type PowerShell.  Right click on Windows PowerShell and choose “Run as administrator”. We’re going to need admin privileges for a few of these steps.

Ok, now we’ve got PowerShell open as Administrator, that’s the hard part. What version do you have? Run the command below, it’ll probably return with a version similar.

$PSVersionTable.PSVersion

Now we can start installing and connecting all the pieces the As-Built script needs to do its work. We’ll need PScribo and PowerCLI. To get those, you have to open the gates a bit as PowerShell is secured by default against random stuff being installed. As this guide is just to make sure you can run the report and see it, we’ll be opening and trusting a few things with a “just open it up” security posture. Please make your own choices and be careful what you install after this post.

Here we’re going to tell PowerShell to run modules and scripts regardless if the code is signed or not. Run the following:

Set-ExecutionPolicy Unrestricted

Let’s reach out to the internet and grab our first module. When you run the install command, PowerShell queries the PowerShell Gallery for the module you want. Think of it like an App Store. Run this:

Install-Module PScribo

So our install started, but as you can see there’s additional dialog to acknowledge. We’re telling PowerShell to use the new method of installing plugins (NuGet) and to trust the PowerShell Gallery (the app store). Chose Y for NuGet and A for the repository. You’ll see some updates happen and then be dropped back to the command prompt. Great work, you’ve installed your first PowerShell module! Now let’s add in some PowerCLI. The workstation I was on had an existing, out of date PowerCLI install and that interfered with this post, let’s clear that out first. Click on start and type appwiz.cpl or navigate to add/remove programs as you like. Select the old PowerCLI and uninstall. If you don’t have PowerCLI installed, this step doesn’t apply.

Now we’re ready to install, run the following commands one at a time. The first line is just if you’d like to see the current version hosted in the PowerShell Gallery and isn’t necessary. After the install is completed, we’ll run the Get-Command to see the VMware commands, proving our install.

Find-Module  -name VMware.PowerCLI

Install-Module -name VMware.PowerCLI -scope CurrentUser

Get-Command -Module *VMware*
Here we can see the VMware commands proving PowerCLI is installed.

Similar to how we configured PowerShell, we’ll now configure PowerCLI. The first command is just to skip a prompt for the Customer Experience Improvement Program and the second enables us to run the scripts . Since the As-Built has unsigned scripts, we’ll need to tell PowerCLI to ignore that.

Set-PowerCLIConfiguration -Scope AllUsers -ParticipateInCeip $false

Set-PowerCLIConfiguration -InvalidCertificateAction Ignore

Now our workstation environment is ready! Let’s get the scripts and get to work. Browse to the GitHub repository. (<–that’s the link) Make sure you’re on the Master branch, then download the .ZIP file and extract the files.

Oh man, we’re so close. Before we run this script, there is an option I want to call out where you can set the detail level of the report. If you browse to the extracted file location, you can edit the vSphere JSON template. If you leave it at the default of 3 across the board, you’re going to get a boat load of information. For your first run, I’d recommend setting a few of the categories to 0 to get a feel for the report. Turn them back on as you like, but understand that’s where you set your detail options. If you make a change, ensure you save the JSON file before you run the report.

This is it! You’re almost there! In PowerShell (and still as Administrator), browse to the location of your extracted scripts.

To run the scripts successfully, we’re going to pass a bunch of information to get the script to do what we want against the stuff we want. Where you see a $field, put in your actual vcenter/username/credentials. You want vCenter admin credentials when you pass this.

.\New-AsBuiltReport.PS1 -Target $vCenter.domain.tld -username $domain\$user -password $yourvcenterpassword -type vSphere -Format Word,HTML -Timestamp -Path C:\$yourpath
Sorry this one is blurry!

PowerShell throws one more warning about the script, hit R to continue and follow along with the prompts. Fill in the requested information if you like or just accept the defaults. Here’s Tim and Matthew presenting at VMworld discussing the report prompts and the output. Once it kicks off, you’ll get a Word doc and an HTML document output. Fantastic resource and I hope this post gets you able to run it. The configuration is up to you.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.