# AWS TiDB TiUP tool
This tool helps you automatically setup TiDB cluster via TiUP in AWS.

![architecture](../img/architecture.png)

# Prerequisites
- Install [terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli)
- An AWS account
- Your AWS credentials. You can [create a new Access Key on this page](https://console.aws.amazon.com/iam/home?#/security_credentials)
- Install [aws cli](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html)
- [Configure AWS crendential](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) in aws cli

# Simple run through
Automatically create tiup cluster in AWS Singapore region. If you want to switch to a different region, please check [Specify AWS region](#Specify-AWS-region)

## Initialize and create the TiDB cluster 
```bash
# checkout github repository
git clone https://github.com/pingcap/tisample.git
# go to the tiup tool directory
cd tisample/tidb-demo-aws/tiup
# run terraform commands to spin up AWS resources
terraform init
terraform apply
```
You should see similar results as below after successfully applied
```bash
Apply complete! Resources: 127 added, 0 changed, 0 destroyed.

Outputs:

jump_ssh_login = "ssh -i ~/.ssh/tidb_demo centos@54.254.7.252"
mysql_command = "mysql -h tidb-lb-d38b8b313db96d5f.elb.ap-southeast-1.amazonaws.com -P 4000 -u root"
tidb_dashboard_url = "http://ec2-13-229-130-6.ap-southeast-1.compute.amazonaws.com:2379/dashboard"
tidb_grafana_url = "http://ec2-13-229-130-6.ap-southeast-1.compute.amazonaws.com:3000"
```

## Verify the installation
```bash
# login to jump server
# NOTE: you can copy paste the value of "jump_ssh_login" from the terraform apply output 
ssh -i ~/.ssh/tidb_demo centos@<jump server address>

# login to mysql console from the jump server
# NOTE: you can copy paste the value of "mysql_command" from the terraform apply output
mysql -h <tidb nlb host name> -P 4000 -u root
```

You can also access TiDB grafana and dashboard through the output URLs.


## Cleanup
```bash
# go back to the local machine, and go to the tioperator dir
# run destroy
terraform destroy
```

# Advanced configurations
You can configure terraform local variables to adjust tidb cluster setup.

For all [configurations supported](#Supported-Configurations), there are 2 ways to change the configuration.
1. This can be done by updating the [variables.tf](./variables.tf) file
2. Specify in terraform commands e.g.
```bash
terraform apply -var "region=us-east-1"
```
## Supported Configurations
### Specify AWS region 
- description: spin up tiup cluster in the specified AWS region
- variable name: region
- default value: ap-southeast-1 

### AMI
- description: AMI map used for EC2 instances creation
- variable name: ami_id
- default value: official centos 7.9 [AMI list](https://wiki.centos.org/Cloud/AWS)
- note: Change only when you want to specify a working AMI other than official centos 7.9
   
### Instance types
- description: EC2 instance types used for jump, tidb, tikv and tiflash 
- variable name: {jump,tidb,tikv,tiflash,pd}_instance_type
- default value: jump=c5.large, tidb=c5.large, tikv=r5.large, tiflash=m5.large, pd=m5.large

### Instance disk size 
- description: EC2 instance EBS disk size(in G) used for jump, tidb, tikv and tiflash
- variable name: {jump,tidb,tikv,tiflash,pd}_instance_disk_size
- default value: 20 

### TiKV IOPS 
- description: EBS IOPS for tikv node 
- variable name: tikv_ebs_iops 
- default value: 3000 

### TiKV Throughput
- description: EBS throughput for tikv node (in MBs)
- variable name: tikv_ebs_throughput 
- default value: 125  

### Number of instances 
- description: number of EC2 instances in tidb, tikv and tiflash group
- variable name: {tidb,tikv,tiflash,pd}_instance_number
- default value: pd=3, tidb=1, tikv=3, tiflash=0 

### Number of instances to scale out 
- description: number of EC2 instances in tidb, tikv and tiflash group to scale out. for the demo of scale out capability of TiDB. Set the numbers to 0 if you don't need to scale out.
- variable name: {tidb,tikv,tiflash}_instance_number_scaleout
- default value: 0 

### Tiup configuration path 
- description: path of the tiup configuration template, relative to tidb-demo-aws dir
- variable name: tiup_config_path
- default value:  tiup/files/deploy.yml.template
- note: You can write your own tidb deploy.yml, in order to tweak the detailed tidb configurations

# Known limitations
- This terraform only works with aws regions with at least 3 AZ, please change the code if your region has less than 3 AZ
- This demo give PD public network access, this is not recommended in production environment. Please set up reverse proxy and apply [security best practices](https://docs.pingcap.com/tidb/stable/dashboard-ops-reverse-proxy)
- Only EBS is supported for now, i3 instances are not supported.