Merge pull request #4386 from hashicorp/b-aws-rds-notes

Better document RDS `apply_immediately`

website/source/docs/providers/aws/r/db_instance.html.markdown

@@ -8,7 +8,21 @@ description: |-
 
 # aws\_db\_instance
 
-Provides an RDS instance resource.
+Provides an RDS instance resource.  A DB instance is an isolated database 
+environment in the cloud.  A DB instance can contain multiple user-created 
+databases. 
+
+Changes to a DB instance can occur when you manually change a
+parameter, such as `allocated_storage`, and are reflected in the next maintenance
+window. Because of this, Terraform may report a difference in it's planning
+phase because a modification has not yet taken place. You can use the
+`apply_immediately` flag to instruct the service to apply the change immediately 
+(see documentation below). 
+
+~> **Note:** using `apply_immediately` can result in a 
+brief downtime as the server reboots. See the AWS Docs on [RDS Maintenance][2] 
+for more information.
+
 
 ## Example Usage
 
@@ -114,3 +128,4 @@ The following attributes are exported:
 * `storage_encrypted` - Specifies whether the DB instance is encrypted
 
 [1]: http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Overview.Replication.html
+[2]: http://docs.aws.amazon.com/fr_fr/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.Maintenance.html

website/source/docs/providers/aws/r/elasticache_cluster.html.markdown

@@ -10,6 +10,17 @@ description: |-
 
 Provides an ElastiCache Cluster resource.
 
+Changes to a Cache Cluster can occur when you manually change a
+parameter, such as `node_type`, and are reflected in the next maintenance
+window. Because of this, Terraform may report a difference in it's planning
+phase because a modification has not yet taken place. You can use the
+`apply_immediately` flag to instruct the service to apply the change immediately 
+(see documentation below). 
+
+~> **Note:** using `apply_immediately` can result in a 
+brief downtime as the server reboots. See the AWS Docs on 
+[Modifying an ElastiCache Cache Cluster][2] for more information.
+
 ## Example Usage
 
 ```
@@ -101,3 +112,4 @@ The following attributes are exported:
 * `configuration_endpoint` - (Memcached only) The configuration endpoint to allow host discovery
 
 [1]: http://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_ModifyCacheCluster.html
+[2]: http://docs.aws.amazon.com/fr_fr/AmazonElastiCache/latest/UserGuide/Clusters.Modify.html

website/source/docs/providers/aws/r/rds_cluster.html.markdown

@@ -15,6 +15,17 @@ database engine.
 
 For more information on Amazon Aurora, see [Aurora on Amazon RDS][2] in the Amazon RDS User Guide.
 
+Changes to a RDS Cluster can occur when you manually change a
+parameter, such as `port`, and are reflected in the next maintenance
+window. Because of this, Terraform may report a difference in it's planning
+phase because a modification has not yet taken place. You can use the
+`apply_immediately` flag to instruct the service to apply the change immediately 
+(see documentation below). 
+
+~> **Note:** using `apply_immediately` can result in a 
+brief downtime as the server reboots. See the AWS Docs on [RDS Maintenance][4] 
+for more information.
+
 ## Example Usage
 
 ```
@@ -93,3 +104,4 @@ The following attributes are exported:
 
 [2]: http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_Aurora.html
 [3]: /docs/providers/aws/r/rds_cluster_instance.html
+[4]: http://docs.aws.amazon.com/fr_fr/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.Maintenance.html