Documentation as Code System (DACS)

A few months ago I wrote a post about Documentation as Code which was an extension of a proof of concept (POC) I put together at work.  Simply put, build some awesome gold templates for your documentation in a mark up/mark down format of your choice [1], check it into the SCM [2] of your choice and then have a system collect information for you and fill in the blanks.

There seems to be a bit of interest regarding automatically updating documentation on https://networktocode.slack.com #cicd channel, so, I thought I’d post a few more musings.

[1] POC was using AsciiDoc and AsciiDoctor
[2] POC was using Git

Documentation as Code System (DACS)

Lacking a more creative name, DACS seem to portray what was trying to achieve.

The idea was to create a few containers/microservices to carry tasks to produce documentation.  Some distinct functions that come to mind:

  • Webfront end (basic, to start a new project and start builds)
  • Source Control (external, or, interchangeable). Contains:
    • Gold templates
    • Clone templates which become live artifacts
  • CMDB – Define systems to be documented
    • Hostname
    • IP details
    • Credentials / access method
  • Data gathering
    • Filling the gaps (substituting) data into the templates (and checking into repo)
    • Could also build the learnt CI CMDB and relationships between configuration items here
  • Documentation builders (acsiidoctor in POC, but, interchangeable if other mark up/mark down formats desired)
    • Building the HTML/PDF/desired format
  • Delivering the outputted documentation
    • Uploading to various locations (SCP/FTP/Sharepoint/Documentation store)
    • Emailing to end user

 

The Dream

Architects building a solution pick from gold templates and create a new solution.

  • Consider building gold templates for Business Service Catalogues (BSC) and Technical Service Catalogues (TSC) items.

Build engineers build the solution and add the devices to DACS.  DACS audits the environment and fills in the documentation blanks.    Repositories and end users updated with freshly minted documentation.

Future changes in the environment are then captured and documentation updated by:

  • Scheduled periodic tasks to ensure documentation is up-to-date
  • Triggered by CI/CD pipelines when a change is made in the environment
  • Manually triggered by the change implementer

Diagrams could also be built with the CMDB and relationship information we’ve gathered during data gathering, with, diagrams inserted into the documentation repository/end document.

No more decaying documentation lying around. 🙂

Data flow

Trying to map out the data flow….

 

 

 

Parallels PBAS failing PCI tests

Parallels Business Automation (PBA) version Build ID: 3.3.3-07.23 appears to introduce a number of PCI compliance issues which causes PCI compliance to fail.  The issue was picked up by a PCI scan after upgrade PBAS from 3.3.3-06.48 to 3.3.3-07.23.

The release notes say the following bugs have been addressed, but, appear not to have been:

3225 (267935) PBAS PCI Compliance. Web Application Cross Site Scripting issue has been corrected in the default online store.
3634          Configure PBAS for the PCI Compleance.

Which, doesn’t seem to be the case.

Parallels Business Automation (PBA) forum bugs:

Although not detailed in the PBA release notes this is not the first time Parallels Business Automation/HSPC has been plagued by XSS issues.

Suggests fixes for the XSS issue can be found in this document:

But, it doesn’t detail a fix for the SVN entries PCI issue that is reported.  Simply chmod’ing the directory fixes the PCI issue, but, may not be the best fix.