Merge pull request #4 from terraform-linters/add_configuration_doc

Add documentation for deep checking

Author: wata727

aws/client.go

@@ -1,9 +1,7 @@
 package aws
 
 import (
-	"errors"
 	"log"
-	"strings"
 
 	"github.com/aws/aws-sdk-go/service/ec2"
 	"github.com/aws/aws-sdk-go/service/ec2/ec2iface"
@@ -67,7 +65,7 @@ func NewClient(creds Credentials) (*Client, error) {
 
 	s, err := awsbase.GetSession(config)
 	if err != nil {
-		return nil, formatBaseConfigError(err)
+		return nil, err
 	}
 
 	return &Client{
@@ -88,26 +86,20 @@ func getBaseConfig(creds Credentials) (*awsbase.Config, error) {
 	}
 
 	return &awsbase.Config{
-		AccessKey:             creds.AccessKey,
-		AssumeRoleARN:         creds.AssumeRoleARN,
-		AssumeRoleExternalID:  creds.AssumeRoleExternalID,
-		AssumeRolePolicy:      creds.AssumeRolePolicy,
-		AssumeRoleSessionName: creds.AssumeRoleSessionName,
-		SecretKey:             creds.SecretKey,
-		Profile:               creds.Profile,
-		CredsFilename:         expandedCredsFile,
-		Region:                creds.Region,
+		AccessKey:              creds.AccessKey,
+		AssumeRoleARN:          creds.AssumeRoleARN,
+		AssumeRoleExternalID:   creds.AssumeRoleExternalID,
+		AssumeRolePolicy:       creds.AssumeRolePolicy,
+		AssumeRoleSessionName:  creds.AssumeRoleSessionName,
+		SecretKey:              creds.SecretKey,
+		Profile:                creds.Profile,
+		CredsFilename:          expandedCredsFile,
+		Region:                 creds.Region,
+		CallerName:             "tflint-ruleset-aws",
+		CallerDocumentationURL: "https://github.com/terraform-linters/tflint-ruleset-aws/blob/master/docs/deep_checking.md",
 	}, nil
 }
 
-// @see https://github.com/hashicorp/aws-sdk-go-base/blob/v0.3.0/session.go#L87
-func formatBaseConfigError(err error) error {
-	if strings.Contains(err.Error(), "No valid credential sources found for AWS Provider") {
-		return errors.New("No valid credential sources found")
-	}
-	return err
-}
-
 // Merge returns a merged credentials
 func (c Credentials) Merge(other Credentials) Credentials {
 	if other.AccessKey != "" {

docs/deep_checking.md

@@ -0,0 +1,111 @@
+# Deep Checking
+
+Deep Checking uses your provider's credentials to perform a more strict inspection.
+
+For example, if the IAM profile references something that doesn't exist, terraform apply will fail, which can't be found by general validation. Deep Checking solves this problem.
+
+```console
+$ tflint
+2 issue(s) found:
+
+Error: instance_type is not a valid value (aws_instance_invalid_type)
+
+  on template.tf line 3:
+   3:   instance_type        = "t1.2xlarge"
+
+Error: "invalid_profile" is invalid IAM profile name. (aws_instance_invalid_iam_profile)
+
+  on template.tf line 4:
+   4:   iam_instance_profile = "invalid_profile"
+
+```
+
+You can enable Deep Checking by changing the plugin configuration.
+
+```hcl
+plugin "aws" {
+  enabled = true
+
+  deep_check = true
+}
+```
+
+## Credentials
+
+Credentials can be set in several ways. Each is referenced in the following order:
+
+- Static credentials
+- Static credentials (Terraform)
+- Environment variables
+- Shared credentials
+- Shared credentials (Terraform)
+- ECS and CodeBuild task roles
+- EC2 role
+
+
+### Static credentials
+
+If you have an access key and a secret key, you can pass these keys like the following:
+
+```hcl
+plugin "aws" {
+  enabled = true
+
+  deep_check = true
+  access_key = "AWS_ACCESS_KEY_ID"
+  secret_key = "AWS_SECRET_ACCESS_KEY"
+  region     = "us-east-1"
+}
+```
+
+Although there is not recommended, if an access key is hard-coded in a provider configuration, they will also be taken into account. However, aliases are not supported. The priority is higher than the environment variable and lower than the above way.
+
+```hcl
+provider "aws" {
+  region     = "us-west-2"
+  access_key = "my-access-key"
+  secret_key = "my-secret-key"
+}
+```
+
+### 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 pass a profile name and credentials file path. If omitted, these will be `default` and `~/.aws/credentials`.
+
+```hcl
+plugin "aws" {
+  enabled = true
+
+  deep_check              = true
+  region                  = "us-east-1"
+  shared_credentials_file = "~/.aws/myapp"
+  profile                 = "AWS_PROFILE"
+}
+```
+
+If these configurations are defined in the provider block, they will also be taken into account. But the priority is lower than the above way.
+
+```hcl
+provider "aws" {
+  region                  = "us-west-2"
+  shared_credentials_file = "/Users/tf_user/.aws/creds"
+  profile                 = "customprofile"
+}
+```
+
+### Environment variables
+
+This plugin 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
+```
+
+### Role-based authentication
+
+This plugin fetches credentials in the same way as Terraform. See [this documentation](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#codebuild-ecs-and-eks-roles) for the role-based authentication.
+
+### Assume role
+
+This plugin can assume a role in the same way as Terraform. See [this documentation](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#assume-role).