github.com/tetrafolium/tflint@v0.8.0/README.md (about) 1 # TFLint 2 [![Build Status](https://travis-ci.org/wata727/tflint.svg?branch=master)](https://travis-ci.org/wata727/tflint) 3 [![GitHub release](https://img.shields.io/github/release/wata727/tflint.svg)](https://github.com/wata727/tflint/releases/latest) 4 [![Docker Hub](https://img.shields.io/badge/docker-ready-blue.svg)](https://hub.docker.com/r/wata727/tflint/) 5 [![License: MPL 2.0](https://img.shields.io/badge/License-MPL%202.0-blue.svg)](LICENSE) 6 [![Go Report Card](https://goreportcard.com/badge/github.com/wata727/tflint)](https://goreportcard.com/report/github.com/wata727/tflint) 7 8 TFLint is a [Terraform](https://www.terraform.io/) linter focused on possible errors, best practices, and so on. 9 10 ## Why TFLint is required? 11 12 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: 13 14 ```hcl 15 resource "aws_instance" "web" { 16 ami = "ami-b73b63a0" 17 instance_type = "t1.2xlarge" # invalid type! 18 19 tags { 20 Name = "HelloWorld" 21 } 22 } 23 ``` 24 25 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. 26 27 TFLint finds such errors in advance: 28 29 ``` 30 $ tflint 31 template.tf 32 ERROR:3 "t1.2xlarge" is invalid instance type. (aws_instance_invalid_type) 33 34 Result: 2 issues (1 errors , 0 warnings , 1 notices) 35 ``` 36 37 ## Installation 38 39 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: 40 41 ``` 42 $ wget https://github.com/wata727/tflint/releases/download/v0.8.0/tflint_darwin_amd64.zip 43 $ unzip tflint_darwin_amd64.zip 44 Archive: tflint_darwin_amd64.zip 45 inflating: tflint 46 $ mkdir -p /usr/local/tflint/bin 47 $ export PATH=/usr/local/tflint/bin:$PATH 48 $ install tflint /usr/local/tflint/bin 49 $ tflint -v 50 ``` 51 52 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. 53 54 ### Homebrew 55 56 macOS users can also use [Homebrew](https://brew.sh) to install TFLint: 57 58 ``` 59 $ brew tap wata727/tflint 60 $ brew install tflint 61 ``` 62 63 ### Docker 64 65 You can also use [TFLint via Docker](https://hub.docker.com/r/wata727/tflint/). 66 67 ``` 68 $ docker run --rm -v $(pwd):/data -t wata727/tflint 69 ``` 70 71 ## Features 72 73 See [Rules](docs/rules). 74 75 ## Limitations 76 77 TFLint currently only inspect Terraform-specific issues and AWS issues. 78 79 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. 80 81 [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. 82 83 ## Usage 84 85 TFLint inspects all configurations under the current directory by default. You can also change the behavior with the following options: 86 87 ``` 88 $ tflint --help 89 Usage: 90 tflint [OPTIONS] 91 92 Application Options: 93 -v, --version Print TFLint version 94 -f, --format=[default|json|checkstyle] Output format (default: default) 95 -c, --config=FILE Config file name (default: .tflint.hcl) 96 --ignore-module=SOURCE1,SOURCE2... Ignore module sources 97 --ignore-rule=RULE1,RULE2... Ignore rule names 98 --var-file=FILE1,FILE2... Terraform variable file names 99 --deep Enable deep check mode 100 --aws-access-key=ACCESS_KEY AWS access key used in deep check mode 101 --aws-secret-key=SECRET_KEY AWS secret key used in deep check mode 102 --aws-profile=PROFILE AWS shared credential profile name used in deep check mode 103 --aws-region=REGION AWS region used in deep check mode 104 --error-with-issues Return error code when issues exist 105 --fast Ignore slow rules (aws_instance_invalid_ami only) 106 -q, --quiet Do not output any message when no issues are found (default format only) 107 108 Help Options: 109 -h, --help Show this help message 110 ``` 111 112 ### Config file 113 114 By default, TFLint looks up `.tflint.hcl` according to the following priority: 115 116 - Current directory (`./.tflint.hcl`) 117 - Home directory (`~/.tflint.hcl`) 118 119 The config file is written in [HCL](https://github.com/hashicorp/hcl), and you can use this file instead of passing command line options. 120 121 ```hcl 122 config { 123 terraform_version = "0.12.0" 124 deep_check = true 125 126 aws_credentials = { 127 access_key = "AWS_ACCESS_KEY" 128 secret_key = "AWS_SECRET_KEY" 129 region = "us-east-1" 130 } 131 132 ignore_module = { 133 "github.com/wata727/example-module" = true 134 } 135 136 varfile = ["example1.tfvars", "example2.tfvars"] 137 } 138 139 rule "aws_instance_invalid_type" { 140 enabled = false 141 } 142 143 rule "aws_instance_previous_type" { 144 enabled = false 145 } 146 ``` 147 148 You can also use another file as a config file with the `--config` option. 149 150 ``` 151 $ tflint --config other_config.hcl 152 ``` 153 154 ### Rules 155 156 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. 157 158 ```hcl 159 rule "aws_instance_previous_type" { 160 enabled = false 161 } 162 ``` 163 164 You can also disable rules with the `--ignore-rule` option. 165 166 ``` 167 $ tflint --ignore-rule=aws_instance_invalid_type,aws_instance_previous_type 168 ``` 169 170 See also [list of available rules](docs/rules). 171 172 ### Deep Checking 173 174 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. 175 176 ``` 177 $ tflint --deep 178 template.tf 179 ERROR:3 "t1.2xlarge" is invalid instance type. (aws_instance_invalid_type) 180 ERROR:4 "invalid_profile" is invalid IAM profile name. (aws_instance_invalid_iam_profile) 181 182 Result: 2 issues (2 errors , 0 warnings , 0 notices) 183 ``` 184 185 In order to enable deep checking, [credentials](#credentials) are needed. 186 187 ### Credentials 188 189 TFLint supports various credential providers. It is used with the following priority: 190 191 - Static credentials 192 - Shared credentials 193 - Environment credentials 194 - Default shared credentials 195 196 #### Static Credentials 197 198 If you have an access key and a secret key, you can pass these keys. 199 200 ``` 201 $ tflint --aws-access-key AWS_ACCESS_KEY --aws-secret-key AWS_SECRET_KEY --aws-region us-east-1 202 ``` 203 204 ```hcl 205 config { 206 aws_credentials = { 207 access_key = "AWS_ACCESS_KEY" 208 secret_key = "AWS_SECRET_KEY" 209 region = "us-east-1" 210 } 211 } 212 ``` 213 214 #### Shared Credentials 215 216 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. 217 218 ``` 219 $ tflint --aws-profile AWS_PROFILE --aws-region us-east-1 220 ``` 221 222 ```hcl 223 config { 224 aws_credentials = { 225 profile = "AWS_PROFILE" 226 region = "us-east-1" 227 } 228 } 229 ``` 230 231 #### Environment Credentials 232 233 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. 234 235 ``` 236 $ export AWS_ACCESS_KEY_ID=AWS_ACCESS_KEY 237 $ export AWS_SECRET_ACCESS_KEY=AWS_SECRET_KEY 238 ``` 239 240 ### Module Inspection 241 242 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. 243 244 ```hcl 245 module "aws_instance" { 246 source = "./module" 247 248 ami = "ami-b73b63a0" 249 instance_type = "t1.2xlarge" 250 } 251 ``` 252 253 ``` 254 $ tflint 255 aws_instance/main.tf 256 ERROR:6 "t1.2xlarge" is invalid instance type. (aws_instance_invalid_type) 257 258 Result: 1 issues (1 errors , 0 warnings , 0 notices) 259 ``` 260 261 TFLint loads modules in the same way as Terraform. So note that you need to run `terraform init` first. 262 263 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. 264 265 ``` 266 $ tflint --ignore-module=./module 267 ``` 268 269 ### Run with a specific configuration file 270 271 If you want to inspect only a specific configuration file, not all files, you can pass a file as an argument. 272 273 ``` 274 $ tflint main.tf 275 ``` 276 277 ### Terraform Version 278 279 You can set the version of Terraform you are using. If it is set, TFLint will detect issues according to it. 280 281 NOTE: This option is now no longer used and will be removed in the future. 282 283 ## Debugging 284 285 If you don't get the expected behavior, you can see the detailed logs when running with `TFLINT_LOG` environment variable. 286 287 ``` 288 $ TFLINT_LOG=debug tflint 289 ``` 290 291 ## Developing 292 293 See [Developer Guides](docs/DEVELOPING.md). 294 295 ## Author 296 297 [Kazuma Watanabe](https://github.com/wata727)