v0.8: Update documentations

CHANGELOG.md

@@ -1,3 +1,58 @@
+## 0.8.0 (2019-??-??)
+
+This release includes major changes due to being dependent on Terraform v0.12 internal API. While we try to keep backward compatibility as much as possible, it does include some breaking changes.
+
+We strongly recommend [upgrading to Terraform v0.12](https://www.terraform.io/upgrade-guides/0-12.html) before trying TFLint v0.8. `terraform 0.12upgrade` is helpful to upgrade your configuration files.
+
+### Breaking Changes
+
+- Always return an error when failed to evaluate an expression.
+  - Until now, except for module arguments, even if an error occurred, it was ignored.
+  - Expressions including unsupported named values (such as `${module.foo}`) are not evaluated, so no error occurs.
+- Drop support for `${terraform.env}`.
+  - Previously `${terraform.env}` was a valid expression that returned the same as `${terraform.workspace}`.
+  - This is because Terraform v0.12 doesn't support `${terraform.env}`.
+- The file name of a module includes module ID instead of the source attribute.
+  - Up to now it was output like `github.com/wata727/example-module/instance.tf`, but it will be changed like `module_id/instance.tf`.
+- Always parse all configuration files under the current directory.
+  - When passing a file name as an argument, TFLint only parsed that file so far, but it now parses all configuration files under the current directory.
+  - Also, file arguments are only used to filter the issues obtained. Therefore, you cannot pass files other than under the current directory.
+  - As a known issue, If file arguments are passed, module's issues are not reported. This will be improved by changing handling of module's issues in the future.
+  - These behaviors have been changed as it depends on Terraform's `configload` package.
+  - In addition, modules are always loaded regardless of `ignore_module`.
+- Raise an error when using invalid syntax as a Terraform configuration.
+  - For example, it didn't raise an error when using `resources`(not `resource`) block because it is valid as HCL syntax in previous versions.
+- Remove `--debug` option.
+  - Please use `TFLINT_LOG` environment variables instead.
+- Raise an error when a file passed by `--config` does not exist.
+  - Previously the error was ignored and the default config was referenced.
+- Remove duplicate resource rules.
+  - This is due to technical difficulty and user experience.
+
+### Enhancements
+
+- HCL2 support
+  - See also https://www.hashicorp.com/blog/terraform-0-1-2-preview
+- Built-in Functions support
+  - Until now, if an expression includes function calls, it was ignored.
+- `TF_DATA_DIR` and `TF_WORKSPACE` environment variables are now available.
+  - Until now, these variables are ignored.
+- It is now possible to handle values doesn't have a default without raising errors.
+  - In the past, an error occurred when there was a reference to a variable that had no default value in an attribute of a module. See [#205](https://github.com/wata727/tflint/issues/205)
+- Terraform v0.11 module support
+  - Until now, it is failed to properly load a part of Terraform v0.11 module. See also [#167](https://github.com/wata727/tflint/issues/167)
+- Support for automatic loading `*.auto.tfvars` files.
+  - Previously it was not loaded automatically.
+
+### BugFixes
+
+- Improve expression checks
+  - Since it used to be checked by a regular expression, there were many bugs, but it was greatly improved by using the `terraform/lang` package. See [#204](https://github.com/wata727/tflint/issues/204) [#160](https://github.com/wata727/tflint/issues/160)
+- Stop overwriting the config under the current directory by the config under the homedir.
+  - Fixed the problem that overwrites the config under the current directory by homedir config.
+- Improve to check for `aws_db_instance_readable_password`.
+  - Previously, false positive occurred when setting values files or environment variables, but this problem has been fixed.
+
 ## 0.7.5 (2019-04-03)
 
 ### Enhancements

README.md

@@ -5,16 +5,11 @@
 [![MIT License](http://img.shields.io/badge/license-MIT-blue.svg?style=flat)](LICENSE)
 [![Go Report Card](https://goreportcard.com/badge/github.com/wata727/tflint)](https://goreportcard.com/report/github.com/wata727/tflint)
 
-TFLint is a [Terraform](https://www.terraform.io/) linter for detecting errors that can not be detected by `terraform plan`
+TFLint is a [Terraform](https://www.terraform.io/) linter focused on possible errors, best practices, and so on.
 
-## Current Project Status
+## Why TFLint is required?
 
-Currently, we don't encourage you to run TFLint on critical workflow due to incomplete features. See [#167](https://github.com/wata727/tflint/issues/167), [#168](https://github.com/wata727/tflint/issues/168).  
-This issue is scheduled to be fixed in the release of v0.8.0, but this release depends on Terraform v0.12.0, and we cannot release v0.8.0 until it is released.  
-For these reasons, feature requests and major changes have been suspended until v0.8.0 release. A small bug fixes for patch upgrade are welcome.
-
-## Why TFLint is Required?
-Terraform is a great tool for infrastructure as a code. It generates an execution plan, we can rely on this plan to proceed with development. However, this plan does not verify values used in template. For example, following template is invalid configuration (t1.2xlarge is invalid instance type)
+Terraform is a great tool for Infrastructure as Code. However, many of these tools don't validate provider-specific issues. For example, see the following configuration file:
 
 ```hcl
 resource "aws_instance" "web" {
@@ -27,10 +22,22 @@ resource "aws_instance" "web" {
 }
 ```
 
-If you run `terraform apply` for this template, it will obviously produce an error. However, `terraform plan` can get an execution plan without causing an error. This is often not a desirable result. In order to solve this problem, TFLint validates values used in template.
+Since `t1.2xlarge` is a nonexistent instance type, an error will occur when you run `terraform apply`. But `terraform plan` and `terraform validate` cannot find this possible error beforehand. That's because it's an AWS provider-specific issue and it's valid as a Terraform configuration.
+
+TFLint finds such errors in advance:
+
+```
+$ tflint
+template.tf
+        ERROR:3 "t1.2xlarge" is invalid instance type. (aws_instance_invalid_type)
+
+Result: 2 issues  (1 errors , 0 warnings , 1 notices)
+```
 
 ## Installation
-Download binary built for your architecture from [latest releases](https://github.com/wata727/tflint/releases/latest). After downloading, place the binary on the directory on the PATH. The following example is the installation in macOS.
+
+You can download the binary built for your architecture from [the latest release](https://github.com/wata727/tflint/releases/latest). The following is an example of installation on macOS:
+
 ```
 $ wget https://github.com/wata727/tflint/releases/download/v0.7.5/tflint_darwin_amd64.zip
 $ unzip tflint_darwin_amd64.zip
@@ -42,7 +49,7 @@ $ install tflint /usr/local/tflint/bin
 $ tflint -v
 ```
 
-For Linux based OS, you can use the install_linux.sh to automate the installation process
+For Linux based OS, you can use the [`install_linux.sh`](https://raw.githubusercontent.com/wata727/tflint/master/install_linux.sh) to automate the installation process.
 
 ### Homebrew
 
@@ -53,39 +60,34 @@ $ brew tap wata727/tflint
 $ brew install tflint
 ```
 
-### Running in Docker
-We provide Docker images for each version on [DockerHub](https://hub.docker.com/r/wata727/tflint/). With docker, you can run TFLint without installing it locally.
+### Docker
+
+You can also use [TFLint via Docker](https://hub.docker.com/r/wata727/tflint/).
 
 ```
 $ docker run --rm -v $(pwd):/data -t wata727/tflint
 ```
 
-## Quick Start
-Try running TFLint under the directory where Terraform is executed. It detect if there is a issue and output the result. For example, run on the previous invalid template.
+## Features
 
-```
-$ tflint
-template.tf
-        ERROR:3 "t1.2xlarge" is invalid instance type. (aws_instance_invalid_type)
+See [Rules](docs/rules).
 
-Result: 2 issues  (1 errors , 0 warnings , 1 notices)
-```
+## Limitations
 
-If you would like to know more about these issues and available features please check the [documentation](https://github.com/wata727/tflint/tree/master/docs).
+TFLint currently only inspect Terraform-specific issues and AWS issues.
 
-### Specify Template
-If you want to parse only a specific template, not all templates, you can specify a filename as an argument.
+Also, load configurations in the same way as Terraform v0.12. This means that it cannot inspect configurations that cannot be parsed on Terraform v0.12.
 
-```
-$ tflint template.tf
-```
+[Named values](https://www.terraform.io/docs/configuration/expressions.html#references-to-named-values) are supported only for [input variables](https://www.terraform.io/docs/configuration/variables.html) and [workspaces](https://www.terraform.io/docs/state/workspaces.html). Expressions that contain anything else are excluded from the  inspection. [Built-in Functions](https://www.terraform.io/docs/configuration/functions.html) are fully supported.
 
-## Available Options
-Please show `tflint --help`
+## Usage
+
+TFLint inspects all configurations under the current directory by default. You can also change the behavior with the following options:
 
 ```
+$ tflint --help
 Usage:
-  tflint [OPTIONS] [FILE]
+  tflint [OPTIONS]
 
 Application Options:
   -v, --version                             Print TFLint version
@@ -99,26 +101,26 @@ Application Options:
       --aws-secret-key=SECRET_KEY           AWS secret key used in deep check mode
       --aws-profile=PROFILE                 AWS shared credential profile name used in deep check mode
       --aws-region=REGION                   AWS region used in deep check mode
-  -d, --debug                               Enable debug mode
       --error-with-issues                   Return error code when issues exist
-      --fast                                Ignore slow rules. Currently, ignore only aws_instance_invalid_ami
-  -q, --quiet                               Do not output any message when no issues are found (Format=default only)
+      --fast                                Ignore slow rules (aws_instance_invalid_ami only)
+  -q, --quiet                               Do not output any message when no issues are found (default format only)
 
 Help Options:
   -h, --help                                Show this help message
 ```
 
-## Configuration
-By default, TFLint loads `.tflint.hcl` according to the following priority:
+### Config file
+
+By default, TFLint looks up `.tflint.hcl` according to the following priority:
 
 - Current directory (`./.tflint.hcl`)
 - Home directory (`~/.tflint.hcl`)
 
-The configuration file is described in [HCL](https://github.com/hashicorp/hcl), and options available on the command line can be described in advance. Following example:
+The config file is written in [HCL](https://github.com/hashicorp/hcl), and you can use this file instead of passing command line options.
 
 ```hcl
 config {
-  terraform_version = "0.9.11"
+  terraform_version = "0.12.0"
   deep_check = true
 
   aws_credentials = {
@@ -143,16 +145,47 @@ rule "aws_instance_previous_type" {
 }
 ```
 
-If you want to create a configuration file with a different name, specify the file name with `--config` option.
+You can also use another file as a config file with the `--config` option.
 
 ```
 $ tflint --config other_config.hcl
 ```
 
-### Terraform Version
-You can set the version of Terraform you are using. If it is set, TFLint will detect issues according to it.
+### Rules
+
+You can make settings for each rule in the `rule` block. Currently, it can set only `enabled` option. If you set `enabled = false`, TFLint doesn't inspect configuration files by this rule.
+
+```hcl
+rule "aws_instance_previous_type" {
+  enabled = false
+}
+```
+
+You can also disable rules with the `--ignore-rule` option.
+
+```
+$ tflint --ignore-rule=aws_instance_invalid_type,aws_instance_previous_type
+```
+
+See also [list of available rules](docs/rules).
+
+### Deep Checking
+
+When deep checking is enabled, TFLint invokes the provider's API to do a more detailed inspection. For example, find a non-existent IAM profile name etc. You can enable it with the `--deep` option.
+
+```
+$ tflint --deep
+template.tf
+        ERROR:3 "t1.2xlarge" is invalid instance type. (aws_instance_invalid_type)
+        ERROR:4 "invalid_profile" is invalid IAM profile name. (aws_instance_invalid_iam_profile)
+
+Result: 2 issues  (2 errors , 0 warnings , 0 notices)
+```
+
+In order to enable deep checking, [credentials](#credentials) are needed.
 
 ### Credentials
+
 TFLint supports various credential providers. It is used with the following priority:
 
 - Static credentials
@@ -161,7 +194,8 @@ TFLint supports various credential providers. It is used with the following prio
 - Default shared credentials
 
 #### Static Credentials
-If you have access key and secret key, you can specify these credentials.
+
+If you have an access key and a secret key, you can pass these keys.
 
 ```
 $ tflint --aws-access-key AWS_ACCESS_KEY --aws-secret-key AWS_SECRET_KEY --aws-region us-east-1
@@ -178,7 +212,8 @@ config {
 ```
 
 #### Shared Credentials
-If you have [shared credentials](https://aws.amazon.com/jp/blogs/security/a-new-and-standardized-way-to-manage-credentials-in-the-aws-sdks/), you can specify credentials profile name. However TFLint supports only `~/.aws/credentials` as shared credentials location.
+
+If you have [shared credentials](https://aws.amazon.com/jp/blogs/security/a-new-and-standardized-way-to-manage-credentials-in-the-aws-sdks/), you can pass the profile name. However, only `~/.aws/credentials` is supported as a credential location.
 
 ```
 $ tflint --aws-profile AWS_PROFILE --aws-region us-east-1
@@ -194,52 +229,69 @@ config {
 ```
 
 #### Environment Credentials
-TFLint looks `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` environment values. This is useful when you do not want to explicitly specify credentials.
+
+TFLint looks up `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` environment variables. This is useful when you don't want to explicitly pass credentials.
 
 ```
 $ export AWS_ACCESS_KEY_ID=AWS_ACCESS_KEY
 $ export AWS_SECRET_ACCESS_KEY=AWS_SECRET_KEY
 ```
 
-### Rules
+### Module Inspection
 
-You can make settings for each rule in the `rule` block. Currently, it can set only `enabled` option. If you set `enabled = false`, TFLint doesn't check templates by this rule.
+TFLint can also inspect [modules](https://www.terraform.io/docs/configuration/modules.html). In this case, it checks based on the input variables passed to the calling module.
 
-```
-rule "aws_instance_previous_type" {
-  enabled = false
+```hcl
+module "aws_instance" {
+  source        = "./module"
+
+  ami           = "ami-b73b63a0"
+  instance_type = "t1.2xlarge"
 }
 ```
 
-Please see the [documentation](https://github.com/wata727/tflint/tree/master/docs) for a list of rules.
+```
+$ tflint
+aws_instance/main.tf
+        ERROR:6 "t1.2xlarge" is invalid instance type. (aws_instance_invalid_type)
 
-## Interpolation Syntax Support
-TFLint can interpret part of [interpolation syntax](https://www.terraform.io/docs/configuration/interpolation.html). We now support only variables and terraform meta information (e.g. "${terraform.env}"). So you cannot use attributes of resource, outputs of modules and built-in functions. If you are using them, TFLint ignores it. You can check what is ignored by executing it with `--debug` option.
+Result: 1 issues  (1 errors , 0 warnings , 0 notices)
+```
 
-### Variable Files
-If you use [variable files](https://www.terraform.io/docs/configuration/variables.html#variable-files), Please specify it by arguments or configuration file. TFLint interprets variables as well as Terraform. In other words, when variables are conflicting, It will be overridden or merged correctly.
+TFLint loads modules in the same way as Terraform. So note that you need to run `terraform init` first.
 
-## Deep Check
-Deep check is an option that you can actually search resources on AWS and check invalid references and duplicate resources. You can activate it by executing it with `--deep` option as following:
+You can use the `--ignore-module` option if you want to skip inspection for a particular module. Note that you need to pass module sources rather than module ids for backward compatibility.
 
 ```
-$ tflint --deep
-template.tf
-        ERROR:3 "t1.2xlarge" is invalid instance type. (aws_instance_invalid_type)
-        ERROR:4 "invalid_profile" is invalid IAM profile name. (aws_instance_invalid_iam_profile)
+$ tflint --ignore-module=./module
+```
+
+### Run with a specific configuration file
+
+If you want to inspect only a specific configuration file, not all files, you can pass a file as an argument.
 
-Result: 2 issues  (2 errors , 0 warnings , 0 notices)
+```
+$ tflint main.tf
 ```
 
-In the above example, an IAM instance profile that does not actually exist is specified, so it is an error. In order to refer to actual resources, AWS credentials are required. You can use command line options, configuration files, environment variables, shared credentials for these specifications.
+### Terraform Version
 
-## Developing
-If you want to build TFLint at your environment, you can build with the following procedure. [Go](https://golang.org/) 1.9 or more is required.
+You can set the version of Terraform you are using. If it is set, TFLint will detect issues according to it.
+
+NOTE: This option is now no longer used and will be removed in the future.
+
+## Debugging
+
+If you don't get the expected behavior, you can see the detailed logs when running with `TFLINT_LOG` environment variable.
 
 ```
-$ make build
+$ TFLINT_LOG=debug tflint
 ```
 
+## Developing
+
+See [Developer Guides](docs/DEVELOPING.md).
+
 ## Author
 
 [Kazuma Watanabe](https://github.com/wata727)