Skip to content

Commit

Permalink
Merge pull request #17051 from hashicorp/elasticache-doc-fixes
Browse files Browse the repository at this point in the history 
ElastiCache documentation fixes and bringing some validations in line with documentation
  • Loading branch information
@gdavison
gdavison authored Jan 21, 2021
2 parents 4bd169a + f77454e commit a0ac9cc
Show file tree
Hide file tree
Showing 4 changed files with 67 additions and 68 deletions.
48 changes: 23 additions & 25 deletions aws/resource_aws_elasticache_cluster.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,11 @@ import (
"github.com/terraform-providers/terraform-provider-aws/aws/internal/tfresource"
)

const (
elasticacheDefaultRedisPort = "6379"
elasticacheDefaultMemcachedPort = "11211"
)

func resourceAwsElasticacheCluster() *schema.Resource {
return &schema.Resource{
Create: resourceAwsElasticacheClusterCreate,
Expand Down Expand Up @@ -156,7 +161,7 @@ func resourceAwsElasticacheCluster() *schema.Resource {
ForceNew: true,
DiffSuppressFunc: func(k, old, new string, d *schema.ResourceData) bool {
// Suppress default memcached/redis ports when not defined
if !d.IsNewResource() && new == "0" && (old == "6379" || old == "11211") {
if !d.IsNewResource() && new == "0" && (old == elasticacheDefaultRedisPort || old == elasticacheDefaultMemcachedPort) {
return true
}
return false
Expand Down Expand Up @@ -206,18 +211,18 @@ func resourceAwsElasticacheCluster() *schema.Resource {
Elem: &schema.Schema{Type: schema.TypeString},
Set: schema.HashString,
},
// A single-element string list containing an Amazon Resource Name (ARN) that
// uniquely identifies a Redis RDB snapshot file stored in Amazon S3. The snapshot
// file will be used to populate the node group.
//
// See also:
// https://github.com/aws/aws-sdk-go/blob/4862a174f7fc92fb523fc39e68f00b87d91d2c3d/service/elasticache/api.go#L2079
"snapshot_arns": {
Type: schema.TypeSet,
Type: schema.TypeList,
Optional: true,
ForceNew: true,
Elem: &schema.Schema{Type: schema.TypeString},
Set: schema.HashString,
MaxItems: 1,
Elem: &schema.Schema{
Type: schema.TypeString,
ValidateFunc: validation.All(
validateArn,
validation.StringDoesNotContainAny(","),
),
},
},
"snapshot_retention_limit": {
Type: schema.TypeInt,
Expand Down Expand Up @@ -295,7 +300,7 @@ func resourceAwsElasticacheCluster() *schema.Resource {
func(_ context.Context, diff *schema.ResourceDiff, v interface{}) error {
// Engine memcached does not currently support vertical scaling
// InvalidParameterCombination: Scaling is not supported for engine memcached
// https://docs.aws.amazon.com/AmazonElastiCache/latest/UserGuide/Scaling.Memcached.html#Scaling.Memcached.Vertically
// https://docs.aws.amazon.com/AmazonElastiCache/latest/mem-ug/Scaling.html#Scaling.Memcached.Vertically
if diff.Id() == "" || !diff.HasChange("node_type") {
return nil
}
Expand Down Expand Up @@ -325,15 +330,9 @@ func resourceAwsElasticacheClusterCreate(d *schema.ResourceData, meta interface{
if v, ok := d.GetOk("replication_group_id"); ok {
req.ReplicationGroupId = aws.String(v.(string))
} else {
securityNameSet := d.Get("security_group_names").(*schema.Set)
securityIdSet := d.Get("security_group_ids").(*schema.Set)
securityNames := expandStringSet(securityNameSet)
securityIds := expandStringSet(securityIdSet)
tags := keyvaluetags.New(d.Get("tags").(map[string]interface{})).IgnoreAws().ElasticacheTags()

req.CacheSecurityGroupNames = securityNames
req.SecurityGroupIds = securityIds
req.Tags = tags
req.CacheSecurityGroupNames = expandStringSet(d.Get("security_group_names").(*schema.Set))
req.SecurityGroupIds = expandStringSet(d.Get("security_group_ids").(*schema.Set))
req.Tags = keyvaluetags.New(d.Get("tags").(map[string]interface{})).IgnoreAws().ElasticacheTags()
}

if v, ok := d.GetOk("cluster_id"); ok {
Expand Down Expand Up @@ -385,11 +384,10 @@ func resourceAwsElasticacheClusterCreate(d *schema.ResourceData, meta interface{
req.NotificationTopicArn = aws.String(v.(string))
}

snaps := d.Get("snapshot_arns").(*schema.Set)
if snaps.Len() > 0 {
s := expandStringSet(snaps)
req.SnapshotArns = s
log.Printf("[DEBUG] Restoring Redis cluster from S3 snapshot: %#v", s)
snaps := d.Get("snapshot_arns").([]interface{})
if len(snaps) > 0 {
req.SnapshotArns = expandStringList(snaps)
log.Printf("[DEBUG] Restoring Redis cluster from S3 snapshot: %#v", snaps)
}

if v, ok := d.GetOk("snapshot_name"); ok {
Expand Down
18 changes: 8 additions & 10 deletions aws/resource_aws_elasticache_replication_group.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -156,8 +156,8 @@ func resourceAwsElasticacheReplicationGroup() *schema.Resource {
Optional: true,
ForceNew: true,
DiffSuppressFunc: func(k, old, new string, d *schema.ResourceData) bool {
// Suppress default memcached/redis ports when not defined
if !d.IsNewResource() && new == "0" && (old == "6379" || old == "11211") {
// Suppress default Redis ports when not defined
if !d.IsNewResource() && new == "0" && old == elasticacheDefaultRedisPort {
return true
}
return false
Expand Down Expand Up @@ -205,19 +205,17 @@ func resourceAwsElasticacheReplicationGroup() *schema.Resource {
Elem: &schema.Schema{Type: schema.TypeString},
Set: schema.HashString,
},
// A single-element string list containing an Amazon Resource Name (ARN) that
// uniquely identifies a Redis RDB snapshot file stored in Amazon S3. The snapshot
// file will be used to populate the node group.
//
// See also:
// https://github.com/aws/aws-sdk-go/blob/4862a174f7fc92fb523fc39e68f00b87d91d2c3d/service/elasticache/api.go#L2079
"snapshot_arns": {
Type: schema.TypeSet,
Optional: true,
ForceNew: true,
// Note: Unlike aws_elasticache_cluster, this does not have a limit of 1 item.
Elem: &schema.Schema{
Type: schema.TypeString,
ValidateFunc: validateArn,
Type: schema.TypeString,
ValidateFunc: validation.All(
validateArn,
validation.StringDoesNotContainAny(","),
),
},
Set: schema.HashString,
},
Expand Down
53 changes: 25 additions & 28 deletions website/docs/r/elasticache_cluster.html.markdown
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,25 @@ description: |-

# Resource: aws_elasticache_cluster

Provides an ElastiCache Cluster resource, which manages a Memcached cluster or Redis instance.
Provides an ElastiCache Cluster resource, which manages either a
[Memcached cluster](https://docs.aws.amazon.com/AmazonElastiCache/latest/mem-ug/WhatIs.html), a
[single-node Redis instance](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/WhatIs.html), or a
[read replica in a Redis (Cluster Mode Enabled) replication group].

For working with Redis (Cluster Mode Enabled) replication groups, see the
[`aws_elasticache_replication_group` resource](/docs/providers/aws/r/elasticache_replication_group.html).

~> **Note:** When you change an attribute, such as `node_type`, by default
~> **Note:** When you change an attribute, such as `num_cache_nodes`, by default
it is applied in the next maintenance window. Because of this, Terraform may report
a difference in its planning phase because the actual modification has not yet taken
place. You can use the `apply_immediately` flag to instruct the service to apply the
change immediately. 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.
See the AWS Documentation on Modifying an ElastiCache Cache Cluster for
[ElastiCache for Memcached](https://docs.aws.amazon.com/AmazonElastiCache/latest/mem-ug/Clusters.Modify.html) or
[ElastiCache for Redis](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/Clusters.Modify.html)
for more information.

~> **Note:** Any attribute changes that re-create the resource will be applied immediately, regardless of the value of `apply_immediately`.

## Example Usage

Expand Down Expand Up @@ -64,12 +73,11 @@ resource "aws_elasticache_cluster" "replica" {
The following arguments are supported:

* `cluster_id` – (Required) Group identifier. ElastiCache converts
this name to lowercase
this name to lowercase. Changing this value will re-create the resource.

* `replication_group_id` - (Optional) The ID of the replication group to which this cluster should belong. If this parameter is specified, the cluster is added to the specified replication group as a read replica; otherwise, the cluster is a standalone primary that is not part of any replication group.

* `engine` – (Required unless `replication_group_id` is provided) Name of the cache engine to be used for this cache cluster.
Valid values for this parameter are `memcached` or `redis`
* `engine` – (Required unless `replication_group_id` is provided) Name of the cache engine to be used for this cache cluster. Valid values are `memcached` or `redis`.

* `engine_version` – (Optional) Version number of the cache engine to be used.
See [Describe Cache Engine Versions](https://docs.aws.amazon.com/cli/latest/reference/elasticache/describe-cache-engine-versions.html)
Expand All @@ -80,38 +88,32 @@ on the cache cluster is performed. The format is `ddd:hh24:mi-ddd:hh24:mi` (24H
The minimum maintenance window is a 60 minute period. Example: `sun:05:00-sun:09:00`

* `node_type` – (Required unless `replication_group_id` is provided) The compute and memory capacity of the nodes. See
[Available Cache Node Types](https://aws.amazon.com/elasticache/details#Available_Cache_Node_Types) for
supported node types
[Available Cache Node Types](https://aws.amazon.com/elasticache/pricing/#Available_node_types) for
supported node types. For Memcached, changing this value will re-create the resource.

* `num_cache_nodes` – (Required unless `replication_group_id` is provided) The initial number of cache nodes that the
cache cluster will have. For Redis, this value must be 1. For Memcache, this
cache cluster will have. For Redis, this value must be 1. For Memcached, this
value must be between 1 and 20. If this number is reduced on subsequent runs,
the highest numbered nodes will be removed.

* `parameter_group_name` – (Required unless `replication_group_id` is provided) Name of the parameter group to associate
with this cache cluster

* `port` – (Optional) The port number on which each of the cache nodes will accept connections. For Memcache the default is 11211, and for Redis the default port is 6379. Cannot be provided with `replication_group_id`.
* `port` – (Optional) The port number on which each of the cache nodes will accept connections. For Memcached the default is 11211, and for Redis the default port is 6379. Cannot be provided with `replication_group_id`. Changing this value will re-create the resource.

* `subnet_group_name` – (Optional, VPC only) Name of the subnet group to be used
for the cache cluster.
* `subnet_group_name` – (Optional, VPC only) Name of the subnet group to be used for the cache cluster. Changing this value will re-create the resource.

* `security_group_names` – (Optional, EC2 Classic only) List of security group
names to associate with this cache cluster
* `security_group_names` – (Optional, EC2 Classic only) List of security group names to associate with this cache cluster. Changing this value will re-create the resource.

* `security_group_ids` – (Optional, VPC only) One or more VPC security groups associated
with the cache cluster
* `security_group_ids` – (Optional, VPC only) One or more VPC security groups associated with the cache cluster

* `apply_immediately` - (Optional) Specifies whether any database modifications
are applied immediately, or during the next maintenance window. Default is
`false`. See [Amazon ElastiCache Documentation for more information.][1]
(Available since v0.6.0)
`false`. See [Amazon ElastiCache Documentation for more information.](https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_ModifyCacheCluster.html)

* `snapshot_arns` – (Optional) A single-element string list containing an
Amazon Resource Name (ARN) of a Redis RDB snapshot file stored in Amazon S3.
Example: `arn:aws:s3:::my_bucket/snapshot1.rdb`
* `snapshot_arns` – (Optional, Redis only) A single-element string list containing an Amazon Resource Name (ARN) of a Redis RDB snapshot file stored in Amazon S3. The object name cannot contain any commas. Changing `snapshot_arns` forces a new resource.

* `snapshot_name` - (Optional) The name of a snapshot from which to restore data into the new node group. Changing the `snapshot_name` forces a new resource.
* `snapshot_name` - (Optional, Redis only) The name of a snapshot from which to restore data into the new node group. Changing `snapshot_name` forces a new resource.

* `snapshot_window` - (Optional, Redis only) The daily time range (in UTC) during which ElastiCache will
begin taking a daily snapshot of your cache cluster. Example: 05:00-09:00
Expand All @@ -128,7 +130,7 @@ SNS topic to send ElastiCache notifications to. Example:

* `az_mode` - (Optional, Memcached only) Specifies whether the nodes in this Memcached node group are created in a single Availability Zone or created across multiple Availability Zones in the cluster's region. Valid values for this parameter are `single-az` or `cross-az`, default is `single-az`. If you want to choose `cross-az`, `num_cache_nodes` must be greater than `1`

* `availability_zone` - (Optional) The Availability Zone for the cache cluster. If you want to create cache nodes in multi-az, use `preferred_availability_zones` instead. Default: System chosen Availability Zone.
* `availability_zone` - (Optional) The Availability Zone for the cache cluster. If you want to create cache nodes in multi-az, use `preferred_availability_zones` instead. Default: System chosen Availability Zone. Changing this value will re-create the resource.

* `preferred_availability_zones` - (Optional, Memcached only) A list of the Availability Zones in which cache nodes are created. If you are creating your cluster in an Amazon VPC you can only locate nodes in Availability Zones that are associated with the subnets in the selected subnet group. The number of Availability Zones listed must equal the value of `num_cache_nodes`. If you want all the nodes in the same Availability Zone, use `availability_zone` instead, or repeat the Availability Zone multiple times in the list. Default: System chosen Availability Zones. Detecting drift of existing node availability zone is not currently supported. Updating this argument by itself to migrate existing node availability zones is not currently supported and will show a perpetual difference.

Expand All @@ -142,14 +144,9 @@ In addition to all arguments above, the following attributes are exported:

* `arn` - The ARN of the created ElastiCache Cluster.
* `cache_nodes` - List of node objects including `id`, `address`, `port` and `availability_zone`.
Referenceable e.g. as `${aws_elasticache_cluster.bar.cache_nodes.0.address}`
* `configuration_endpoint` - (Memcached only) The configuration endpoint to allow host discovery.
* `cluster_address` - (Memcached only) The DNS name of the cache cluster without the port appended.

[1]: https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_ModifyCacheCluster.html
[2]: https://docs.aws.amazon.com/AmazonElastiCache/latest/UserGuide/Clusters.Modify.html


## Import

ElastiCache Clusters can be imported using the `cluster_id`, e.g.
Expand Down
16 changes: 11 additions & 5 deletions website/docs/r/elasticache_replication_group.html.markdown
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,10 @@ description: |-
# Resource: aws_elasticache_replication_group

Provides an ElastiCache Replication Group resource.
For working with Memcached or single primary Redis instances (Cluster Mode Disabled), see the
[`aws_elasticache_cluster` resource](/docs/providers/aws/r/elasticache_cluster.html).

For working with a [Memcached cluster](https://docs.aws.amazon.com/AmazonElastiCache/latest/mem-ug/WhatIs.html) or a
[single-node Redis instance (Cluster Mode Disabled)](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/WhatIs.html),
see the [`aws_elasticache_cluster` resource](/docs/providers/aws/r/elasticache_cluster.html).

~> **Note:** When you change an attribute, such as `engine_version`, by
default the ElastiCache API applies it in the next maintenance window. Because
Expand All @@ -19,6 +21,11 @@ actual modification has not yet taken place. You can use the
`apply_immediately` flag to instruct the service to apply the change
immediately. Using `apply_immediately` can result in a brief downtime as
servers reboots.
See the AWS Documentation on
[Modifying an ElastiCache Cache Cluster](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/Clusters.Modify.html)
for more information.

~> **Note:** Any attribute changes that re-create the resource will be applied immediately, regardless of the value of `apply_immediately`.

~> **Note:** Be aware of the terminology collision around "cluster" for `aws_elasticache_replication_group`. For example, it is possible to create a ["Cluster Mode Disabled [Redis] Cluster"](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/Clusters.Create.CON.Redis.html). With "Cluster Mode Enabled", the data will be stored in shards (called "node groups"). See [Redis Cluster Configuration](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/cluster-create-determine-requirements.html#redis-cluster-configuration) for a diagram of the differences. To enable cluster mode, use a parameter group that has cluster mode enabled. The default parameter groups provided by AWS end with ".cluster.on", for example `default.redis6.x.cluster.on`.

Expand Down Expand Up @@ -118,9 +125,8 @@ The following arguments are supported:
* `subnet_group_name` - (Optional) The name of the cache subnet group to be used for the replication group.
* `security_group_names` - (Optional) A list of cache security group names to associate with this replication group.
* `security_group_ids` - (Optional) One or more Amazon VPC security groups associated with this replication group. Use this parameter only when you are creating a replication group in an Amazon Virtual Private Cloud
* `snapshot_arns` – (Optional) A single-element string list containing an
Amazon Resource Name (ARN) of a Redis RDB snapshot file stored in Amazon S3.
Example: `arn:aws:s3:::my_bucket/snapshot1.rdb`
* `snapshot_arns` – (Optional) A list of
Amazon Resource Names (ARNs) that identify Redis RDB snapshot files stored in Amazon S3. The names object names cannot contain any commas.
* `snapshot_name` - (Optional) The name of a snapshot from which to restore data into the new node group. Changing the `snapshot_name` forces a new resource.
* `maintenance_window` – (Optional) Specifies the weekly time range for when maintenance
on the cache cluster is performed. The format is `ddd:hh24:mi-ddd:hh24:mi` (24H Clock UTC).
Expand Down

0 comments on commit a0ac9cc

Please sign in to comment.