SERVICE AS-BUILT DOCUMENT GENERATOR

A tool to generate Service (Cluster/Files/Ndb/Flow/Volumes) as-built documentation from Nutanix hosted environment.

Installation
Download the appropriate zip file.

For Mac:

Nutanix_Service_As_Built_Mac_<version>.zip

For Windows:

Nutanix_Service_As_Built_Windows_<version>.zip

Extract the zip file.

On Mac:

Double-click in Finder or via the command line like below:

unzip Nutanix_Service_As_Built_Mac_<version>.zip

On Windows:

Select Extract All in Windows Explorer (or) via the command line like below:

powershell expand-archive
-path "c:<path to zip>\Nutanix_Service_As_Built_Windows_<version>.zip"
-DestinationPath "C:\<path to destination folder>"

Usage

CLUSTER / FILES / VOLUMES

Either of "-n" / "-pc" / "-f" parameters have to be passed to run_as_built executable. Passing more than one parameter from the above selection would result in
error.
To run with clusters that use AD credentials pass the AD login with domain.

Single Cluster or Multi cluster (with same credentials for all clusters)

Without "-m" flag, the same username and password will be used for all the cluster inputs

(Windows)
run_as_built.exe -c "My customer" -s <service_name> -i n
(macOS)
./run_as_built -c "My customer" -s <service_name> -i n

Multi cluster with multiple login credentials

Pass the "-m" flag, and you will be prompted for the credentials of every cluster

(Windows)
run_as_built.exe -c "My customer" -s <service_name> -i n -m
(macOS)
./run_as_built -c "My customer" -s <service_name> -i n -m

Cluster Service Specific

Include Volumes Data in Cluster As-Built

Volumes Data will be included in the Cluster As-Built Document based on the users choice.

Pass the "-iv" flag to include volumes data in cluster As-built document.

If you do not pass the "-iv" flag the user will still be prompted for the choice of [y/n] to either include volumes data or don't
 (Windows)
run_as_built.exe -c "My customer" -s cluster -i n -iv
(macOS)
./run_as_built -c "My customer" -s cluster -i n -iv

vCenter Info Usage

Your /etc/hosts file should have the hostname and IP of vCenter server (if hostname is entered as input).

If you do not wish to gather information from vCenter, use the below command:

(Windows)
run_as_built.exe -c "My customer" -s cluster -i n -xv
(macOS)
./run_as_built -c "My customer" -s cluster -i n -xv

If you are running the tool against multiple ESXi clusters, with multiple login credentials

(Windows)
run_as_built.exe -c "My customer" -s cluster -i n -mv
(macOS)
./run_as_built -c "My customer" -s cluster -i n -mv

To pass/change the default SSL Port number (443) used to log in to vCenter, use:

The default SSL Port Number used to connect to vCenter is 443

(Windows)
run_as_built.exe -c "My customer" -s cluster -i n -pv
(macOS)
./run_as_built -c "My customer" -s cluster -i n -pv

NDB:

If there is any error with data collection from the REST API, the error will be displayed on the prompt, and the data of the same has to be updated manually.

Port 443 needs to be open and accessible between the VM running the tool and the NDB VM.

Provide Admin credentials while running the tool in order to fetch all the NDB server details.

Single VM or Multiple VMs (with same credentials for all VMs)

Without "-m" flag, the same username and password will be used for all the NDB VM inputs

(Windows)
run_as_built.exe -c "My customer" -s ndb
(macOS)
./run_as_built -c "My customer" -s ndb

Multiple Ndb VMs with multiple login credentials

Pass the "-m" flag, and you will be prompted for the credentials of every cluster

(Windows)
run_as_built.exe -c "My customer" -s ndb -m
(macOS)
./run_as_built -c "My customer" -s ndb -m

FLOW:

Either of "-pc" / "-f" parameters have to be passed to run_as_built executable. Passing more than one parameter from the above selection would result in error.
To run with clusters that use AD credentials pass the AD login with domain.
Refer to COMMON NOTE for login into prism central(s) (single/multiple) with multiple credentials.

COMMON NOTE:

The MAC executable has been built on macOS version 10.13.6, so you can only run this executable on same or later versions of macOS.

If there is any error with data collection from the REST API, the error will be displayed on the prompt, and the data of the same has to be updated manually.

Single Prism Central or Multiple Prism Centrals (with same credentials for all PCs) [Except for NDB Service]
 Use the following command to use PC credentials and generate outputs for all the associated clusters.

Without "-m" flag, the same username and password will be used for all the PC inputs

(Windows)
run_as_built.exe -c "My customer" -s <service_name> -i pc
(macOS)
./run_as_built -c "My customer" -s <service_name> -i pc

