Example usage on registry.terraform.io in multiple languages

[mabead]

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

When we look at the CDK documentation (the AWS CDK, not CDK TF), we always have the code snippets in all supported languages. For example, here is the documentation for an AWS lambda in multiple languages:

• typescript
• python
• java
• .NET

Unfortunately, the terraform documentation does not have code snippets for CDK TF supported languages. All the code snippets are only in HCL. Example from https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lambda_function:

It therefore makes it hard for developers to use the CDK-TF because most of the available examples are not in the same language they are using. It requires a mental mapping. Note that I am aware aware that I could use cdktf convert to manually convert all the HCL snippets that I see. But I don't see myself trying to convince my colleagues that it's a fun workflow.

All that being said, do you have plans to update registry.terraform.io to show code snippets in all languages that are supported by CDK TF? I think it would significantly help in the adoption of cdktf.

[skorfmann]

That's certainly something which is on our radar. However, there are no immediate plans to do this.

[mabead]

@skorfmann thanks for the response. Until you have what I would classify like the best solution (i.e. code samples in all languages in registry.terraform.io), if you had an online page like "cdktf-online-converter.com" where people could:

• paste some HCL code
• select the output language
• show the resulting CDKTF code

Then, I think that it could remove some friction around the usage of cdktf.

[skorfmann]

while we don't have a website for this (yet?), that's possible with cdktf convert. Your example above would translate to when copying the code example from the registry: pbpaste | cdktf convert | pbcopy

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";

/*The following providers are missing schema information and might need manual adjustments to synthesize correctly: aws.
For a more precise conversion please use the --provider flag in convert.*/
const awsIamRoleIamForLambda = new aws.iam.IamRole(this, "iam_for_lambda", {
  assumeRolePolicy:
    '{\n  "Version": "2012-10-17",\n  "Statement": [\n    {\n      "Action": "sts:AssumeRole",\n      "Principal": {\n        "Service": "lambda.amazonaws.com"\n      },\n      "Effect": "Allow",\n      "Sid": ""\n    }\n  ]\n}\n',
  name: "iam_for_lambda",
});
new aws.lambdafunction.LambdaFunction(this, "test_lambda", {
  environment: [
    {
      variables: [
        {
          foo: "bar",
        },
      ],
    },
  ],
  filename: "lambda_function_payload.zip",
  functionName: "lambda_function_name",
  handler: "index.test",
  role: awsIamRoleIamForLambda.arn,
  runtime: "nodejs12.x",
  sourceCodeHash: '${filebase64sha256("lambda_function_payload.zip")}',
});

[skorfmann]

Would even work with other language targets: pbpaste | cdktf convert --language python | pbcopy

# Provider bindings are generated by running cdktf get.
# See https://cdk.tf/provider-generation for more details.
import ...gen.providers.aws as aws

# The following providers are missing schema information and might need manual adjustments to synthesize correctly: aws.
# For a more precise conversion please use the --provider flag in convert.
aws_iam_role_iam_for_lambda = aws.iam.IamRole(self, "iam_for_lambda",
    assume_role_policy="""{
      "Version": "2012-10-17",
      "Statement": [
        {
          "Action": "sts:AssumeRole",
          "Principal": {
            "Service": "lambda.amazonaws.com"
          },
          "Effect": "Allow",
          "Sid": ""
        }
      ]
    }
    """,
    name="iam_for_lambda"
)
aws.lambdafunction.LambdaFunction(self, "test_lambda",
    environment=[{
        "variables": [{
            "foo": "bar"
        }
        ]
    }
    ],
    filename="lambda_function_payload.zip",
    function_name="lambda_function_name",
    handler="index.test",
    role=aws_iam_role_iam_for_lambda.arn,
    runtime="nodejs12.x",
    source_code_hash="${filebase64sha256(\"lambda_function_payload.zip\")}"
)

[mabead]

@skorfmann thanks for the example that shows how to use cdktf convert. But as I said in my initial post, I know it's possible to use cdktf converrt but I don't see myself trying to convince my colleagues that are not cli savy to use such a workflow... even more on windows where pbpaste is not present.

[schersh]

@mabead Thanks for filing this issue! We do have this on our radar; because of the way the docs are currently generated for the Terraform Registry there are some technical hurdles that we need to work through to enable a language selector. But it's helpful to have issues like this to show the need and the value!

[DanielMSchmidt]

@mabead would a hosted version of convert be a stepping stone to a proper solution or not help at all? Like a text area to past your code to and a button to convert it to CDK

[mabead]

@DanielMSchmidt We're pretty aligned on that topic (see this comment).

And if it's easy to do, maybe a button like "Convert to cdktf" could be added in registry.terraform.io. This button would post the code snippet to that online version of cdktf.

[mabead]

Hi @skorfmann @schersh . Now that CDK TF is officially released, do you have more precise plans to make code snippets on registry.terraform.io available in multiple languages?