search

hashicorp / terraform

Terraform enables you to safely and predictably create, change, and improve infrastructure. It is a source-available tool that codifies APIs into declarative configuration files that can be shared amongst team members, treated as code, edited, reviewed, and versioned.
https://www.terraform.io/
Other
41.68k stars 9.41k forks source link

Support comments to assets in configs.File/configs.Module #19604

Closed metmajer closed 5 years ago

metmajer commented 5 years ago

Hi, and thank you for considering my request.

I am the maintainer of https://github.com/segmentio/terraform-docs, currently working on integrating Terraform 0.12's rich value types to be prepared for prime time.

A primary use-case of terraform-docs is the creation of human-readable documentation from a Terraform module. An important part of this documentation is a module's lead comment. Unfortunately, I couldn't find support for this in neither configs.File or configs.Module. Currently, we're using hcl.ast, but we see this deprecated for obvious reasons.

Also, with hcl.ast, we were able to read out comment nodes for Terraform variables and outputs. This has been there historically, but this could be useful in the future to provide structured annotations to be interpreted by third-party tooling (such as a CI/CD pipeline, or doing range validations, etc.).

Any supporting thoughts or plans ahead on getting lead comments (and possibly comments on top of variables and outputs) integrated? Thanks!

apparentlymart commented 5 years ago

Hi @metmajer,

Using HCL lead comments as docstrings isn't a common pattern in Terraform so it hasn't historically been in Terraform's own APIs, though as you saw you could do it by using the HCL parser directly. Terraform traditionally deals with this sort of documentation by specific arguments, like description in variable and output blocks, though I know there isn't any such mechanism for objects within modules, like module and resource blocks.

The main API in HCL2 doesn't make comments available since it's an abstraction over multiple syntaxes (native HCL syntax and JSON syntax), but there's another package hclwrite that is intended for making surgical edits to HCL native syntax files that does retain the comments. Unfortunately they are not currently exposed in its API because that package's API is still in progress, but they are there internally and attached to the block objects so they could potentially be exposed. I think exposing the comments there would give you the closest analog to what you were doing with the HCL API. I won't be able to do that immediately but can look at it at a later time.

The configs package and most other packages in the Terraform repository are not considered to be public API and so are subject to change at any time, and so I would recommend against using this API as a dependency.

metmajer commented 5 years ago

Thanks @apparentlymart for this great summary. As noted in #19603, I'll try to avoid configs and resort to HCL2 instead.

ghost commented 4 years ago

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.

If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.