Multiple Prism Centrals with multiple login credentials [Except for NDB Service]

Pass the "-m" flag, and you will be prompted for the credentials of every Prism Central

(Windows)
run_as_built.exe -c "My customer" -s <service_name> -i pc -m
(macOS)
./run_as_built -c "My customer" -s <service_name> -i pc -m

Input list of host IPs from file [Except for NDB Service]

The input file is a YAML file which has all the IPs or FQDNs. The sample file "user_file_input.yml", is located in the same directory as the executable.

Pass the "-m" flag, and you will be prompted for the credentials of every Cluster/ PC in the file

(Windows)
run_as_built.exe -c "My customer" -s <service_name> -i f
(macOS)
./run_as_built -c "My customer" -s <service_name> -i f

Output:

A Word document will be the output of the execution. The document will be named with the below convention:

<customer name>-<Nutanix cluster name>-Nutanix_Cluster_as_Built-<date>-<time>.docx

Example:
My customer-some_cluster-Nutanix_Cluster_as_Built_2021-10-12_112629.docx

Document help:

Once the document has been created, open and update the TOC (Table of Contents) by right-clicking on the TOC and selecting 'Update Field', then selecting
'Update Entire Table' and then click 'OK'.
Continue through the document filing in any information that could not be sourced from the Nutanix cluster, inserting the appropriate diagrams, reformatting
as needed and removing any red text highlighted in yellow after completing instructed edits.
There is also the possibility that the version of AOS on the cluster may not support certain Nutanix REST API versions. In this case the script will create all the
tables with no data. These tables will need to be filled in manually or removed from the document before handing off to the customer.

Known Issues

Mixed Clusters

Hypervisors

If the Nutanix cluster contains mixed hypervisors, e.g., AHV and ESXi, only the hypervisor host information for the first hypervisor found in the cluster will be
documented. Please update the document manually for any additional hypervisors in the cluster.

Node Hardware

If the Nutanix cluster contains mixed hardware nodes, e.g., NX-3065-G5 and NX-8150-G5, only the image for the first node in the cluster will be captured in the
document. Please update the document manually with the additional image(s).

UCS Hardware

If the Nutanix cluster is installed on UCS hardware, the UCS specific information will have to be added manually from the UCS build template document.

Protection Domains pre AOS 5.0

The protection domain information is not reliably available in AOS version pre 5.0.

Mac OS
Mac OS Security issues

The following message might be displayed when you are downloading the zipped application. This is because the latest version of MacOS only trusts the apps
downloaded from App Store and identified developers. Please follow the steps as shown in the image below to allow execution of the executable.

While running the executable, you might get the below error message. If this is the case, navigate to "System Preferences > Security & Privacy". Select the "General"
tab and click on "Open Anyway" for the executable.

Help command

(Windows)
run_as_built.exe --help

(macOS)
./run_as_built --help

Output
KINDLY REFER TO THE READMEs OF RESPECTIVE SERVICES FOR DETAILED INFORMATION.

Usage: run_as_built [OPTIONS]

Options:
Required arguments: These are the mandatory arguments required
for any service to run document generation.

-c, --customer TEXT Customer name

-s, --service [cluster|files|ndb|flow]
Deployed service to generate As-built
document

Optional arguments for all services:

These are the optional arguments that can be
passed as flags.

-d, --debug Debug the document generation workflow

-m, --multi_user Multiple user accounts required to access
multiple Clusters/VMs

Optional arguments for only 'Cluster' As-built:

These are the optional arguments that can be
passed as flags only when service type is
'Cluster'.

-iv, --include_volumes Include volumes data in cluster as-built

document

-mv, --multi_user_vcenter Multiple user accounts required to access

multiple vCenters

-pv, --ssl_port_vcenter Non-standard vCenter SSL port

-xv, --no_vcenter Exclude vCenter Info
Optional arguments for 'Cluster/Files' As-built:
These are the optional arguments that can be
passed as flags only when service type is
'cluster' or 'files'.

-i, --input_source [pc|n|f] pc for comma separated list of Prism Central

IPs/ FQDNs n for comma separated list of
Nutanix Cluster IPs/ FQDNs f for yml file
input containing Cluster/Prism Central IPs/
FQDNs

Optional arguments for 'Flow' As-built:

These are the optional arguments that can be
passed as flags only when service type is
'Flow'.

-if, --input_flow [pc|f] pc for comma separated list of Prism Central

IPs/ FQDNs f for yml file input containing
Cluster/Prism Central IPs/ FQDNs

--help Show this message and exit.