Revise documentation

wata727 · wata727 · commit 247840db396f · 2020-12-20T16:33:58.000+09:00
diff --git a/README.md b/README.md
@@ -1,19 +1,13 @@
-# WORKING IN PROGRESS AND MAINTAINER WANTED!
-
-This project was started to make TFLint pluggable. Everything is working in progress and not available as a plugin.
-
-AWS provider rules are currently integrated into the TFLint core. It will be cut out to this repository in the future, but it doesn't mean that limit the proposal of rules about AWS provider into the core repository.
-
-The migration process will take a long time. Please open an issue to the core repository for the latest proposal.
-
 # TFLint Ruleset for terraform-provider-aws
 
 TFLint ruleset plugin for Terraform AWS Provider
 
+This ruleset focus on possible errors and best practices about AWS resources. Many rules are enabled by default and warn against code that might fail when running `terraform apply`, or clearly unrecommened.
+
 ## Requirements
 
-- TFLint v0.14+
-- Go v1.13
+- TFLint v0.23+
+- Go v1.15
 
 ## Installation
 
@@ -25,11 +19,11 @@ plugin "aws" {
 }
 ```
 
+For more configuration about the plugin, see [Plugin Configuration](docs/configuration.md).
+
 ## Rules
 
-|Name|Description|Severity|Enabled|Link|
-| --- | --- | --- | --- | --- |
-|aws_instance_example_type|Show instance type|ERROR|✔||
+700+ rules are available. See [Rules](docs/rules/README.md).
 
 ## Building the plugin
 
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -0,0 +1,60 @@
+# Configuration
+
+This plugin can take advantage of additional features by configure the `plugin` block. Currently, this configuration is only available for [Deep Checking](deep_checking.md).
+
+Here's an example:
+
+```hcl
+plugin "aws" {
+    enabled = true
+
+    deep_check = false
+    access_key = "AWS_ACCESS_KEY_ID"
+    secret_key = "AWS_SECRET_ACCESS_KEY"
+    region     = "us-east-1"
+    profile    = "AWS_PROFILE"
+    shared_credentials_file = "~/.aws/credentials"
+}
+```
+
+## `enabled`
+
+Default: false
+
+Enable this plugin. This is the common option in all plugins.
+
+## `deep_check`
+
+Default: false
+
+Enable [Deep Checking](deep_checking.md).
+
+## `access_key`
+
+Default: Credentials declared in the `provider` block or `AWS_ACCESS_KEY_ID` environment variables when the deep checking is enabled.
+
+AWS access key used in the deep checking.
+
+## `secret_key`
+
+Default: Credentials declared in the `provider` block or `AWS_SECRET_ACCESS_KEY` environment variables when the deep checking is enabled.
+
+AWS secret key used in the deep checking.
+
+## `region`
+
+Default: Region declared in the `provider` block or `AWS_REGION` environment variables when the deep checking is enabled.
+
+AWS region used in the deep checking.
+
+## `profile`
+
+Default: Profile declared in the `provider` block or `AWS_PROFILE` environment variables when the deep checking is enabled.
+
+AWS shared credentials profile name used in the deep checking.
+
+## `shared_credentials_file`
+
+Default: Profile declared in the `provider` block or `~/.aws/credentials` when the deep checking is enabled.
+
+AWS shared credentials file path used in the deep checking.
diff --git a/docs/rules/README.md b/docs/rules/README.md
@@ -0,0 +1,55 @@
+# Rules
+
+This documentation describes a list of rules available by enabling this ruleset.
+
+### Possible Errors
+
+These rules warn of possible errors that can occur at `terraform apply`. Rules marked with `Deep` are only used when enabling [Deep Checking](../deep_checking.md):
+
+|Rule|Deep|
+| --- | --- |
+|aws_alb_invalid_security_group|✔|
+|aws_alb_invalid_subnet|✔|
+|aws_db_instance_invalid_db_subnet_group|✔|
+|aws_db_instance_invalid_option_group|✔|
+|aws_db_instance_invalid_parameter_group|✔|
+|aws_db_instance_invalid_type||
+|aws_db_instance_invalid_vpc_security_group|✔|
+|aws_elasticache_cluster_invalid_parameter_group|✔|
+|aws_elasticache_cluster_invalid_security_group|✔|
+|aws_elasticache_cluster_invalid_subnet_group|✔|
+|aws_elasticache_cluster_invalid_type||
+|aws_elb_invalid_instance|✔|
+|aws_elb_invalid_security_group|✔|
+|aws_elb_invalid_subnet|✔|
+|aws_instance_invalid_ami|✔|
+|aws_instance_invalid_iam_profile|✔|
+|aws_instance_invalid_key_name|✔|
+|aws_instance_invalid_subnet|✔|
+|aws_instance_invalid_vpc_security_group|✔|
+|aws_launch_configuration_invalid_iam_profile|✔|
+|aws_launch_configuration_invalid_image_id|✔|
+|aws_route_invalid_egress_only_gateway|✔|
+|aws_route_invalid_gateway|✔|
+|aws_route_invalid_instance|✔|
+|aws_route_invalid_nat_gateway|✔|
+|aws_route_invalid_network_interface|✔|
+|aws_route_invalid_route_table|✔|
+|aws_route_invalid_vpc_peering_connection|✔|
+|[aws_s3_bucket_name](aws_s3_bucket_name.md)||
+|[aws_route_not_specified_target](aws_route_not_specified_target.md)||
+|[aws_route_specified_multiple_targets](aws_route_specified_multiple_targets.md)||
+
+#### SDK-based Validations
+
+700+ rules based on the aws-sdk validations are also available. See [full list](../../rules/awsrules/models/).
+
+### Best Practices
+
+These rules suggest to better ways.
+
+- [aws_instance_previous_type](aws_instance_previous_type.md)
+- [aws_db_instance_previous_type](aws_db_instance_previous_type.md)
+- [aws_db_instance_default_parameter_group](aws_db_instance_default_parameter_group.md)
+- [aws_elasticache_cluster_previous_type](aws_elasticache_cluster_previous_type.md)
+- [aws_elasticache_cluster_default_parameter_group](aws_elasticache_cluster_default_parameter_group.md)
diff --git a/docs/rules/aws_db_instance_default_parameter_group.md b/docs/rules/aws_db_instance_default_parameter_group.md
@@ -0,0 +1,42 @@
+# aws_db_instance_default_parameter_group
+
+Disallow using default DB parameter group.
+
+## Example
+
+```hcl
+resource "aws_db_instance" "mysql" {
+  identifier             = "app"
+  allocated_storage      = 50
+  storage_type           = "gp2"
+  engine                 = "mysql"
+  engine_version         = "5.7.11"
+  instance_class         = "db.m4.large"
+  name                   = "app_db"
+  port                   = 3306
+  publicly_accessible    = false
+  vpc_security_group_ids = ["${aws_security_group.mysql.id}"]
+  db_subnet_group_name   = "app-subnet-group"
+  parameter_group_name   = "default.mysql5.7" // default DB parameter group!
+  multi_az               = true
+}
+```
+
+```
+$ tflint
+1 issue(s) found:
+
+Notice: "default.mysql5.7" is default parameter group. You cannot edit it. (aws_db_instance_default_parameter_group)
+
+  on template.tf line 13:
+  13:   parameter_group_name   = "default.mysql5.7" // default DB parameter group!
+ 
+```
+
+## Why
+
+You can modify parameter values in a custom DB parameter group, but you can't change the parameter values in a default DB parameter group.
+
+## How To Fix
+
+Create a new parameter group, and change the `parameter_group_name` to that.
diff --git a/docs/rules/aws_db_instance_previous_type.md b/docs/rules/aws_db_instance_previous_type.md
@@ -0,0 +1,38 @@
+# aws_db_instance_previous_type
+
+Disallow using previous generation instance types.
+
+## Example
+
+```hcl
+resource "aws_db_instance" "default" {
+  allocated_storage    = 10
+  engine               = "mysql"
+  engine_version       = "5.6.17"
+  instance_class       = "db.t1.micro" // previous generation instance type!
+  name                 = "mydb"
+  username             = "foo"
+  password             = "bar"
+  db_subnet_group_name = "my_database_subnet_group"
+  parameter_group_name = "default.mysql5.6"
+}
+```
+
+```
+$ tflint
+1 issue(s) found:
+
+Warning: "db.t1.micro" is previous generation instance type. (aws_db_instance_previous_type)
+
+  on template.tf line 5:
+   5:   instance_class       = "db.t1.micro" // previous generation instance type!
+ 
+```
+
+## Why
+
+Current generation instance types have better performance and lower cost than previous generations. Users should avoid previous generation instance types, especially for new instances.
+
+## How To Fix
+
+Select a current generation instance type according to the [upgrade paths](https://aws.amazon.com/rds/previous-generation/).
diff --git a/docs/rules/aws_elasticache_cluster_default_parameter_group.md b/docs/rules/aws_elasticache_cluster_default_parameter_group.md
@@ -0,0 +1,39 @@
+# aws_elasticache_cluster_default_parameter_group
+
+Disallow using default parameter group.
+
+## Example
+
+```hcl
+resource "aws_elasticache_cluster" "redis" {
+  cluster_id           = "app"
+  engine               = "redis"
+  engine_version       = "3.2.4"
+  maintenance_window   = "sun:00:00-sun:06:00"
+  node_type            = "cache.m4.large"
+  num_cache_nodes      = 1
+  port                 = 6379
+  parameter_group_name = "default.redis3.2" // default paramete group!
+  subnet_group_name    = "app-subnet-group"
+  security_group_ids   = ["${aws_security_group.redis.id}"]
+}
+```
+
+```
+$ tflint
+1 issue(s) found:
+
+Notice: "default.redis3.2" is default parameter group. You cannot edit it. (aws_elasticache_cluster_default_parameter_group)
+
+  on template.tf line 9:
+   9:   parameter_group_name = "default.redis3.2" // default paramete group!
+ 
+```
+
+## Why
+
+You can modify parameter values in a custom parameter group, but you can't change the parameter values in a default parameter group.
+
+## How To Fix
+
+Create a new parameter group, and change the `parameter_group_name` to that.
diff --git a/docs/rules/aws_elasticache_cluster_previous_type.md b/docs/rules/aws_elasticache_cluster_previous_type.md
@@ -0,0 +1,39 @@
+# aws_elasticache_cluster_previous_type
+
+Disallow using previous node types.
+
+## Example
+
+```hcl
+resource "aws_elasticache_cluster" "redis" {
+  cluster_id           = "app"
+  engine               = "redis"
+  engine_version       = "3.2.4"
+  maintenance_window   = "sun:00:00-sun:06:00"
+  node_type            = "cache.t1.micro" // previous node type!
+  num_cache_nodes      = 1
+  port                 = 6379
+  parameter_group_name = "default.redis3.2"
+  subnet_group_name    = "app-subnet-group"
+  security_group_ids   = ["${aws_security_group.redis.id}"]
+}
+```
+
+```
+$ tflint
+1 issue(s) found:
+
+Warning: "cache.t1.micro" is previous generation node type. (aws_elasticache_cluster_previous_type)
+
+  on template.tf line 6:
+   6:   node_type            = "cache.t1.micro" // previous node type!
+ 
+```
+
+## Why
+
+Previous node types are inferior to current generation in terms of performance and fee. Unless there is a special reason, you should avoid to use these ones.
+
+## How To Fix
+
+Select a current generation node type according to the [upgrade paths](https://aws.amazon.com/elasticache/previous-generation/).
diff --git a/docs/rules/aws_instance_previous_type.md b/docs/rules/aws_instance_previous_type.md
@@ -0,0 +1,36 @@
+# aws_instance_previous_type
+
+Disallow using previous generation instance types.
+
+## Example
+
+```hcl
+resource "aws_instance" "web" {
+  ami                  = "ami-b73b63a0"
+  instance_type        = "t1.micro" # previous instance type!
+  iam_instance_profile = "app-service"
+
+  tags {
+    Name = "HelloWorld"
+  }
+}
+```
+
+```
+$ tflint
+1 issue(s) found:
+
+Warning: "t1.micro" is previous generation instance type. (aws_instance_previous_type)
+
+  on template.tf line 3:
+   3:   instance_type        = "t1.micro" # previous instance type!
+ 
+```
+
+## Why
+
+Current generation instance types have better performance and lower cost than previous generations. Users should avoid previous generation instance types, especially for new instances.
+
+## How To Fix
+
+Select a current generation instance type according to the [upgrade paths](https://aws.amazon.com/ec2/previous-generation/).
diff --git a/docs/rules/aws_route_not_specified_target.md b/docs/rules/aws_route_not_specified_target.md
@@ -0,0 +1,31 @@
+# aws_route_not_specified_target
+
+Disallow routes that have no targets.
+
+## Example
+
+```hcl
+resource "aws_route" "foo" {
+  route_table_id         = "rtb-1234abcd"
+  destination_cidr_block = "10.0.1.0/22"
+}
+```
+
+```
+$ tflint
+1 issue(s) found:
+
+Error: The routing target is not specified, each aws_route must contain either egress_only_gateway_id, gateway_id, instance_id, nat_gateway_id, network_interface_id, transit_gateway_id, vpc_peering_connection_id or vpc_endpoint_id. (aws_route_not_specified_target)
+
+  on template.tf line 1:
+   1: resource "aws_route" "foo" {
+ 
+```
+
+## Why
+
+It results in an error.
+
+## How To Fix
+
+Add a routing target. The [supported arguments](https://www.terraform.io/docs/providers/aws/r/route.html#argument-reference) are: `egress_only_gateway_id`, `gateway_id`, `instance_id`, `nat_gateway_id`, `network_interface_id`, `transit_gateway_id`, `vpc_peering_connection_id`.
diff --git a/docs/rules/aws_route_specified_multiple_targets.md b/docs/rules/aws_route_specified_multiple_targets.md
diff --git a/docs/rules/aws_s3_bucket_name.md b/docs/rules/aws_s3_bucket_name.md
