Automagical vCenter Documentation with MkDocs

❓ Why ❓

Everything as Code has been a very popular topic over the last 5 years or so. Mostly, as IT continues to move faster and automation is needed to meet business timelines and guaranteed quality. This past week, I have been helping a customer set standards for Engineering Documentation. One of the standards my employer uses is MkDocs for Documentation as Code.

🗒️ What 🗒️

Python
Python-PIP
PowerShell (Windows) or PowerShell Core (Linux, MacOS)
PowerCLI
MkDocs

🔧 How 🔧

Install All the Software Components

Install python and python-pip for your OS using the links above. I'm using Linux, so the install was:

$ sudo apt install python
$ sudo apt install python-pip

Install Powershell for your OS using the link above. I'm using Linux, so the install was:

$ curl https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --yes --dearmor --output /usr/share/keyrings/microsoft.gpg
$ sudo sh -c 'echo "deb [arch=amd64 signed-by=/usr/share/keyrings/microsoft.gpg] https://packages.microsoft.com/repos/microsoft-debian-bullseye-prod bullseye main" > /etc/apt/sources.list.d/microsoft.list'
$ sudo apt update && sudo apt install -y powershell

Install PowerCLI in PowerShell

$ pwsh
> Install-Module VMware.PowerCLI -Scope CurrentUser

Install mkdocs (and the optional mkdocs material theme)

$ pip install mkdocs
$ pip install mkdocs-material

Automate Your Documentation

Start a New MkDocs Project

$ mkdir mkdocs-project
$ cd mkdocs-project
$ mkdocs new .
INFO    -  Writing config file: ./mkdocs.yml
INFO    -  Writing initial docs: ./docs/index.md

(Optionally) Change the Theme to Material

$ vi mkdocs.yml
site_name: Dennis' Docs
theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - toc.integrate
    - navigation.top
    - search.suggest
    - search.highlight
    - content.tabs.link
    - content.code.annotation
    - content.code.copy
  language: en
  palette:
    - scheme: default
      toggle:
        icon: material/toggle-switch-off-outline
        name: Switch to dark mode
      primary: teal
      accent: purple
    - scheme: slate
      toggle:
        icon: material/toggle-switch
        name: Switch to light mode
      primary: teal
      accent: lime

copyright: |
  &copy; 2023 <a href="https://github.com/dennisfaucher"  target="_blank" rel="noopener">Dennis Faucher</a>

Fire up the Development MkDocs Web Server

This web server will show you your documentation changes live.

 $ mkdocs serve -a 0.0.0.0:8000
WINFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.18 seconds
INFO    -  [08:22:48] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [08:22:48] Serving on http://0.0.0.0:8000/

Write your automation script

You can use any API language that works for you. The vCenter PowerShell API works very well, so I used that. Here is the script I wrote thats authenticates to vCenter, writes the index.md markdown file based on PowerCLI commands, builds the web site, and uses scp to copy the site to my web server. If you need help with password-less ssh/scp, take a look at this post.

(I learned that the escape character for Powershell is "`". Also, so I did not have to show my vCenter password in the script, I created a file in docs named clear_password.txt and put my vCenter password in there.)

$ cd docs
$ vi pwsh_build_vcenter_mkdocs.ps1

# Create the header
echo "# vCenter Automagic MkDocs Documentation" > index.md
echo "" >> index.md
echo "For full documentation visit [mkdocs.org](https://www.mkdocs.org)." >> index.md

# Login to vCenter
Set-PowerCLIConfiguration -InvalidCertificateAction Ignore -Confirm:$false
$Password = Get-Content "/home/dennis/Documents/MkDocs/vcenter-v2/docs/clear_password.txt"
Connect-viserver -server 192.168.1.55 -user administrator@vsphere.local -password $Password

# Build the host information
echo "## 🖥 Host Information 🖥" >> index.md
echo "````````bash" >> index.md
Get-VMHost | select Name,NumCpu,ProcessorType,CpuUsageMhz,MemoryUsageGB,Version |  Format-Table >> /home/dennis/Documents/MkDocs/vcenter-v2/docs/index.md
echo "````````" >> index.md

# Build the VM information
echo "## 🫙 VM Information 🫙" >> index.md
echo "````````bash" >> index.md
Get-VM |select Name,NumCpu,MemoryGB,PowerState | Format-Table >> /home/dennis/Documents/MkDocs/vcenter-v2/docs/index.md
echo "````````" >> index.md


# Build the Datastore information
echo "## 💾 Datastore Information 💾" >> index.md
echo "````````bash" >> index.md
Get-datastore | Format-Table >> /home/dennis/Documents/MkDocs/vcenter-v2/docs/index.md
echo "````````" >> index.md


# Build the vSwitch information
echo "## 🔌 vSwitch 🔌 " >> index.md
echo "````````bash" >> index.md
Get-virtualswitch | Format-Table >> /home/dennis/Documents/MkDocs/vcenter-v2/docs/index.md
echo "````````" >> index.md

# Build the documentation web site
cd /home/dennis/Documents/MkDocs/vcenter-v2
mkdocs build

# Copy the site to the web server
scp -r /home/dennis/Documents/MkDocs/vcenter-v2/site/* dennis@plex-addons:/var/www/html/mkdocs/

🙏 Thank You 🙏

Thanks for taking the time to read this post. I hope you found the post helpful and maybe saved you some time. I love feedback, so please add comments if you have any.

IT in Context

Search This Blog