We're sorry but this page doesn't work properly without JavaScript enabled. Please enable it to continue.
Feedback

Automate IaC documentations with terraform-docs

00:00

Formal Metadata

Title
Automate IaC documentations with terraform-docs
Subtitle
Introduction to terraform-docs and a showcase of a real world example
Title of Series
Number of Parts
637
Author
Contributors
License
CC Attribution 2.0 Belgium:
You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal purpose as long as the work is attributed to the author in the manner specified by the author or licensor.
Identifiers
Publisher
Release Date
Language

Content Metadata

Subject Area
Genre
Abstract
Let's face it: our documentations are more often than not at least one step behind our implementations. This becomes a problem when it prevents our users from effectively using what we produce as developers. In this talk, you will learn from its maintainers an in depth introduction of terraform-docs, how users apply the tool to automate the documentation of Terraform modules to always keep implementation and documentation consistent whenever a part of their code changes. You will also get to know about more possibilities, such as the automated rendering of Jenkins pipelines to execute Terraform code using the same tool.
AutomationSoftware documentationSoftware maintenanceDrop (liquid)Observational studyComputer animation
CodeData structureRow (database)Term (mathematics)InformationModule (mathematics)Coefficient of determinationOrder (biology)Open sourceMultitier architectureElectric generatorFile formatProduct (business)Binary codeFunction (mathematics)Computer fileDifferent (Kate Ryan album)UML
Computer-generated imageryInstallation artCoefficient of determinationLevel (video gaming)Different (Kate Ryan album)File formatMedical imagingComputing platformVariety (linguistics)Computer animation
Coefficient of determinationProcess (computing)File formatCore dumpCuboidComputer animation
NumberData typeFile formatoutputTable (information)Term (mathematics)Touchscreen40 (number)Operator (mathematics)View (database)Endliche ModelltheorieVotingElectric generatorGoodness of fitFile formatDifferent (Kate Ryan album)Variety (linguistics)Internet service providerComputer animation
IntelTerm (mathematics)Integrated development environmentPlanningVariable (mathematics)InjektivitätRevision controlMechanism designComputer fileConfiguration spaceFile formatFunction (mathematics)Module (mathematics)EmailComputer configurationCoefficient of determinationHypermediaGroup actionTouchscreenWater vaporComputer virusDigitizingSign (mathematics)
CodeProjective planeConfiguration spaceWorkstation <Musikinstrument>Message passingRight angleComputer fileCodeSet (mathematics)Repository (publishing)FlagAttribute grammarSelf-organizationGroup actionRevision controlMathematicsOrder (biology)AreaMereologyProcess (computing)Combinational logicFluxPresentation of a groupCASE <Informatik>System callReading (process)40 (number)JSON
Group actionEvent horizonGroup actionMathematicsChainWordGoodness of fitCoefficient of determinationMachine visionMoment (mathematics)Mathematical singularityCombinational logicWhiteboardProper mapProcess (computing)Code2 (number)Function (mathematics)Plug-in (computing)XML
File formatCommon Language InfrastructureFunctional (mathematics)Latent heatCASE <Informatik>Operating systemElectronic signatureComputer fileInterface (computing)Plug-in (computing)MathematicsConfiguration spaceTemplate (C++)Sheaf (mathematics)Moment (mathematics)Point (geometry)Physical systemSelf-organizationFunction (mathematics)ExistenceWordText editorReading (process)FrequencyAuthorizationInstance (computer science)Uniformer RaumDecision theoryCloningGreatest element
Demo (music)Computer fileFile formatView (database)Slide ruleCodeInformation securityGroup actionModule (mathematics)Wechselseitige InformationNormed vector spaceFermat's Last TheoremCubeVariable (mathematics)Open setInstance (computer science)Sampling (statistics)Projective planeDemo (music)Condition numberEmailSpecial unitary groupArmGroup actionMathematicsSystem callNeighbourhood (graph theory)Water vaporReading (process)Function (mathematics)Computer fileRevision controlConfiguration spaceTable (information)Computer animation
Instance (computer science)CodeInformation securityWikiBuildingDemo (music)Mach's principleGroup actionBeta functionData conversionOpen setWindowAuftragsspracheDefault (computer science)Hydraulic jumpDigital filterMathematicsComputer animation
outputRevision controlVariable (mathematics)NumberString (computer science)Instance (computer science)Universal product codeIntegrated development environmentElectronic mailing listCodeComputer fileLink (knot theory)Demo (music)Data typeState of matterMusical ensembleObject (grammar)Shared memoryGroup actionComputer animation
Instance (computer science)Demo (music)WritingOpen setWikiGroup actionWeightSystem on a chipNumberHydraulic jumpComputer fileInformation managementMathematicsRoundness (object)ChainComputer animation
Slide ruleFile formatView (database)Computer fileComputer animation
Element (mathematics)Computer animation
Transcript: English(auto-generated)
Hello everyone, thanks for joining this session. Today I will be talking about automation of infrastructure as code documentation with Terraform docs. My name is Kostro Musavi,
I'm senior DevOps engineer at Matamos and I'm currently one of the maintainers of Terraform docs. More often than not, we as engineers tend to forget about the documentation of the code that we write, irrelevant of the where in this that that code is supposed to run.
Terraform docs is built to help on that regard. So whenever you write a Terraform module, either a standalone module that someone else is going to use it and you might open source it or not, or your actual end product that you use that to actually deploy infrastructure
somewhere, you can use Terraform docs to automatically generate documentation out of that. So what it does essentially, you point it to one particular folder
which hosts all the Terraform tier files and Terraform docs reads them and extract all the information out of the providers, the variables, outputs, and so on. And it can generate essentially different output format. You can get Terraform docs binary from
usual places, you can check out our GitHub release pages, or you can just download and use the docker image that we produce on each release, or you can use any of the
Homebrew, Chocolatey, Scoop. We support a variety of different formats for different platforms because of the fact that most of the users should want to be able to use this. At the core of Terraform docs, we have a bunch of formators which Terraform docs out of the
box supports, namely AsciiDoc, JSON, Markdown, and so on. These are all the supported out of the box formats that you can generally use. One of the most popular format though is a
Markdown table as you can see on the screenshot on the right, it gives a really clear view of what are the inputs, what are the outputs, what is the requirements, what providers have
been used in this particular module, and this is a perfect candidate for generating this documentation and updating and putting them in readme. This format is really popular, it's been extensively being used from a variety of different people. One of the biggest example
is the Terraform AWS module that heavily utilizes this particular format to automatically update their readme. One other interesting format is TFRS HCL or TFRS JSON for that matter.
What you can do is by parsing your Terraform module configuration and extracting and
repopulating Terraform TFRS file. What that means is that you might have a couple of required variables and a couple of already set optional variables. Whenever you want to Terraform plan
HCL format, output it into TFRS file and inject and pass whatever is required on the
fly to that instead of just going and constructing the Terraform TFRS file by hand. This is one of the really good examples that you can use this particular command and formatter on your CI. Whenever you want to run a Terraform plan and apply something
as a prerequisite step, you can generate the HCL TFRS format or JSON format if you want to manipulate it with some tools, for example with the JQ, and then inject the variables that
you want, maybe from environment variables or reading it from file. Anyways, with some mechanism you can just read them and inject them, then let the Terraform TFRS be handed over to Terraform for actual execution. Since version 0.10, we introduced Terraform docs
yaml file, which is a dot configuration file. As you can see on the screenshot on the right, you can pretty much do all the configuration that previously you had to do to the various
CLI flags and attributes. All of them are combined in this file. This is really convenient for the users because first you don't make a mistake to accidentally not pass one particular
flag. It's going to unify user experience among your organization of whoever has access to that
particular repository. So that means that the same set of configuration can be used for automated CI jobs, for whoever is running the the clr command manually on the worker station.
You can onboard colleagues more easily on the project because everything is already in place. They don't necessarily need to understand a new tool to be able to get productive.
Eventually, what you want to do is check in this configuration right next to your code. So whenever you want to run it, you can just simply run the Terraform docs and pass configuration file without any extra flags. It's worth noting that you can still pass additional
flags to it and what it does is it's going to override the value that is specified in the configuration. So any flag takes precedence over the value that is specified in the configuration
file. In the past couple weeks we have been working on a couple of new features that we are really excited to announce them. One of them is the new GitHub action. So what you can do is
to use this new GitHub action to effectively try to do two things. One is to commit changes back to the PR. So I open my PR, I make some changes in the TF file, add a new variable
or new output or whatever changes and I simply just commit and push my changes and the GitHub action is going to take care of the regenerating with me and commit it back to my PR.
The second approach is going to be the exact opposite of this. So you have this assumption that whoever is writing the code should also update the documentation around it. So you can
utilize the GitHub action to make sure that the readme actually has been updated and fail the CI if there is any change detected. The second one failing the CI is a really good
candidate of using it in combination of the Terraform Docs pre-commit book which has been developed by Anton Babenko and it is really powerful and it's really popular so in conjunction
of that you can make sure that there is a job on your CI to fail if the readme has not been updated properly. The second one is that we have implemented a plugin SDK. So you can extend
Terraform Docs and write your own format based on your choosing. So let's say if you want to have some customized templating for the output, the generated output or maybe there's a guideline in your organization that you want to follow that. So you can create a plugin. So essentially what
you need to do there is an interface that you need to implement a function to satisfy that interface with some specific function signature. Then implement the body of that function however
you like. You can define the sections based on your template of your choosing. You can reorder the sections however you like and at the end you just need to register the plugin and then build the binary out of it. So there are two points here. One is that right now we are only
supporting plugin to be written in golang. There is no specific item in our roadmap to support other languages as of yet. We might support it in the future. And secondly,
the plugin SDK at the moment should be considered slightly unstable. We tend to not break API of it as of now but bear that in mind that there might be some breaking changes until we get it
stabilized enough. So when you finish writing the plugin you can just build it, cross-compile it to be able to distribute it for other system architecture, operating system. And one other point here is that the plugin system only works when working with Terraform.x.yml
There is no CLI command for it to be executed so you have to have a Terraform.x config file. Then in the formatted section of that you specify the name of your plugin which you
register. For example in this case the name of the plugin is foo. The formatter of the Terraform.x file should be the name of the plugin and in that case you would be able to write your own plugin and use it to generate the documentation out of it. So now I'm gonna go to
show a demo for the project. So here I created this sample project which only consists of one
main file. It's really a simplified version of the configuration and it's basically just for for demo purposes but it's fully workable. So this is gonna be a header for my documentation
and as you can see here I'm specifying that I want to have the Markdown table output as a format, read my header from this particular file, enable sorting and enable it by a required column,
use the intention of 2 for the headers and show the required columns all the way anyway. So this was the header that is populated, this is the generated output. So what I want to do
to show you is also we are enabling the GitHub action here which is going to just commit any changes that I want back to my peer. So for example if I want to do that I'm just gonna go
and edit this file. I'm just gonna add a new here. I created a change, I'm gonna create a pull request for it. What it does it's going to
in a minute, it's going to update the readme based on my new change here. This is the new variable that I'm currently missing in the readme here.
Right, so here it's still working. Okay so as you see here it's generated the readme and pushed it back to
my peer. So if I come back here right now I have two commits. One of them is automated action which updated my readme based on the changes that I had created in my
peer. So that is it, thanks for joining the talk and I'll be around on the live Q&A for
any questions that you might have. Have a good rest of the conference.