Make TerraformHclModule more beginner friendly — Request for docs

[bLuka]

Community Note

• Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request
• Please do not leave "+1" or other comments that do not add relevant new information or questions, they generate extra noise for issue followers and do not help prioritize the request
• If you are interested in working on this issue or have submitted a pull request, please leave a comment

Description

To give some context, I have some experience with Terraform, and can easily find my way out, but it is more complicated with the CDK as some details are language specific, and others are CDK specific.

It's the first time I'm playing around with Terraform modules, and I'm having a hard time understanding how it works, especially using TerraformHclModule. I haven't found any other documentation apart from a short introduction which does not describe how it works, or what the parameters mean.

To make it more beginner friendly, would it make sense to enhance the docs by providing fully functional examples of Terraform modules using TerraformHclModule for example, and add more details over the options you should feed it?

References

I may have missed some, but exact match searches from TerraformHclModule gave very few web results.

[ansgarm]

Hi @bLuka 👋

That is a nice idea! You are right, the example in the docs you linked, assumes familiarity with the AWS VPC module – we could definitely improve this by extending them to explain what is passed and why. And we could of course also add an example using the TerraformHclModule construct (and link it in the docs).

Do you have further ideas / questions we might need to answer to improve our docs with?

[jsteinich]

TerraformHclModule isn't really meant to be used by the average user. Typically module bindings would be generated following the instructions a bit earlier on that docs page. The generated bindings have properties that match the variables and outputs of the module. TerraformHclModule is meant as a fallback if that generation fails for any reason. It's basically using a Terraform module directly and relying on the user to lookup the relevant pieces.

[bLuka]

Hello!

TerraformHclModule is meant as a fallback if that generation fails for any reason

@jsteinich From my understanding, you highlight it's better to have language (let's say Typescript or Python) specific bindings rather than using TerraformHclModule. This is used to generate native Terraform modules instead of using the CDK to do so, is that right?

EDIT: In fact, is TerraformHclModule a way to create new modules or a way to consume the modules? I first was looking for a way to create and publish modules, before thinking of consuming them.

Do you have further ideas / questions we might need to answer to improve our docs with?

@ansgarm After those discussions, I realize few things are still obscure to me:

• From building to publishing a new Terraform module (the documentation already covers how to consume them)
• Why is the doc referring to terraform-aws-modules/vpc/aws? I thing AWS VPCs have native Terraform resources/data sources; what are the benefits of the VPC module compared to the Terraform resource? How is it different?

[ansgarm]

Ah, got it!

The TerraformHclModule is not creating a new module but offered to consume existing HCL modules (e.g. from the Terraform Registry). If you want to create an HCL module using CDKTF, you can use the TFModuleStack construct. We might include something like this into the CDK for Terraform itself at some point in the future.

However, if you plan to consume your modules using CDKTF, creating custom constructs is the recommended way. We could definitely improve the docs of TerraformHclModule to make that more clear.

The terraform-aws-modules/vpc/aws module is a reusable building block that uses e.g. an AWS VPC Terraform resource under the hood. It creates multiple resources and connects them in the right way (supplying lots of sane defaults along the way). The benefit is that you don't have to do all of that on your own as in practice there are lots of resources required to setup an AWS VPC to be ready to use.

[xiehan]

I believe a lot of this should be addressed now by the construct authoring docs introduced in #2084 (especially this page) but from the sound of it it may still be worth adding a short paragraph below the docs for TerraformHclModule talking about what that is/isn't intended to be used for and then pointing to our other docs about Constructs. It may be worth tackling this at the same time as other documentation tasks related to modules, like #2072 and #956.