The current times provide us with many solutions related to automation as well as the so-called Infrastructure as a Code. Everything would be great, but we must tell ourselves that administrators, engineers, devOps or other technical people are not the only people who want to know how websites, services, and data flows are built.
Therefore, one of the tasks when creating code or providing some functionality is to provide documentation for the solution. VMware, because my work is mainly based on this environment, provided us with vRealize Orchestrator (VMware Aria Orchestrator) version 7.x tools that automatically created workflow documentation.
It was nothing extraordinary and the most important data collected in PDF form that could be used as an attachment to more complete documentation or considered as independent documentation.
Unfortunately, as it happens in the world of IaaC in version 8.x, this solution has not been implemented. Talking behind the scenes with other engineers, everyone said it was a pity that it was missing, but from version to version nothing appeared even on the horizon.
The plus for VMware is that its solution is based on readable XML code and probably the most accurate API I’ve ever worked with. That’s why I decided to create my own workflow that creates documentation and that’s what this article will be about.
The workflow at the time of writing the article is at the stage of testing and corrections and consulting with other vRO users, so it will not be posted here in its entirety yet, but I want to present my ideas to you, and if you are interested and improve all the bugs, I will share it with you.
Workflow requirements:
For certain tasks during the workflow, it uses the local OS, therefore, according to the VMware documentation, an appropriate parameter should be added to the configuration.
we can do it from the GUI
or from the API by hitting the address of our vRO with the ending
/vco-controlcenter/api/properties{
“properties”:
[
{
“key”:”com.vmware.js.allow-local-process”,
“value”:”true”,
“description”:”Allow Orchestrator to run the Command class”
}
]
}
Then we need to restart the server, so we can’t have this functionality in our main documentation workflow because we’ll lose the connection anyway.
The second element that needs to be set on the workflow is adding permissions to some place on the disk on the vRO container, the assumption I made here is the /tmp folder.
We set it in the js-io-rights.conf file, which is also described in the documentation. The file is in this path
/data/vco/usr/lib/vco/app-server/conf/js-io-rights.confI set /tmp to +rwx, i.e. full permissions
Once we meet the prerequisities, we can configure the workflow. At the moment, these are local variables, however, the workflow will be set up to use the configuration file. Before I describe all the variables that we set in detail, let’s take a look at what the workflow looks like.
Workflow
Workflow currently has 4 variables that are entered at startup. And here the question for you, i.e. end users, will the variables that you see here be needed to send an email or files to GIT set as Input or leave them as constant variables in the configuration file?
At the moment, the variables are set inside vRO/Workflow, so here we only need to provide some data.
The first element is inputORchoose, i.e. the question whether we want to provide the name of the workflow along with the full path
If we choose choose we will get a list of all workflows that are available on vRO
My little note to the creators, use names that are unique, because later it may turn out that you have 7 workflows with the same name and you don’t know which one we want to document ?.
The other two elements are checkboxes where we want to get the result of the workflow.
Or it will be sent by e-mail – so in vRO we must have variables configured
The mail will be sent from your settings with the title Documentation Report. Where will there be two attachments. HTML version of the report and a workflow package for which you are making documentation
If we want to use GIT
Here, when uploading, a new branch will be created in the same way with the .html file and the workflow package.
The other variables we need to specify are
As you can see, we have 12 variables in total, so I have to think about whether I want to specify them or hide them in the config.
The workflow itself looks like this
And its simplified version used in nested form looks like this
What can we find in Workflow and Documentation.
Most of the elements are collecting data, properly preparing tables, collecting objects to generate an HTML file. I will not post the code here, but I will describe what we get as a result.
The first element is Workflow Information, name, ID, Version, path and description. As well as a tabular representation of the variables,
Then we go through all the objects that are in the workflow here, I don’t quite like the template yet, so I have to think about how to present it. At the moment, we have tables describing the element, i.e. name, description as well as variables used in the element. The last element that is displayed is a script with syntax coloring for which I use the PRISM functionality https://prismjs.com/
One of the elements that has been added is Copy to Clipboard, because it will be easier for us, for example, to borrow code from other workflows.
Once we go through all the elements, there is information about the Error Handler, if there is one, if not, we have undefined, but it seems to me that to make it look nicer I need to change it
And workflow information that is inserted/used in our documented workflow.
The next element is the diagram. Here, a very big minus for VMware for removing the API that provided us with such a diagram, so I have to dynamically create such a diagram when creating it. Mermaid came to my aid https://mermaid-js.github.io/mermaid/#/
The images you see are set in the generated CSS file and link to the images on vRO. Here is another question. Do you think this solution is sufficient or is it better to download images, send them along with the HTML file and link to the local copy in the code?
But let’s leave that for the official release.
After the diagram, we have information about the actions that are linked in the workflow. Here I used some action that is out-of-box
We also have information about variables
And the script also with colored syntax
Finally, also at the urging of one of the vRO users, we have a handful of statistics
The diagram is generated using AnyChart, however, it is not an open source version, so I have to look for something else.
After the diagram and here I already know that I will put an option such as input, namely whether to include additional documentation of elements that are nested. This is currently done automatically
Once the workflow is done, as I said, or we will receive a set of files by e-mail
Or in a branch on GIT
The entire workflow does not require a long time
And it runs quite smoothly
The only delay I’ve noticed is if we name the workflow manually because we have to do a lot of linear searches.
Maybe we can speed it up somehow.
But that’s the end of my discussion of this workflow. I am asking you for any comments you can give and any improvements you would like to see and I hope that I will release it as soon as possible and you will enjoy it as much as I do.