role : Make Files and Docs (mkfd)

This role defines a general-purpose text templating engine. Plays that include this role will supply their own variables and templates in the proper locations. The role handles all the heavy-lifting and error checking associated with correctly templating text files. The tool can also handle infrastructure updates, configuration integrity via hashing, and automated documentation generation using LaTeX.

Contact information:
Email: njrusmc@gmail.com
Twitter: @nickrusso42518

Supported platforms
Hosts
LaTeX installation
Role defaults
Role variables
Role handlers
Role templates
Design guidance

Supported platforms

This playbook does not log into any devices and only runs locally on the control machine. It is a perfect choice for risk-averse/conservative organizations that are not willing to automate their production devices yet.

Control machine information:

$ cat /etc/redhat-release
Red Hat Enterprise Linux Server release 7.4 (Maipo)

$ uname -a
Linux ip-10-125-0-100.ec2.internal 3.10.0-693.el7.x86_64 #1 SMP
  Thu Jul 6 19:56:57 EDT 2017 x86_64 x86_64 x86_64 GNU/Linux

$ ansible --version
ansible 2.8.7
  config file = /home/ec2-user/racc/ansible.cfg
  configured module search path = ['/home/ec2-user/.ansible/plugins/modules',
    '/usr/share/ansible/plugins/modules']
  ansible python module location =
    /home/ec2-user/environments/racc287/lib/python3.7/site-packages/ansible
  executable location = /home/ec2-user/environments/racc287/bin/ansible
  python version = 3.7.3 (default, Aug 27 2019, 16:56:53)
    [GCC 4.8.5 20150623 (Red Hat 4.8.5-36)]

Hosts

Typically this role is included in a play that only contains the control machine. No network connectivity is required for the role to work, although copying files from the control machine to other devices will require SCP or some other mechanism of file transfer.

LaTeX installation

Users who want to take advantage of this role's ability to create PDFs along with text files will need to install TeX Live. After installation, follow the steps to update your PATH variable so that the shell command pdflatex functions.

Download TeX Live: https://www.tug.org/texlive/quickinstall.html

Last, update the texmf.cnf file contained in the correct location (the distribution year changes each year), with openout_any = a which allows pdflatex to create output files in a location outside of the directory structure where the source document exists. This is because PDFs are written to the proper entity folders as files are shuffled around.

Those not interested in using the documentation feature do not need to install LaTeX to use the rest of the role functions. Be sure that doc_name is always set to false, which is a role default, to avoid any LaTeX false negatives. Users can also export openout_any=a as an environment variable, which works nicely for CI/CD pipelines.

$ cat /usr/local/texlive/2018/texmf.cnf
% [comments from the Tex Live maintainers]
openout_any = a

Role defaults

There are several variables defined in the role as defaults. Most of these are intended to be overwritten and are only defined as defaults so that the tasks do not fail catastrophically.

entity_list: By far the most important variable, this contains the list of entities to be templated. The word "entity" is synonymous with the word "system" in that the length of this list should be the number of systems to template. The entity list is not concerned with the composition of each system. Each element in the list should be a dictionary which contains values relevant to that system. The only key that is required is id which is used to uniquely identify the system; it can hold any value. The default setting for this variable is the empty list [], which causes the role do gracefully do nothing when it is not correctly overridden by playbook host_vars/localhost, group_vars/control, or something similar. The directory structure will still be initialized, but the lack of entities means that no templated files can be generated. Example entity_list below.
```
---
entity_list:
- id: system1
  subnet: 10.0.1.0/24
  poc: john doe
  bgp_asn: 65001
- id: system2
  subnet: 10.0.2.0/24
  poc: jane smith
  bgp_asn: 65002
...
```
zip_format: Both the compression type and file extension of the archive. The role default is zip for Windows compatibility. Any option supported by the archive module is supported here, based on current Ansible version. Use ansible-doc archive to see the list of options.
debug_level: The debug verbosity required in order to see role-level task debugging during execution. Set to 1 by default and not commonly overridden, this allows debug to be revealed with the -v option when ansible-playbook is invoked. Debugging generally prints the value of variables processed by the role to stdout for troubleshooting/logging.
current_user: Performs an environment lookup on the USER variable and stores the result. This string can be used in templates and playbooks for comments or troubleshooting, and works nicely when paired with DTG. For example: by "{{ current_user }}" at "{{ DTG }}"
file_mode: The role generates a number of files (discussed more later), and the permissions of the files can be set when the files are created. The default value is 0444 which implies all users can read it, but no one can edit it. This is not commonly overridden, but if it is, a value of 0664 can be used to enable write permissions to the owner and group members. This might be useful when configurations are being created based on limited information (read: need to deliver fast) and this tool is being used as a 90% solution. Note that post-processing changes to output files will invalidate the machine-generated SHA-256 hashes.
make_zip: A true/false question which controls whether to archive all of the resulting text files into a single Windows ZIP bundle. When set to yes, all source files/folders are deleted, leaving only the final bundle. The default value is no, which does not create a bundle and retains all source files/folders. Answering false is an appropriate option for testing and development to rapidly check the output files for correctness. Answering true is an appropriate option for production deliverables. This variable is commonly overloaded within the playbook variables.
zip_name: Optional parameter to provide an alternate, potentially more descriptive name for the ZIP file output generated when make_zip is true. By default, the string "archive" is used.
doc_name: When specified, the role looks for a jinja2 file with this basename with the intent of creating a PDF document using LaTeX. The file must be present in a playbook directory called doc_inputs/. The utility is called pdflatex (https://www.tug.org/applications/pdftex/). Note: Generally speaking, only a .pdf file is accessible after running this utility, which is appropriate for distribution. When pdflatex is invoked, it generates many intermediate files, such as:
- .toc: Table of contents
- .lot: List of tables
- .lof: List of figures
- .aux: Auxiliary compilation data
- .tex: LaTeX source file
- .out: Sectional information about outlines
keep_tex: When doc_name is specified, the .tex file generated by the templater will be retained. This is only valuable for troubleshooting that the jinja2 templating process succeeded before typesetting the file into LaTeX using pdflatex. By default, this file is removed as the end-users should never see it.
skip_sha256: A true/false question that allows an operator to skip the hashing of output files. The value is false by default since security should be both assumed and integration with any provisioning system. Setting this value to true is limited to cases where it is certain that configurations must be hand-edited after generation to meet a specific customer demand. These cases are very rare.
scp: Nested dictionary containing two subkeys below.
- user: The SCP username that can write files to the SCP server.
- host: The SCP server FQDN/IP address. Under its root directory, a directory called racc/ should be created. This is where the archives generated by this playbook are copied.

Role variables

Given the high priority of role variables within Ansible, these are used for constant values. Any set of known-in-advanced and seldom changing information can be enumerated here to offload the complexity of defining constants at the playbook level. Defining complex data structures, like nested dictionaries, lists of dictionaries, etc ... can significantly reduce the playbook level variable input process.

Role tasks

The tasks begin by checking that all entities have an id field. The output is verbose and all entries are checked, even if there are failures early in the list. The list indices (counting from 0) indicate where the failures occur, simplifying the remediation process for the playbook designer.

Following this check, some other error checking around directory/file presence is conducted. The main work is done by populating the

Mkfd

Install / Use

README