README.yaml

---
#
# This is the canonical configuration for the `README.md`
# Run `make readme` to rebuild the `README.md`
#

# Name of this project
name: terraform-aws-elasticache-redis

# Tags of this project
tags:
  - aws
  - cache
  - elasticache
  - elasticache-redis
  - terraform
  - terraform-module

# Categories of this project
categories:
  - terraform-modules/databases

# Logo for this project
#logo: docs/logo.png

# License of this project
license: "APACHE2"

# Canonical GitHub repo
github_repo: cloudposse/terraform-aws-elasticache-redis

# Badges to display
badges:
  - name: "Latest Release"
    image: "https://img.shields.io/github/release/cloudposse/terraform-aws-elasticache-redis.svg"
    url: "https://github.com/cloudposse/terraform-aws-elasticache-redis/releases/latest"
  - name: "Slack Community"
    image: "https://slack.cloudposse.com/badge.svg"
    url: "https://slack.cloudposse.com"

# List any related terraform modules that this module may be used with or that this module depends on.
related:
  - name: "terraform-aws-security-group"
    description: "Terraform module to provision an AWS Security Group."
    url: "https://github.com/cloudposse/terraform-aws-security-group"
  - name: "terraform-null-label"
    description: "Terraform module designed to generate consistent names and tags for resources. Use terraform-null-label to implement a strict naming convention."
    url: "https://github.com/cloudposse/terraform-null-label"


# Short description of this project
description: |-
  Terraform module to provision an [`ElastiCache`](https://aws.amazon.com/elasticache/) Redis Cluster

# How to use this project
# Note: use absolute rather than relative URLs because Hashicorp will copy the README to
# its Terraform Registry website but will not fix relative URLs in the process, leading
# to broken links in the official Terraform documentation.
usage: |-
  _**Disruptive changes introduced at version 0.41.0**. If upgrading from an earlier version, see
  [migration notes](https://github.com/cloudposse/terraform-aws-elasticache-redis/blob/master/docs/migration-notes-0.41.0.md) for details._

  Note that this uses secure defaults. One of the ways this module can trip users up is with `transit_encryption_enabled`
  which is `true` by default. With this enabled, one does not simply `redis-cli` in without setting up an `stunnel`.
  Amazon provides [good documentation on how to connect with it enabled](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/in-transit-encryption.html#connect-tls).
  If this is not desired behavior, set `transit_encryption_enabled=false`.

  This module creates, by default, a new security group for the Elasticache Redis Cluster. When a configuration
  change (for example, a different security group name) cannot be applied to the security group, Terraform will
  replace that security group with a new one with the new configuration. In order to allow Terraform to fully manage the security group, you
  should not place any other resources in (or associate any other resources with) the security group this module
  creates. Also, in order to keep things from breaking when this module replaces the security group, you should
  not reference the created security group anywhere else (such as in rules in other security groups). If you
  want to associate the cluster with a more stable security group that you can reference elsewhere, create that security group
  outside this module (perhaps with [terraform-aws-security-group](https://github.com/cloudposse/terraform-aws-security-group))
  and pass the security group ID in via `associated_security_group_ids`.

  **Note about `zone_id`**: Previously, `zone_id` was a string. This caused problems (see [#82](https://github.com/cloudposse/terraform-aws-elasticache-redis/issues/82)).
  Now `zone_id` should be supplied as a `list(string)`, either empty or with exactly 1 zone ID in order to avoid the problem.

  For a complete example, see [examples/complete](examples/complete).

  For automated tests of the complete example using [bats](https://github.com/bats-core/bats-core) and [Terratest](https://github.com/gruntwork-io/terratest) (which tests and deploys the example on AWS), see [test](test).

  ```hcl
  provider "aws" {
    region = var.region
  }

  module "this" {
    source  = "cloudposse/label/null"
    # Cloud Posse recommends pinning every module to a specific version
    # version = "x.x.x"
    namespace  = var.namespace
    stage      = var.stage
    name       = var.name
  }

  module "vpc" {
    source = "cloudposse/vpc/aws"
    # Cloud Posse recommends pinning every module to a specific version
    # version = "x.x.x"

    cidr_block = "172.16.0.0/16"

    context = module.this.context
  }

  module "subnets" {
    source = "cloudposse/dynamic-subnets/aws"
    # Cloud Posse recommends pinning every module to a specific version
    # version = "x.x.x"

    availability_zones   = var.availability_zones
    vpc_id               = module.vpc.vpc_id
    igw_id               = module.vpc.igw_id
    cidr_block           = module.vpc.vpc_cidr_block
    nat_gateway_enabled  = true
    nat_instance_enabled = false

    context = module.this.context
  }

  module "redis" {
    source = "cloudposse/elasticache-redis/aws"
    # Cloud Posse recommends pinning every module to a specific version
    # version = "x.x.x"

    availability_zones         = var.availability_zones
    zone_id                    = var.zone_id
    vpc_id                     = module.vpc.vpc_id
    allowed_security_group_ids = [module.vpc.vpc_default_security_group_id]
    subnets                    = module.subnets.private_subnet_ids
    cluster_size               = var.cluster_size
    instance_type              = var.instance_type
    apply_immediately          = true
    automatic_failover_enabled = false
    engine_version             = var.engine_version
    family                     = var.family
    at_rest_encryption_enabled = var.at_rest_encryption_enabled
    transit_encryption_enabled = var.transit_encryption_enabled

    parameter = [
      {
        name  = "notify-keyspace-events"
        value = "lK"
      }
    ]

    context = module.this.context
  }
  ```

examples: |-
  Review the [complete example](examples/complete) to see how to use this module.

include:
  - "docs/targets.md"
  - "docs/terraform.md"

# Contributors to this project
contributors:
  - name: "Erik Osterman"
    github: "osterman"
  - name: "Igor Rodionov"
    github: "goruha"
  - name: "Andriy Knysh"
    github: "aknysh"
  - name: "Daren Desjardins"
    github: "darend"
  - name: "Max Moon"
    github: "MoonMoon1919"
  - name: "Christopher Riley"
    github: "christopherriley"
  - name: "RB"
    github: "nitrocode"