OPA/Rego — Generating Documentation
In my previous blog entry, I shared details about a tool called konstraint. That entry focused on generating YAML. As a follow up, I will delve deeper into the documentation generation capabilities.
Many programming languages make the use of documentation conventions in code and will often have annotations to support a parser to extract the data to generate documentation.
Konstraint does this for rego language. Let’s have a look at rego header and the available annotations & output documentation:
# @title this is a basic title for my policy
#
# This is the longer explanation of my policy details
# and the opinions it enforces# @enforcement deny # This is the default, but could be dryrun# The line below is used to generate the constraint by linking the resource types of interest to the policy
# @kinds core/pod bigquerydatasets.crnm.cloud.google.com/BigQueryDataset# The line below defines parameters for the ConstraintTemplate. As such, you need to define the Constraints yourself.
# @parameter <name> array string
# @parameter resource_types array string
- @title — This becomes the heading for the policy in the documentation. It will also used in creating a table of contents
- @enforcement — This documents whether the policy is deny or in dryrun mode. The default is deny
- @kinds — Space separated list of resources in apiGroup/resourceName format for the Constraint to attach to.
- @parameter — Defines a parameter for the ConstraintTemplate CRD and its data types
konstraint doc will parse rego files for documentation blocks as shown above and generate a policies.md file with a table of contents and the explanation for each policy.
To demonstrate the tool and the output, I have created a sample repository: https://github.com/patpicos/rego_doc_gen
Conclusion
Automated documentation generation is one more small step in ensuring the documentation is maintained and kept up to date. The make directives can be used in a pre-commit hook or in a CI pipeline to ensure the repository is up to date on every merge.
