From dd54f88c0e92f96ead5244eacfbeb04cfe78151d Mon Sep 17 00:00:00 2001 From: Anubhav Mishra Date: Fri, 3 Jul 2020 17:46:32 -0700 Subject: [PATCH] docs and examples to trigger build (#134) --- CHANGELOG.md | 12 ++ README.md | 18 +- docs/cli-commands.md | 204 ++++++++++++++++-- docs/getting-started/python.md | 10 +- docs/getting-started/typescript.md | 79 ++++++- .../data-sources.md | 19 ++ package.json | 2 +- .../bin/cmds/helper/terraform-login.ts | 4 +- packages/cdktf-cli/bin/cmds/init.ts | 5 +- packages/cdktf-cli/bin/cmds/synth.ts | 1 - 10 files changed, 318 insertions(+), 36 deletions(-) create mode 100644 docs/working-with-cdk-for-terraform/data-sources.md diff --git a/CHANGELOG.md b/CHANGELOG.md index ed6cf93bc1..61dc8da915 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,15 @@ +## 0.0.7 + +- Support for `cdktf diff` (#90) +- Support for `cdktf deploy` (#92) +- Support for `cdktf destroy` (#111) +- Support for Terraform Cloud via `cdktf login` (#96) +- Support for logging across the project (#100) +- New UI for `cdktf synth` and `cdktf get` (#103) +- Basic error handling support (#110) + +There are other minor bug fixes included in the release. (#109, #122, #128). + ## 0.0.6 - Typescript examples and template defaults for synthesize commands to compile application (#63) diff --git a/README.md b/README.md index e4d3f077b1..d693e6c632 100644 --- a/README.md +++ b/README.md @@ -14,13 +14,17 @@ HashiCorp Terraform. ## Overview -The CDK for Terraform project helps users define infrastructure resources using their programming language of choice and generates a Terraform configuration in JSON that can be applied with `terraform apply`. +The CDK for Terraform project helps users define infrastructure resources using supported programming languages and generates a Terraform configuration in JSON. Users can then use the Terraform or the CDK for Terraform CLI to deploy the application. + +The project uses [AWS CDK](https://aws.amazon.com/cdk/) [constructs](https://github.com/aws/constructs) to define applications. The CDK for Terraform project includes two packages: * [cdktf-cli](./packages/cdktf-cli) - A CLI that allows users to run commands to initialize, import, and synthesize CDK for Terraform applications. * [cdktf](./packages/cdktf-cli) - A library for defining Terraform resources using programming constructs. +The project currently supports TypeScript and Python. + ## Getting Started Choose a language: @@ -36,11 +40,21 @@ Choose a language: ## Documentation -* [cdktf command-line interface](./docs/cli-commands.md). +* 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). * Using the CDK for Terraform [escape hatch](./docs/working-with-cdk-for-terraform/escape-hatch.md). * Using the CDK for Terraform [tokens](./docs/working-with-cdk-for-terraform/tokens.md). +* Using Teraform [data sources](./docs/working-with-cdk-for-terraform/data-sources.md). + +## Contributing and Feedback + +CDK for Terraform is an early experimental project and the development team would love your feedback to help guide the project. + +* Contribute using the [CONTRIBUTING.md](./CONTRIBUTING.md) guide. +* Ask a question on the HashiCorp [Discuss](https://discuss.hashicorp.com/) using the [terraform-cdk](https://discuss.hashicorp.com/c/terraform-core/cdk-for-terraform/) category. +* Report a [bug](https://github.com/hashicorp/terraform-cdk/issues/new?assignees=&labels=bug&template=bug-report.md&title=) or request a new [feature](https://github.com/hashicorp/terraform-cdk/issues/new?assignees=&labels=enhancement&template=feature-request.md&title=). +* Browse all [open issues](https://github.com/hashicorp/terraform-cdk/issues). ## Building diff --git a/docs/cli-commands.md b/docs/cli-commands.md index 4d172b641b..2386c12157 100644 --- a/docs/cli-commands.md +++ b/docs/cli-commands.md @@ -20,13 +20,19 @@ Help output: cdktf [command] Commands: - cdktf get [OPTIONS] Generate CDK Constructs for Terraform providers and modules. - cdktf init [OPTIONS] Create a new cdktf project from a template. - cdktf synth Synthesizes Terraform code for the given app in a directory. [aliases: synthesize] + cdktf deploy [OPTIONS] Deploy the given stack + cdktf destroy [OPTIONS] Destroy the given stack + cdktf diff [OPTIONS] Perform a diff (terraform plan) for the given stack + cdktf get [OPTIONS] Generate CDK Constructs for Terraform providers and modules. + cdktf init [OPTIONS] Create a new cdktf project from a template. + cdktf login Retrieves an API token to connect to Terraform Cloud. + cdktf synth [OPTIONS] Synthesizes Terraform code for the given app in a directory. [aliases: synthesize] Options: - --version Show version number [boolean] - --help Show help [boolean] + --version Show version number [boolean] + --disable-logging Dont write log files. Supported using the env CDKTF_DISABLE_LOGGING. [boolean] [default: true] + --log-level Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL [string] + -h, --help Show help [boolean] Options can be specified via environment variables with the "CDKTF_" prefix (e.g. "CDKTF_OUTPUT") ``` @@ -36,6 +42,10 @@ Options can be specified via environment variables with the "CDKTF_" prefix (e.g * [get](#cdktf-get) * [init](#cdktf-init) * [synth](#cdktf-synth) +* [diff](#cdktf-diff) +* [deploy](#cdktf-deploy) +* [destroy](#cdktf-destroy) +* [login](#cdktf-login) ### cdktf get @@ -55,10 +65,12 @@ cdktf get [OPTIONS] Generate CDK Constructs for Terraform providers and modules. Options: - --version Show version number [boolean] - --help Show help [boolean] - --output, -o Output directory [string] [default: ".gen"] - --language, -l Output programming language [string] [required] + --version Show version number [boolean] + --disable-logging Dont write log files. Supported using the env CDKTF_DISABLE_LOGGING. [boolean] [default: true] + --log-level Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL [string] + --output, -o Output directory for generated Constructs [string] [default: ".gen"] + --language, -l Output programming language [string] [required] [choices: "typescript", "python"] + -h, --help Show help [boolean] ``` Examples: @@ -94,11 +106,16 @@ cdktf init [OPTIONS] Create a new cdktf project from a template. Options: - --version Show version number [boolean] - --help Show help [boolean] - --template The template name to be used to create a new project. [string] [required] [choices: "typescript"] - --dist Install dependencies from a "dist" directory (for development) [string] - --cdktf-version The cdktf version to use while creating a new project. [string] [default: "0.0.2-alpha.2"] + --version Show version number [boolean] + --disable-logging Dont write log files. Supported using the env CDKTF_DISABLE_LOGGING. [boolean] [default: true] + --log-level Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL [string] + --template The template name to be used to create a new project. [string] [choices: "python", "typescript"] + --project-name The name of the project. [string] + --project-description The description of the project. [string] + --dist Install dependencies from a "dist" directory (for development) [string] + --local Use local remote state storage for generated Terraform. [boolean] [default: false] + --cdktf-version The cdktf version to use while creating a new project. [string] [default: "0.0.0"] + -h, --help Show help [boolean] ``` Examples: @@ -126,15 +143,18 @@ $ cdktf synth --help Help output: ``` -cdktf synth +cdktf synth [OPTIONS] Synthesizes Terraform code for the given app in a directory. Options: - --version Show version number [boolean] - --help Show help [boolean] - --app, -a Command to use in order to execute cdktf app [required] - --output, -o Output directory [required] [default: "cdktf.out"] + --version Show version number [boolean] + --disable-logging Dont write log files. Supported using the env CDKTF_DISABLE_LOGGING. [boolean] [default: true] + --log-level Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL [string] + --app, -a Command to use in order to execute cdktf app + --output, -o Output directory [default: "cdktf.out"] + --json Provide JSON output for the generated Terraform configuration. [boolean] [default: false] + -h, --help Show help [boolean] ``` Examples: @@ -150,3 +170,149 @@ Synthesize code when providing a custom command to execute and an output directo ```bash $ cdktf synth --app="npm compile && node main.js" --output="dirname" ``` + +Synthesize code for a given application and output the Terraform JSON configuration. + +```bash +$ cdktf synth --json +``` + +### cdktf diff + +This command generates a diff for a given application by running Terraform plan. + +```bash +$ cdktf diff --help +``` + +Help output: + +``` +cdktf diff [OPTIONS] + +Perform a diff (terraform plan) for the given stack + +Options: + --version Show version number [boolean] + --disable-logging Dont write log files. Supported using the env CDKTF_DISABLE_LOGGING. [boolean] [default: true] + --log-level Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL [string] + --app, -a Command to use in order to execute cdktf app [required] + --output, -o Output directory [required] [default: "cdktf.out"] + -h, --help Show help [boolean] +``` + +Examples: + +Generate a diff for a given application. + +```bash +$ cdktf diff +``` + +### cdktf deploy + +This command deploys a given application. + +```bash +$ cdktf deploy --help +``` + +Help output: + +``` +cdktf deploy [OPTIONS] + +Deploy the given stack + +Options: + --version Show version number [boolean] + --disable-logging Dont write log files. Supported using the env CDKTF_DISABLE_LOGGING. [boolean] [default: true] + --log-level Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL [string] + --app, -a Command to use in order to execute cdktf app [required] + --output, -o Output directory [required] [default: "cdktf.out"] + --auto-approve Auto approve [boolean] [default: false] + -h, --help Show help [boolean] +``` + +Examples: + +Deploy a given application. + +```bash +$ cdktf deploy +``` + +Deploy a given application with auto approval of the diff (Terraform plan). + +```bash +$ cdktf deploy --auto-approve +``` + +### cdktf destroy + +This command destroys a given application. + +```bash +$ cdktf destroy --help +``` + +Help output: + +``` +cdktf destroy [OPTIONS] + +Destroy the given stack + +Options: + --version Show version number [boolean] + --disable-logging Dont write log files. Supported using the env CDKTF_DISABLE_LOGGING. [boolean] [default: true] + --log-level Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL [string] + --app, -a Command to use in order to execute cdktf app [required] + --output, -o Output directory [required] [default: "cdktf.out"] + --auto-approve Auto approve [boolean] [default: false] + -h, --help Show help [boolean] +``` + +Examples: + +Destroy a given application. + +```bash +$ cdktf destroy +``` + +Destroy a given application with auto approval of the diff (Terraform plan). + +```bash +$ cdktf destroy --auto-approve +``` + +### cdktf login + +This command helps login to Terraform Cloud by fetching a Terraform Cloud API token. + +```bash +$ cdktf login --help +``` + +Help output: + +``` +cdktf login + +Retrieves an API token to connect to Terraform Cloud. + +Options: + --version Show version number [boolean] + --disable-logging Dont write log files. Supported using the env CDKTF_DISABLE_LOGGING. [boolean] [default: true] + --log-level Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL [string] + -h, --help Show help [boolean] +``` + +Examples: + +Fetch an API token from Terraform Cloud. + +```bash +$ cdktf login +``` \ No newline at end of file diff --git a/docs/getting-started/python.md b/docs/getting-started/python.md index 7fed724def..9f4f674b05 100644 --- a/docs/getting-started/python.md +++ b/docs/getting-started/python.md @@ -3,6 +3,7 @@ ## Prerequisites - [Terraform](https://www.terraform.io/downloads.html) >= v0.12 +- [Node.js](https://nodejs.org) >= v12.16 - [Python](https://www.python.org/downloads/) >= v3.7 - [Pipenv](https://pipenv.pypa.io/en/latest/install/#installing-pipenv/) @@ -19,10 +20,15 @@ Learn more how to use the cdktf command-line interface [here](../cli-commands.md ```bash mkdir hello-terraform cd hello-terraform -cdktf init --template="python" +cdktf init --template="python" --local ``` +This will initialize a brand new CDK for Terraform project in Python using an interactive command. -This will initialize a brand new CDK for Terraform project in Python and install the `cdktf` library so that it can be used in the project. +```bash + +``` + +Also, this command installs the `cdktf` library so that it can be used in the project. ## CDK for Terraform Application diff --git a/docs/getting-started/typescript.md b/docs/getting-started/typescript.md index 4ad661a1a2..58182c72f9 100644 --- a/docs/getting-started/typescript.md +++ b/docs/getting-started/typescript.md @@ -19,10 +19,23 @@ Learn more how to use the cdktf command-line interface [here](../cli-commands.md ```bash mkdir hello-terraform cd hello-terraform -cdktf init --template="typescript" +cdktf init --template="typescript" --local ``` -This will initialize a brand new CDK for Terraform project in TypeScript. Also, install the `cdktf` library so that it can be used in the project. +This will initialize a brand new CDK for Terraform project in TypeScript using an interactive command. + +```bash +Note: By supplying '--local' option you have chosen local storage mode for storing the state of your stack. +This means that your Terraform state file will be stored locally on disk. + +We will now setup the project. Please enter the details for your project. +If you want to exit, press ^C. + +Project Name: (default: 'hello-terraform') +Project Description: (default: 'A simple getting started project for cdktf.') +``` + +Also, this command installs the `cdktf` library so that it can be used in the project. **CDK for Terraform Application** @@ -128,12 +141,64 @@ cat cdktf.out/example.tf.json } ``` -**Apply Configuration** +**Deploy Application** + +> Note: You can use Terraform commands like `terraform init`, `terraform plan`, and `terraform apply` with the generated +Terraform JSON configuration (Learn more [here]()) or optionally continue to use the CDK for Terraform CLI for a first-class experience. + +You can now deploy your CDK for Terraform application using the `cdktf deploy` command. -You can now run Terraform commands to apply the given configuration. +```bash +cdktf deploy +``` + +This command will ask for confirmation on a generated diff and then deploy the application. ```bash -terraform init -terraform plan -terraform apply +Stack: helloterraform +Resources + + AWS_INSTANCE helloterraform_Hell aws_instance.helloterraform_Hello_19940A68 + +Diff: 1 to create, 0 to update, 0 to delete. +Do you want to continue (Y/n)? y ``` + +Deployed application + +```bash +Deploying Stack: helloterraform +Resources + ✔ AWS_INSTANCE helloterraform_Hell aws_instance.helloterraform_Hello_19940A68 + +Summary: 1 created, 0 updated, 0 destroyed. +``` + +**Destroy Application** + +You can destroy the application by running `cdktf destroy`. + +```bash +cdktf destroy +``` + +This command will ask for confirmation on a generated diff and then destroy the application if +the user confirms that they want to continue with the destroy operation. + +```bash +Stack: helloterraform +Resources + - AWS_INSTANCE helloterraform_Hell aws_instance.helloterraform_Hello_19940A68 + +Diff: 0 to create, 0 to update, 1 to delete. +Do you want to continue (Y/n)? +``` + +Destroyed application + +```bash +Destroying Stack: helloterraform +Resources + ✔ AWS_INSTANCE helloterraform_Hell aws_instance.helloterraform_Hello_19940A68 + +Summary: 1 destroyed. +``` \ No newline at end of file diff --git a/docs/working-with-cdk-for-terraform/data-sources.md b/docs/working-with-cdk-for-terraform/data-sources.md new file mode 100644 index 0000000000..d8680db961 --- /dev/null +++ b/docs/working-with-cdk-for-terraform/data-sources.md @@ -0,0 +1,19 @@ +# Terraform Data Sources + +[Terraform data sources](https://www.terraform.io/docs/configuration/data-sources.html) allow data to be fetched to be used in Terraform configuration. + +In TypeScript, a Terraform data source can fetches the AWS region can be expressed by `DataAwsRegion`. + +```typescript +..... +import { DataAwsRegion } from './gen/providers/aws' + +export class HelloTerraform extends TerraformStack { + constructor(scope: Construct, id: string) { + super(scope, id); + + ..... + const region = new DataAwsRegion(this, 'region') + } +} +``` diff --git a/package.json b/package.json index faff355432..1648566bcb 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "root", - "version": "0.0.6", + "version": "0.0.7", "private": true, "scripts": { "build": "lerna run build", diff --git a/packages/cdktf-cli/bin/cmds/helper/terraform-login.ts b/packages/cdktf-cli/bin/cmds/helper/terraform-login.ts index 45b955a01e..297abe7166 100644 --- a/packages/cdktf-cli/bin/cmds/helper/terraform-login.ts +++ b/packages/cdktf-cli/bin/cmds/helper/terraform-login.ts @@ -33,9 +33,7 @@ If login is successful, cdktf will store the token in plain text in the following file for use by subsequent Terraform commands: {whiteBright ${terraformCredentialsFilePath}} -{yellow Note: Other login options are availiable using 'cdktf login' command which include -using local storage for the state of your stack. The local storage mode isn't -recommended.} +{yellow Note: The local storage mode isn't recommended for storing the state of your stacks.} `); let isLogin = false diff --git a/packages/cdktf-cli/bin/cmds/init.ts b/packages/cdktf-cli/bin/cmds/init.ts index 8258ae3555..8e205a2df6 100644 --- a/packages/cdktf-cli/bin/cmds/init.ts +++ b/packages/cdktf-cli/bin/cmds/init.ts @@ -45,6 +45,9 @@ class Command implements yargs.CommandModule { // without a token and setup the project. const terraformLogin = new TerraformLogin token = await terraformLogin.askToLogin(); + } else { + console.log(chalkColour`{yellow Note: By supplying '--local' option you have chosen local storage mode for storing the state of your stack. +This means that your Terraform state file will be stored locally on disk.}`) } // Check if template was specified by the user @@ -118,7 +121,7 @@ If you want to exit, press {magenta ^C}. if (!projectName) { // Current working directory const currentDirectory = path.basename(process.cwd()); - projectName = readlineSync.question(chalkColour`{greenBright Project Name:} (default: '${currentDirectory}')`, { defaultInput: currentDirectory }) + projectName = readlineSync.question(chalkColour`{greenBright Project Name:} (default: '${currentDirectory}') `, { defaultInput: currentDirectory }) } if (!projectDescription) { diff --git a/packages/cdktf-cli/bin/cmds/synth.ts b/packages/cdktf-cli/bin/cmds/synth.ts index 52bc6c7561..ceef1a508d 100644 --- a/packages/cdktf-cli/bin/cmds/synth.ts +++ b/packages/cdktf-cli/bin/cmds/synth.ts @@ -13,7 +13,6 @@ class Command implements yargs.CommandModule { public readonly aliases = [ 'synthesize' ]; public readonly builder = (args: yargs.Argv) => args - .usage('Usage: $0 [options]') .option('app', { default: config.app, desc: 'Command to use in order to execute cdktf app', alias: 'a' }) .option('output', { default: config.output, desc: 'Output directory', alias: 'o' }) .option('json', { type: 'boolean', desc: 'Provide JSON output for the generated Terraform configuration.', default: false })