从 terraform + gitlab-ci 系统创建基础架构文档

Question

Our infra pipeline is setup using terraform + gitlab-ci. I am given with task to provide documentation on setup with what's implemented and what's left. I am new to infra world and finding it hard to come up template to start documentation.

So far I thought of having a table with resources needed with details on dependencies, source of the module, additional notes, etc

If you have a template, can you share OR any other suggestions?

Answer 1

For starters, you could try one or both of the below approaches:

a) create a graph of the Terraform resources using its graph command

b) group and then list all of your resources for a specific tag using AWS Resource Groups , specifically its Create Resource Group functionality

Answer 2

The way I do documentation is to keep it as simple as possible, explain how it works, how to use it and also provide instructions on how it was setup from scratch for reference and as an insurance policy. So that if it's destroyed, someone other than the person that set it all up could recreate it.

Since this is just a pipeline there is probably not much to diagram. The structure of documentation I would provide would be something like this and I would add this either as part of the README.md, in Confluence or however your team does documentation.

Summary

1-2 Sentences about the work and why it was created.

How the Repo is Structured

An explanation on how the repo is structured and decisions behind why it was structured the way it was.

How To Use

Provide steps on how a user can use the pipeline

How It Was Created

Provide steps on how it was setup so anybody can manage it and work on it going forward.