Automate IaC documentations with terraform-docs
This is a modal window.
The media could not be loaded, either because the server or network failed or because the format is not supported.
Formal Metadata
| Title |
| |
| Subtitle |
| |
| 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 | 10.5446/52467 (DOI) | |
| Publisher | ||
| Release Date | ||
| Language |
Content Metadata
| Subject Area | ||
| Genre | ||
| Abstract |
|
00:00
AutomationSoftware documentationSoftware maintenanceDrop (liquid)Observational studyComputer animation
00:28
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
01:43
Computer-generated imageryInstallation artCoefficient of determinationLevel (video gaming)Different (Kate Ryan album)File formatMedical imagingComputing platformVariety (linguistics)Computer animation
02:18
Coefficient of determinationProcess (computing)File formatCore dumpCuboidComputer animation
02:43
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
03:39
IntelTerm (mathematics)Integrated development environmentPlanningVariable (mathematics)InjektivitätRevision controlMechanism designComputer fileConfiguration spaceFile formatFunction (mathematics)Module (mathematics)EmailComputer configurationCoefficient of determinationHypermediaGroup actionTouchscreenWater vaporComputer virusDigitizingSign (mathematics)
05:44
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
08:05
Group actionEvent horizonGroup actionMathematicsChainWordGoodness of fitCoefficient of determinationMachine visionMoment (mathematics)Mathematical singularityCombinational logicWhiteboardProper mapProcess (computing)Code2 (number)Function (mathematics)Plug-in (computing)XML
10:19
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
13:05
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
15:29
Instance (computer science)CodeInformation securityWikiBuildingDemo (music)Mach's principleGroup actionBeta functionData conversionOpen setWindowAuftragsspracheDefault (computer science)Hydraulic jumpDigital filterMathematicsComputer animation
15:44
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
16:13
Instance (computer science)Demo (music)WritingOpen setWikiGroup actionWeightSystem on a chipNumberHydraulic jumpComputer fileInformation managementMathematicsRoundness (object)ChainComputer animation
16:29
Slide ruleFile formatView (database)Computer fileComputer animation
16:49
Element (mathematics)Computer animation
Transcript: English(auto-generated)
00:08
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,
00:20
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.
00:47
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
01:07
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
01:21
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
01:50
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
02:03
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
02:28
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
02:48
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
03:02
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
03:26
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.
03:51
What you can do is by parsing your Terraform module configuration and extracting and
04:00
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
04:29
HCL format, output it into TFRS file and inject and pass whatever is required on the
04:42
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
05:06
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
05:26
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
05:53
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
06:11
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
06:30
flag. It's going to unify user experience among your organization of whoever has access to that
06:45
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.
07:04
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.
07:26
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
07:48
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
08:03
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
08:27
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
08:49
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.
09:06
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
09:25
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
09:44
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
10:02
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
10:24
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
10:46
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
11:05
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
11:26
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,
11:41
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
12:01
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
12:28
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
12:42
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
13:11
show a demo for the project. So here I created this sample project which only consists of one
13:22
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
13:44
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,
14:01
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
14:22
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
14:43
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
15:27
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.
15:48
Right, so here it's still working. Okay so as you see here it's generated the readme and pushed it back to
16:10
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
16:26
peer. So that is it, thanks for joining the talk and I'll be around on the live Q&A for
16:40
any questions that you might have. Have a good rest of the conference.