API docs: Add docs to Terraform backends

[ansgarm]

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

There are currently no docstrings on the constructs we have for Terraform backends.

See this one for example: https://github.com/hashicorp/terraform-cdk/blob/main/packages/cdktf/lib/backends/s3-backend.ts

It should at least include a link to https://www.terraform.io/docs/language/settings/backends/s3.html

References

[aayushharwani-aidash]

@ansgarm I am interested in working on this. Can you plz guide ?

[ansgarm]

Hi @aayushharwani-aidash 👋 Wow! That's great!

I'll use the S3 backend as an example, but feel free to pick your favorite(s) – you also don't have to do all at once to get a PR accepted and merged 🙂

Our backends can be found here and the docs on them are here.

So let's take the S3Backend and the related docs as an example.

The backend has a S3BackendProps type that defines the arguments that you can set on the backend:

terraform-cdk/packages/cdktf/lib/backends/s3-backend.ts

Lines 40 to 44 in 537c7da

	export interface S3BackendProps {
	readonly bucket: string;
	readonly key: string;
	readonly region?: string;
	readonly endpoint?: string;

The docs contain descriptions for those config keys. For example for the region property:

region - (Required) AWS Region of the S3 Bucket and DynamoDB Table (if used). This can also be sourced from the AWS_DEFAULT_REGION and AWS_REGION environment variables.
(...)

A docstring for this property could look like this:

export interface S3BackendProps {
  // ...
  
  /**
   * AWS Region of the S3 Bucket and DynamoDB Table (if used). This can also
   * be sourced from the AWS_DEFAULT_REGION and AWS_REGION environment 
   * variables.
   */
  readonly region?: string;
  // ...

Note: The docs state that the region is required to be set, but in our code region is optional ("?") because it does not need to be set via the S3BackendProps config, but could also be set via an environment variable.

Besides adding docstrings to the properties, it is also useful to add a general docstring to the S3Backend class itself:

terraform-cdk/packages/cdktf/lib/backends/s3-backend.ts

Lines 9 to 12 in 537c7da

	export class S3Backend extends TerraformBackend {
	constructor(scope: Construct, private readonly props: S3BackendProps) {
	super(scope, "backend", "s3");
	}

The introductory section of the backend docs seems to fit quite well. And adding a link to the docs allows the user to access more information if required.

/**
 * Stores the state as a given key in a given bucket on Amazon S3. This backend
 * also supports state locking and consistency checking via Dynamo DB, which
 * can be enabled by setting the dynamodb_table field to an existing DynamoDB
 * table name. A single DynamoDB table can be used to lock multiple remote
 * state files. Terraform generates key names that include the values of the
 * bucket and key variables.
 * 
 * Warning! It is highly recommended that you enable Bucket Versioning on the
 * S3 bucket to allow for state recovery in the case of accidental deletions
 * and human error.
 * 
 * Read more about this backend in the Terraform docs:
 * https://www.terraform.io/language/settings/backends/s3
 */
export class S3Backend extends TerraformBackend {
  constructor(scope: Construct, private readonly props: S3BackendProps) {
    super(scope, "backend", "s3");
  }
  // ...

If there's anything left unclear, feel free to ask! I hope this explains what we had in mind here.

[aayushharwani-aidash]

Thanks @ansgarm , I got your point.