Merge pull request #848 from hashicorp/update-module-docs

fix(docs): document module generation

README.md

@@ -17,7 +17,7 @@ HashiCorp Terraform.
 
 ## Overview
 
-CDK for Terraform apps are written in one of the supported programming languages and can leverage the entire ecosystem of Terraform [modules and providers](./docs/working-with-cdk-for-terraform/using-providers-and-modules.md). The application [synthesizes](./docs/working-with-cdk-for-terraform/synthesizing-config.md) Terraform configuration in JSON. Terraform or the CDK for Terraform can then be used to deploy the application.
+CDK for Terraform apps are written in one of the supported programming languages and can leverage the entire ecosystem of Terraform [modules](./docs/working-with-cdk-for-terraform/using-modules.md) and [providers](./docs/working-with-cdk-for-terraform/using-providers.md). The application [synthesizes](./docs/working-with-cdk-for-terraform/synthesizing-config.md) Terraform configuration in JSON. Terraform or the CDK for Terraform can then be used to deploy the application.
 
 The CDK for Terraform project includes two packages:
 
@@ -100,7 +100,7 @@ Choose a language:
 ## Documentation
 
 - Install and run a quick start tutorial at [HashiCorp Learn](https://learn.hashicorp.com/terraform/cdktf/cdktf-install)
-- Learn how to use any [module or provider](./docs/working-with-cdk-for-terraform/using-providers-and-modules.md) with the CDK for Terraform. You can find all modules and providers in the [Terraform Registry](https://registry.terraform.io/).
+- Learn how to use any Terraform [module](./docs/working-with-cdk-for-terraform/using-modules.md) and [provider](./docs/working-with-cdk-for-terraform/using-providers.md) with the CDK for Terraform. You can find all modules and providers in the [Terraform Registry](https://registry.terraform.io/).
 - Explore the CDK for Terraform [CLI](./docs/cli-commands.md).
 - Defining Terraform [outputs](./docs/working-with-cdk-for-terraform/terraform-outputs.md).
 - Using Terraform [remote backend](./docs/working-with-cdk-for-terraform/remote-backend.md).

docs/getting-started/csharp.md

@@ -147,7 +147,7 @@ You specify it in your local `cdktf.json` file, like this:
 ```
 
 Next you need to run `cdktf get` which generates provider-specific bindings.
-To save some time you can also use pre-built provider, please visit the ["Using Providers and Modules"-Guide](../working-with-cdk-for-terraform/using-providers-and-modules.md) for more on that topic.
+To save some time you can also use pre-built providers, please visit the ["Using Providers"-Guide](../working-with-cdk-for-terraform/using-providers.md) for more on that topic.
 
 ## Synthesize Application
 

docs/getting-started/go.md

@@ -158,7 +158,7 @@ You specify it in your local `cdktf.json` file, like this:
 ```
 
 Next you need to run `cdktf get` which generates provider-specific bindings.
-To save some time you can also use pre-built provider, please visit the ["Using Providers and Modules"-Guide](../working-with-cdk-for-terraform/using-providers-and-modules.md) for more on that topic.
+To save some time you can also use pre-built providers, please visit the ["Using Providers"-Guide](../working-with-cdk-for-terraform/using-providers.md) for more on that topic.
 
 ## Generating Go provider bindings
 

docs/getting-started/java.md

@@ -153,7 +153,7 @@ You specify it in your local `cdktf.json` file, like this:
 ```
 
 Next you need to run `cdktf get` which generates provider-specific bindings.
-To save some time you can also use pre-built provider, please visit the ["Using Providers and Modules"-Guide](../working-with-cdk-for-terraform/using-providers-and-modules.md) for more on that topic.
+To save some time you can also use pre-built providers, please visit the ["Using Providers"-Guide](../working-with-cdk-for-terraform/using-providers.md) for more on that topic.
 
 ## Synthesize Application
 

docs/getting-started/python.md

@@ -141,7 +141,7 @@ You specify it in your local `cdktf.json` file, like this:
 ```
 
 Next you need to run `cdktf get` which generates provider-specific bindings.
-To save some time you can also use pre-built provider, please visit the ["Using Providers and Modules"-Guide](../working-with-cdk-for-terraform/using-providers-and-modules.md) for more on that topic.
+To save some time you can also use pre-built providers, please visit the ["Using Providers"-Guide](../working-with-cdk-for-terraform/using-providers.md) for more on that topic.
 
 ## Synthesize Application
 

docs/getting-started/typescript.md

@@ -117,7 +117,7 @@ You specify it in your local `cdktf.json` file, like this:
 ```
 
 Next you need to run `cdktf get` which generates provider-specific bindings.
-To save some time you can also use pre-built provider, please visit the ["Using Providers and Modules"-Guide](../working-with-cdk-for-terraform/using-providers-and-modules.md) for more on that topic.
+To save some time you can also use pre-built providers, please visit the ["Using Providers"-Guide](../working-with-cdk-for-terraform/using-providers.md) for more on that topic.
 
 **Synthesize Application**
 

docs/working-with-cdk-for-terraform/cdktf-json.md

@@ -13,13 +13,20 @@ export enum Language {
   GO = "go",
 }
 
+export interface TerraformDependencyConstraint {
+  readonly name: string; // name of the module / provider
+  readonly source?: string; // path / url / registry identifier for the module / provider
+  readonly version?: string; // version constraint (https://www.terraform.io/docs/language/providers/requirements.html#version-constraints)
+}
+type RequirementDefinition = string | TerraformDependencyConstraint;
+
 export interface Config {
   readonly app?: string; // The command to run in order to synthesize the code to Terraform compatible JSON
   readonly language?: Language; // Target language for building provider or module bindings. Currently supported: `typescript`, `python`, `java`, `csharp`, and `go`
   readonly output: string; // Default: 'cdktf.out'. Where the synthesized JSON should go. Also will be the working directory for Terraform operations
   readonly codeMakerOutput: string; // Default: '.gen'. Path where generated provider bindings will be rendered to.
-  readonly terraformProviders?: string[]; // Terraform Providers to build
-  readonly terraformModules?: string[]; // Terraform Modules to build
+  readonly terraformProviders?: RequirementDefinition[]; // Terraform Providers to build
+  readonly terraformModules?: RequirementDefinition[]; // Terraform Modules to build
 }
 ```
 
@@ -39,7 +46,28 @@ Community providers have to provide a fully qualified name, e.g. to define the D
 
 #### Modules
 
-Similar to 3rd Party providers, the full registry namespace should be provided. Please note that only modules from the registry are supported at this point.
+Similar to 3rd party providers, the full registry namespace should be provided. For local modules please use the object format:
+
+```jsonc
+{
+  // ...
+  "moduleRequirements": [
+    "terraform-aws-modules/vpc/aws@ ~> 3.2.0",
+    {
+      "name": "myLocalModule",
+      "source": "../my-modules/local-module"
+    }
+  ]
+}
+```
+
+#### Version Constraints
+
+In the string format the version can be omitted if you don't want to pin the version down.
+If you want to denote a version you can add a version constraint after the name, separated by an `@`, so `<provider|module>@<constraint>`.
+In the object format the constraint can be added under `version`.
+
+[The structure of a version constraint can be found here.](https://www.terraform.io/docs/language/expressions/version-constraints.html#version-constraint-syntax)
 
 ## Examples
 

docs/working-with-cdk-for-terraform/using-modules.md

@@ -0,0 +1,102 @@
+# Using Terraform Modules
+
+## Installing Terraform Modules
+
+For using Terraform modules on the Terraform Registry, see [cdktf.json](./cdktf-json.md).
+For using Terraform modules from other sources (local, Github, etc), you have two options:
+
+### Generated Terraform Module Bindings
+
+To get typed module bindings you first need to add the module in your `cdktf.json` file. For a local module it might look like this:
+
+```jsonc
+{
+  // ...
+  "terraformModules": [
+    {
+      "name": "my-local-module",
+      "source": "./path/to/local/terraform/module" // relative to cdktf.json file
+    }
+  ]
+}
+```
+
+When you run `cdktf get` the module bindings are generated in the `./.gen` and can be used as `MyLocalModule`.
+
+### `TerraformHclModule`
+
+You can make use of `TerraformHclModule`. This doesn't have type safe inputs/outputs, but allows for creating any terraform module.
+
+TypeScript example:
+
+```typescript
+const provider = new TestProvider(stack, "provider", {
+  accessKey: "key",
+  alias: "provider1",
+});
+
+const module = new TerraformHclModule(stack, "test", {
+  source: "./foo",
+  variables: {
+    param1: "value1",
+  },
+  providers: [provider],
+});
+
+new TestResource(stack, "resource", {
+  name: module.getString("name"),
+});
+```
+
+## Working with Module Outputs
+
+### Terraform Modules with generated bindings
+
+Outputs can be accessed with an `Output` suffix or in the case of python with an `_output`.
+The return type of the outputs is always string, because the output returns an HCL expression representing the underlying Terraform resource.
+
+This means that when the `TerraformOutput` is anything else than a string a typecast is necessary to compile the application (e.g. `mod.numberOutput as number`). This also means if a module returns a list one can not access items or loop over it without using an [escape hatch](./escape-hatch.md).
+
+#### Typescript / Java / C# / Go
+
+```typescript
+import { Construct } from "constructs";
+import { App, TerraformStack, TerraformOutput } from "cdktf";
+// This module can come from a registry or through a local / remote reference
+import MyLocalModule from "./.gen/modules/my-local-module";
+
+class MyStack extends TerraformStack {
+  constructor(scope: Construct, id: string) {
+    super(scope, id);
+
+    const localModule = new MyLocalModule(this, "local-module", {
+      ipAddress: "127.0.0.1",
+    });
+
+    new TerraformOutput(this, "dns-server", {
+      value: localModule.dnsServerOutput,
+    });
+  }
+}
+```
+
+#### Python
+
+```python
+#!/usr/bin/env python
+
+from constructs import Construct
+from cdktf import App, TerraformStack, TerraformOutput
+# This module can come from a registry or through a local / remote reference
+from imports.my_local_module import MyLocalModule
+
+
+class MyStack(TerraformStack):
+    def __init__(self, scope: Construct, ns: str):
+        super().__init__(scope, ns)
+
+        localModule = MyLocalModule(self, "local-module", ip_address='127.0.0.1')
+        TerraformOutput(self, "dns-server", value=localModule.dns_server_output)
+```
+
+### `TerraformHclModule`

docs/working-with-cdk-for-terraform/using-providers-and-modules.md → docs/working-with-cdk-for-terraform/using-providers.md

@@ -1,4 +1,4 @@
-# Using Providers and Modules
+# Using Providers
 
 ## Prebuilt Providers
 
@@ -68,7 +68,7 @@ vim cdktf.json
 ```
 
 In order to use another provider or module, edit the `cdktf.json` file and add the name of the provider.
-For example, to add [DNS Simple](https://www.terraform.io/docs/providers/dnsimple/index.html) provider to the project, edit the `cdktf.json` file and add the provider name to the `terraformProviders` array.
+For example, to add [DNS Simple](https://www.terraform.io/docs/providers/dnsimple/index.html) provider to the project, edit the `cdktf.json` file and add the provider name to the `terraformProviders` array. For details on the version constraint syntax and the alternative object syntax please see the [`cdktf.json` specification](./cdktf-json.md).
 
 ```json
 {
@@ -211,30 +211,3 @@ When using the `cdktf` cli commands, it'll automatically set the process env `TF
 Last but not least, when using multiple stacks within one application, provider caching is a basic prerequisite.
 
 This behaviour can be disabled by setting `CDKTF_DISABLE_PLUGIN_CACHE_ENV` to non null value, e.g. `CDKTF_DISABLE_PLUGIN_CACHE_ENV=1`. This might be desired, when a different cache directory is configured via a `.terraformrc` configuration file.
-
-## Using Modules
-
-For using modules on the terraform registry, see [cdktf.json](./cdktf-json.md).
-
-For using modules from other sources (local, github, etc), you can make use of `TerraformHclModule`. This doesn't have type safe inputs/outputs, but allows for creating any terraform module.
-
-TypeScript example:
-
-```typescript
-const provider = new TestProvider(stack, "provider", {
-  accessKey: "key",
-  alias: "provider1",
-});
-
-const module = new TerraformHclModule(stack, "test", {
-  source: "./foo",
-  variables: {
-    param1: "value1",
-  },
-  providers: [provider],
-});
-
-new TestResource(stack, "resource", {
-  name: module.getString("name"),
-});
-```