resource/aws_api_gateway_stage: Add kinesis access logs test + docs (#…

…11425)

Output from acceptance testing:

```
--- PASS: TestAccAWSAPIGatewayStage_accessLogSettings (217.24s)
--- PASS: TestAccAWSAPIGatewayStage_accessLogSettings_kinesis (317.54s)
--- PASS: TestAccAWSAPIGatewayStage_basic (441.31s)
```

aws/resource_aws_api_gateway_stage_test.go

@@ -145,6 +145,72 @@ func TestAccAWSAPIGatewayStage_accessLogSettings(t *testing.T) {
 	})
 }
 
+func TestAccAWSAPIGatewayStage_accessLogSettings_kinesis(t *testing.T) {
+	var conf apigateway.Stage
+	rName := acctest.RandString(5)
+	resourceName := "aws_api_gateway_stage.test"
+	clf := `$context.identity.sourceIp $context.identity.caller $context.identity.user [$context.requestTime] "$context.httpMethod $context.resourcePath $context.protocol" $context.status $context.responseLength $context.requestId`
+	json := `{ "requestId":"$context.requestId", "ip": "$context.identity.sourceIp", "caller":"$context.identity.caller", "user":"$context.identity.user", "requestTime":"$context.requestTime", "httpMethod":"$context.httpMethod", "resourcePath":"$context.resourcePath", "status":"$context.status", "protocol":"$context.protocol", "responseLength":"$context.responseLength" }`
+	xml := `<request id="$context.requestId"> <ip>$context.identity.sourceIp</ip> <caller>$context.identity.caller</caller> <user>$context.identity.user</user> <requestTime>$context.requestTime</requestTime> <httpMethod>$context.httpMethod</httpMethod> <resourcePath>$context.resourcePath</resourcePath> <status>$context.status</status> <protocol>$context.protocol</protocol> <responseLength>$context.responseLength</responseLength> </request>`
+	csv := `$context.identity.sourceIp,$context.identity.caller,$context.identity.user,$context.requestTime,$context.httpMethod,$context.resourcePath,$context.protocol,$context.status,$context.responseLength,$context.requestId`
+
+	resource.ParallelTest(t, resource.TestCase{
+		PreCheck:     func() { testAccPreCheck(t) },
+		Providers:    testAccProviders,
+		CheckDestroy: testAccCheckAWSAPIGatewayStageDestroy,
+		Steps: []resource.TestStep{
+			{
+				Config: testAccAWSAPIGatewayStageConfig_accessLogSettingsKinesis(rName, clf),
+				Check: resource.ComposeTestCheckFunc(
+					testAccCheckAWSAPIGatewayStageExists(resourceName, &conf),
+					resource.TestCheckResourceAttr(resourceName, "access_log_settings.#", "1"),
+					testAccMatchResourceAttrRegionalARN(resourceName, "access_log_settings.0.destination_arn", "firehose", regexp.MustCompile(`deliverystream/amazon-apigateway-.+`)),
+					resource.TestCheckResourceAttr(resourceName, "access_log_settings.0.format", clf),
+				),
+			},
+
+			{
+				Config: testAccAWSAPIGatewayStageConfig_accessLogSettingsKinesis(rName, json),
+				Check: resource.ComposeTestCheckFunc(
+					testAccCheckAWSAPIGatewayStageExists(resourceName, &conf),
+					testAccMatchResourceAttrRegionalARNNoAccount(resourceName, "arn", "apigateway", regexp.MustCompile(`/restapis/.+/stages/prod`)),
+					resource.TestCheckResourceAttr(resourceName, "access_log_settings.#", "1"),
+					testAccMatchResourceAttrRegionalARN(resourceName, "access_log_settings.0.destination_arn", "firehose", regexp.MustCompile(`deliverystream/amazon-apigateway-.+`)),
+					resource.TestCheckResourceAttr(resourceName, "access_log_settings.0.format", json),
+				),
+			},
+			{
+				Config: testAccAWSAPIGatewayStageConfig_accessLogSettingsKinesis(rName, xml),
+				Check: resource.ComposeTestCheckFunc(
+					testAccCheckAWSAPIGatewayStageExists(resourceName, &conf),
+					testAccMatchResourceAttrRegionalARNNoAccount(resourceName, "arn", "apigateway", regexp.MustCompile(`/restapis/.+/stages/prod`)),
+					resource.TestCheckResourceAttr(resourceName, "access_log_settings.#", "1"),
+					testAccMatchResourceAttrRegionalARN(resourceName, "access_log_settings.0.destination_arn", "firehose", regexp.MustCompile(`deliverystream/amazon-apigateway-.+`)),
+					resource.TestCheckResourceAttr(resourceName, "access_log_settings.0.format", xml),
+				),
+			},
+			{
+				Config: testAccAWSAPIGatewayStageConfig_accessLogSettingsKinesis(rName, csv),
+				Check: resource.ComposeTestCheckFunc(
+					testAccCheckAWSAPIGatewayStageExists(resourceName, &conf),
+					testAccMatchResourceAttrRegionalARNNoAccount(resourceName, "arn", "apigateway", regexp.MustCompile(`/restapis/.+/stages/prod`)),
+					resource.TestCheckResourceAttr(resourceName, "access_log_settings.#", "1"),
+					testAccMatchResourceAttrRegionalARN(resourceName, "access_log_settings.0.destination_arn", "firehose", regexp.MustCompile(`deliverystream/amazon-apigateway-.+`)),
+					resource.TestCheckResourceAttr(resourceName, "access_log_settings.0.format", csv),
+				),
+			},
+			{
+				Config: testAccAWSAPIGatewayStageConfig_basic(rName),
+				Check: resource.ComposeTestCheckFunc(
+					testAccCheckAWSAPIGatewayStageExists(resourceName, &conf),
+					testAccMatchResourceAttrRegionalARNNoAccount(resourceName, "arn", "apigateway", regexp.MustCompile(`/restapis/.+/stages/prod`)),
+					resource.TestCheckResourceAttr(resourceName, "access_log_settings.#", "0"),
+				),
+			},
+		},
+	})
+}
+
 func testAccCheckAWSAPIGatewayStageExists(n string, res *apigateway.Stage) resource.TestCheckFunc {
 	return func(s *terraform.State) error {
 		rs, ok := s.RootModule().Resources[n]
@@ -339,3 +405,63 @@ resource "aws_api_gateway_stage" "test" {
 }
 `, rName, format)
 }
+
+func testAccAWSAPIGatewayStageConfig_accessLogSettingsKinesis(rName string, format string) string {
+	return testAccAWSAPIGatewayStageConfig_base(rName) + fmt.Sprintf(`
+resource "aws_s3_bucket" "test" {
+  bucket = "%[1]s"
+  acl    = "private"
+}
+
+resource "aws_iam_role" "test" {
+  name = "%[1]s"
+
+  assume_role_policy = <<EOF
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Action": "sts:AssumeRole",
+      "Principal": {
+        "Service": "firehose.amazonaws.com"
+      },
+      "Effect": "Allow",
+      "Sid": ""
+    }
+  ]
+}
+EOF
+}
+
+resource "aws_kinesis_firehose_delivery_stream" "test" {
+  destination = "extended_s3"
+  name = "amazon-apigateway-%[1]s"
+
+  extended_s3_configuration {
+    role_arn   = "${aws_iam_role.test.arn}"
+    bucket_arn = "${aws_s3_bucket.test.arn}"
+  }
+
+
+}
+
+resource "aws_api_gateway_stage" "test" {
+  rest_api_id = "${aws_api_gateway_rest_api.test.id}"
+  stage_name = "prod"
+  deployment_id = "${aws_api_gateway_deployment.dev.id}"
+  cache_cluster_enabled = true
+  cache_cluster_size = "0.5"
+  variables = {
+    one = "1"
+    two = "2"
+  }
+  tags = {
+    Name = "tf-test"
+	}
+  access_log_settings {
+    destination_arn = "${aws_kinesis_firehose_delivery_stream.test.arn}"
+    format = %q
+  }
+}
+`, rName, format)
+}

website/docs/r/api_gateway_stage.html.markdown

@@ -116,7 +116,7 @@ The following arguments are supported:
 
 #### `access_log_settings`
 
-* `destination_arn` - (Required) ARN of the log group to send the logs to. Automatically removes trailing `:*` if present.
+* `destination_arn` - (Required) The Amazon Resource Name (ARN) of the CloudWatch Logs log group or Kinesis Data Firehose delivery stream to receive access logs. If you specify a Kinesis Data Firehose delivery stream, the stream name must begin with `amazon-apigateway-`. Automatically removes trailing `:*` if present.
 * `format` - (Required) The formatting and values recorded in the logs. 
 For more information on configuring the log format rules visit the AWS [documentation](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-logging.html)