From 051a4227d0547422d292f3a480c37fd75c2c95b8 Mon Sep 17 00:00:00 2001
From: Chris Marchesi <cmarchesi@paybyphone.com>
Date: Mon, 14 Nov 2016 12:06:00 -0800
Subject: [PATCH] docs/aws: Document initial_lifecycle_hook in
 aws_autoscaling_group

This is a useful feature that seems to have been added in September,
with 7dd7078, but has not yet been documented.
---
 .../aws/r/autoscaling_group.html.markdown     | 64 ++++++++++++++-----
 .../autoscaling_lifecycle_hooks.html.markdown | 14 +++-
 2 files changed, 62 insertions(+), 16 deletions(-)

diff --git a/website/source/docs/providers/aws/r/autoscaling_group.html.markdown b/website/source/docs/providers/aws/r/autoscaling_group.html.markdown
index 34cca690b..9c2c7dac9 100644
--- a/website/source/docs/providers/aws/r/autoscaling_group.html.markdown
+++ b/website/source/docs/providers/aws/r/autoscaling_group.html.markdown
@@ -14,30 +14,47 @@ Provides an AutoScaling Group resource.
 
 ```
 resource "aws_placement_group" "test" {
-  name = "test"
+  name     = "test"
   strategy = "cluster"
 }
 
 resource "aws_autoscaling_group" "bar" {
-  availability_zones = ["us-east-1a"]
-  name = "foobar3-terraform-test"
-  max_size = 5
-  min_size = 2
+  availability_zones        = ["us-east-1a"]
+  name                      = "foobar3-terraform-test"
+  max_size                  = 5
+  min_size                  = 2
   health_check_grace_period = 300
-  health_check_type = "ELB"
-  desired_capacity = 4
-  force_delete = true
-  placement_group = "${aws_placement_group.test.id}"
-  launch_configuration = "${aws_launch_configuration.foobar.name}"
+  health_check_type         = "ELB"
+  desired_capacity          = 4
+  force_delete              = true
+  placement_group           = "${aws_placement_group.test.id}"
+  launch_configuration      = "${aws_launch_configuration.foobar.name}"
+
+  initial_lifecycle_hook {
+    name                   = "foobar"
+    default_result         = "CONTINUE"
+    heartbeat_timeout      = 2000
+    lifecycle_transition   = "autoscaling:EC2_INSTANCE_LAUNCHING"
+
+    notification_metadata = <<EOF
+{
+  "foo": "bar"
+}
+EOF
+
+    notification_target_arn = "arn:aws:sqs:us-east-1:444455556666:queue1*"
+    role_arn                = "arn:aws:iam::123456789012:role/S3Access"
+  }
 
   tag {
-    key = "foo"
-    value = "bar"
+    key                 = "foo"
+    value               = "bar"
     propagate_at_launch = true
   }
+
   tag {
-    key = "lorem"
-    value = "ipsum"
+    key                 = "lorem"
+    value               = "ipsum"
     propagate_at_launch = false
   }
 }
@@ -54,6 +71,12 @@ The following arguments are supported:
 * `availability_zones` - (Optional) A list of AZs to launch resources in.
    Required only if you do not specify any `vpc_zone_identifier`
 * `launch_configuration` - (Required) The name of the launch configuration to use.
+* `initial_lifecycle_hook` - (Optional) One or more
+  [Lifecycle Hooks](http://docs.aws.amazon.com/autoscaling/latest/userguide/lifecycle-hooks.html)
+  to attach to the autoscaling group **before** instances are launched. The
+  syntax is exactly the same as the separate
+  [`aws_autoscaling_lifecycle_hook`](/docs/providers/aws/r/autoscaling_lifecycle_hooks.html)
+  resource, without the `autoscaling_group_name` attribute.
 * `health_check_grace_period` - (Optional, Default: 300) Time (in seconds) after instance comes into service before checking health.
 * `health_check_type` - (Optional) "EC2" or "ELB". Controls how health checking is done.
 * `desired_capacity` - (Optional) The number of Amazon EC2 instances that
@@ -120,7 +143,18 @@ The following attributes are exported:
 * `target_group_arns` (Optional) list of Target Group ARNs that apply to this
 AutoScaling Group
 
-~> **NOTE:** When using `ELB` as the health_check_type, `health_check_grace_period` is required.
+~> **NOTE:** When using `ELB` as the `health_check_type`, `health_check_grace_period` is required.
+
+~> **NOTE:** Terraform has two types of ways you can add lifecycle hooks - via
+the `initial_lifecycle_hook` attribute from this resource, or via the separate
+[`aws_autoscaling_lifecycle_hook`](/docs/providers/aws/r/autoscaling_lifecycle_hooks.html)
+resource. `initial_lifecycle_hook` exists here because any lifecycle hooks
+added with `aws_autoscaling_lifecycle_hook` will not be added until the
+autoscaling group has been created, and depending on your
+[capacity](#waiting-for-capacity) settings, after the initial instances have
+been launched, creating unintended behavior. If you need hooks to run on all
+instances, add them with `initial_lifecycle_hook` here, but take
+care to not duplicate these hooks in `aws_autoscaling_lifecycle_hook`.
 
 ## Waiting for Capacity
 
diff --git a/website/source/docs/providers/aws/r/autoscaling_lifecycle_hooks.html.markdown b/website/source/docs/providers/aws/r/autoscaling_lifecycle_hooks.html.markdown
index 7f3d5f8cf..13f8da588 100644
--- a/website/source/docs/providers/aws/r/autoscaling_lifecycle_hooks.html.markdown
+++ b/website/source/docs/providers/aws/r/autoscaling_lifecycle_hooks.html.markdown
@@ -10,6 +10,18 @@ description: |-
 
 Provides an AutoScaling Lifecycle Hook resource.
 
+~> **NOTE:** Terraform has two types of ways you can add lifecycle hooks - via
+the `initial_lifecycle_hook` attribute from the 
+[`aws_autoscaling_group`](/docs/providers/aws/r/autoscaling_group.html)
+resource, or via this one. Hooks added via this resource will not be added
+until the autoscaling group has been created, and depending on your
+[capacity](/docs/providers/aws/r/autoscaling_group.html#waiting-for-capacity)
+settings, after the initial instances have been launched, creating unintended
+behavior. If you need hooks to run on all instances, add them with
+`initial_lifecycle_hook` in
+[`aws_autoscaling_group`](/docs/providers/aws/r/autoscaling_group.html),
+but take care to not duplicate those hooks with this resource.
+
 ## Example Usage
 
 ```
@@ -52,4 +64,4 @@ The following arguments are supported:
 * `lifecycle_transition` - (Optional) The instance state to which you want to attach the lifecycle hook. For a list of lifecycle hook types, see [describe-lifecycle-hook-types](https://docs.aws.amazon.com/cli/latest/reference/autoscaling/describe-lifecycle-hook-types.html#examples)
 * `notification_metadata` - (Optional) Contains additional information that you want to include any time Auto Scaling sends a message to the notification target.
 * `notification_target_arn` - (Optional) The ARN of the notification target that Auto Scaling will use to notify you when an instance is in the transition state for the lifecycle hook. This ARN target can be either an SQS queue or an SNS topic.
-* `role_arn` - (Optional) The ARN of the IAM role that allows the Auto Scaling group to publish to the specified notification target.
\ No newline at end of file
+* `role_arn` - (Optional) The ARN of the IAM role that allows the Auto Scaling group to publish to the specified notification target.