aws-ecs-tf

This is an example project showcasing the provisioning of a Replicated Redis cluster AKA ElastiCache, and the associated resources that are required to make it publicly accessible, on AWS, using Terraform.

Table of Contents

1. Prerequesites
2. Usage
3. Testing
4. License

Prerequesites

1. Install the Necessary Tools

• Terraform

  brew install terraform

• Redis

  brew install redis

2. Create a Free AWS Account

Head to https://aws.amazon.com/free on your browser and click "Create a Free Account". Follow the steps until the account setup is complete.

3. Configure AWS Credentials

• On the AWS console, head over to the IAM service.

• Click "Users" > "Create User" and give it a name, such as "Terraform" and click "Next".

• On the "Permissions options", click "Attach policies directly", then "Next", followed by "Create user".

• Click the user that was just created, then click "Create access key". Follow through the steps and copy the Access Key ID and Value. You will be needing them in the following steps.

4. Generate an SSH Key Pair

• Open a terminal window and run:

  ssh-keygen -b 4096 -t rsa

• You will be prompted to enter a filename. By default, your keys will be saved as id_rsa and id_rsa.pub. Simply press Enter to confirm the default.

• When prompted, enter an optional passphrase. This will created a hidden directory called .ssh that contains both your public (id_rsa.pub) and private (id_rsa) key files.

Usage

After making sure that your AWS credentials have been configured and the prerequesites have been installed, we are a couple of terraform commands away from creating our cluster. Before doing that though, take a look at the configuration parameters this module accepts as shown below, and feel free to customize them to your needs.

Name	Description	Type	Default	Required
additional_tags	Define additional tags to be added to the resources.	map	{ "Provisioner": "Terraform" }	no
ami_override	Override the AMI for the SSH host.	any	null	no
automatic_failover_enabled	Specifies whether a read-only replica will be automatically promoted to read/write primary if the existing primary fails.	bool	true	no
cidr_blocks	The CIDR blocks for creating subnets.	list	[ "10.1.1.0/24", "10.1.2.0/24" ]	no
cluster_id	Replication group identifier.	string	"redis-cluster"	no
instance_type	Instance type to use for the instance.	string	"t2.nano"	no
monitoring_enabled	If true, the launched EC2 instance will have detailed monitoring enabled.	bool	false	no
node_groups	Number of node groups (shards) for this Redis replication group.	number	3	no
node_type	Instance class to be used.	string	"cache.t2.micro"	no
port	Port number on which each of the cache nodes will accept connections.	number	6379	no
public_key_path	Path to public key for ssh access.	string	"~/.ssh/id_rsa.pub"	no
vpc_cidr_block	The IPv4 CIDR block for the VPC.	string	"10.1.0.0/16"	no

You can set these values in the terraform.tfvars file. E.g:

cluster_id      = "my-cluster"
node_type       = "cache.m4.large"
node_groups     = 2
public_key_path = "~/.ssh/id_ed25519.pub"

In order to proceed, first set the AWS credentials that you copied earlier as environment variables, using the commands below:

export AWS_ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
export AWS_SECRET_ACCESS_KEY=<YOUR_ACCESS_KEY_VALUE>

Initialize terraform with:

terraform init

Then, plan the changes with:

terraform plan

In order to apply the changes, run:

terraform apply

After making sure that the output looks as expected, when prompted, type "yes" and hit enter. While you wait, terraform will be provisioning the resources shown below.

Name	Description
aws_elasticache_replication_group	The replicated Redis cluster.
aws_elasticache_subnet_group	The cluster's subnet group.
aws_instance	An EC2 instance acting as a bastion host.
aws_internet_gateway	Enables resources to connect to the internet.
aws_key_pair	Public/private key pair for connecting to the EC2 instance.
aws_route	Grant the VPC internet access on its main route table.
aws_security_group	Controls the inbound/outbound traffic resources.
aws_subnet	A range of IP addresses in the VPC.
aws_vpc	A VPC lets you launch AWS resources in a logically isolated virtual network.

After the resources have been provisoned, terraform will print the outputs shown below.

Name	Description
configuration_endpoint	Address of the replication group configuration endpoint.
redis_arn	ARN of the created Redis cluster.
redis_cmd	Command for connecting to the created Redis cluster.
ssh_cmd	Command for connecting to the SSH host.
ssh_host	Public IP address assigned to the instance.

Testing

In order to test out our Redis cluster, we first have to connect to the host via SSH. The command for doing this can be found in the outputs of the apply command, and looks like this:

ssh [email protected]

Once you get a shell in the running host, run the redis-cli command from the terraform output in order to connect to the cluster, which looks like this:

redis-cli -h redis-cluster.abcdef.clustercfg.use1.cache.amazonaws.com -p 6379

Once you are connected, run:

CLUSTER NODES

in order to get a list of the running nodes. You can connect to any one of them by running:

redis-cli -h <NODE_IP_ADDRESS> -p 6379

After getting a shell in a node, you can set a key-value pair with:

SET <KEY> <VALUE>

and get a value with:

GET <KEY>

In order to get more information on the node, run:

INFO

License

The project is licensed under the MIT License.