DOCSEARCHbyAlgolia
Submit Docs

CDK Terrain (CDKTN)

repository·main·Indexed 42 days ago

https://github.com/open-constructs/cdk-terrain

A community fork of CDKTF that allows developers to define and provision infrastructure using TypeScript, Python, Java, C#, and Go via OpenTofu or Terraform. It includes a CLI (cdktn-cli) for generating constructs, synthesizing configurations, and deploying stacks.

Tokens
33.3K
Snippets
120
Records
167
Agent score
51%

What's inside CDK Terrain

  2. What is CDK Terrain?

    main
    CDK Terrain (cdktn) is a community-driven continuation of the Cloud Development Kit for Terraform (CDKTF). It allows developers to define Terraform infrastructure using programming languages like TypeScript and Python, which are then synthesized into standard Terraform JSON configuration.

  4. What is CDK Terrain (CDKTN)?

    main
    CDK Terrain (CDKTN) is a community fork of the Cloud Development Kit for Terraform (CDKTF). It allows you to define cloud infrastructure using familiar programming languages (TypeScript, Python, Java, C#, and Go) and provision it via OpenTofu or Terraform. This enables you to leverage your existing programming toolchain for testing and dependency management without needing to learn HashiCorp Configuration Language (HCL).

  5. Understand the documentation generation pipeline

    main

    The documentation generation process follows a pipeline that operates on the MDAST (Markdown Abstract Syntax Tree) using remark/unified. This approach ensures that code blocks are preserved without corruption during sanitization.

    Pipeline Stages

    1. Source: packages/cdktn/.jsii (JSII assembly).
    2. Generation: jsii-docgen creates one large markdown document per language.
    3. Parsing: remark-parse converts markdown into a full MDAST.
    4. Splitting: splitByHeading(tree, 2) divides the tree into a Map of topics based on H2 headings.
    5. Sanitization: sanitizeAst(subtree) walks text, HTML, and link nodes to clean them while skipping code and inlineCode nodes.
    6. Serialization: remark-stringify converts the AST back to markdown.
    7. MDX Fixups: postProcessForMdx() performs string-level fixes (autolinks, escaping braces, etc.).
    8. Composition: compose() wraps content with MDX frontmatter and writes the final .mdx files.

  6. Core components of CDK Terrain

    main

    CDK Terrain is composed of two primary packages:

    1. cdktn-cli: A command-line interface used to initialize, import, and synthesize CDK Terrain applications.
    2. cdktn: A library used to define Terraform resources using programming constructs.

  7. Compatibility with OpenTofu and Terraform

    main
    CDK Terrain is designed to be execution-engine agnostic. It synthesizes standard Terraform configuration, meaning users can run the generated output with either Terraform or OpenTofu without special configuration or feature gaps. This allows you to choose your execution engine based on operational or licensing preferences.

  8. How function availability is tracked and consumed

    main

    Function availability for Terraform and OpenTofu is managed via functions-matrix.json. This file records the stable releases in which every built-in function is available (tracking introductions, removals, and gaps per product).

    This matrix is consumed by two primary processes:

    1. ../scripts/generate.ts: Merges OpenTofu-only functions into the Fn bindings.
    2. ../scripts/generate-function-availability.ts: Emits packages/cdktn/src/functions/function-availability.generated.ts. This file contains the version-constraint map used by the ValidateFunctionVersionSupport mechanism to validate function versions at synthesis time.

  9. Override Terraform functions in bindings

    main

    If you need to skip exposing a function or export it with a modified signature (for example, to improve the UX of variadic parameters), you can use the INTERNAL_METHODS constant in scripts/generate.ts.

    Functions listed in INTERNAL_METHODS will be internalized by adding a _ prefix and the @internal docstring required by JSII. This allows you to then re-export them with a custom signature via packages/cdktn/src/terraform-functions.ts.

  10. Understand the Provider Feature Availability Matrix

    main

    The features-matrix.json file tracks the availability of various Terraform and OpenTofu CLI capabilities (such as provider-defined functions, ephemeral resources, write-only attributes, resource identity, list resources, actions, and state stores). It records which specific CLI releases first emitted these capabilities via the providers schema -json command.

    This matrix is used to drive the ValidateFeatureTargetSupport check during synthesis, ensuring that a project's declared targetVersions are compatible with the features being used.

  11. Maintain Provider Feature Constraints and Schema Emission Boundaries

    main

    The feature availability matrix is used to derive two critical, hand-maintained maps within the repository. Because there is currently no automated drift check, these must be updated manually whenever the matrix changes:

    1. Usage Boundaries: packages/cdktn/src/provider-feature-constraints.ts (specifically the providerFeatureConstraints map). This defines when a feature is supported by the language syntax.

      • Note: There is an asymmetry for OpenTofu provider functions: language support began in version 1.7.0, but the providers schema -json command only started emitting the functions key in version 1.8.0.

    2. Schema Emission Boundaries: packages/@cdktn/provider-schema/src/emission-check.ts (specifically the SCHEMA_EMISSION_BOUNDARIES map). This defines when the providers schema -json command starts including the specific feature key.

  12. Understand the Stack architecture in CDK for Terraform

    main

    In CDK for Terraform, a Stack represents a collection of resources that share a single Terraform state and are deployed as a single unit.

    In complex applications, you can split infrastructure into multiple stacks (e.g., FrontendStack, PostsStack, PreviewStack) to manage lifecycles independently. For example, a dev environment and a prod environment might each have their own instances of these stacks.