Documentation > Deployment > Automatic Deployment on Amazon EC2
H-Store includes an automatic deployment script for Amazon EC2 based on Fabric and Boto. This script will allow you to easily deploy, configure, and tear down multiple nodes in an cluster and run the benchmarks included with H-Store. At a high-level, the deployment script will create a cluster with a shared NFS directory. This is the easiest and most reliable way to get H-Store up and running to perform tests and experiments.
Dependencies
Note that you do not need to install Fabric or Boto because the proper versions are included in the H-Store third_party directory.
Source Code
The source code for the Fabric deployment script available in the H-Store repository:
https://github.com/apavlo/h-store/blob/master/scripts/fabfile.py
Local Environment Setup
- If you do not have Fabric installed locally on your machine, add an alias to the fab executable in the H-Store repository directory in your .bashrc file:
alias fab='$HSTORE_HOME/tools/fab'
- You first must create an EC2 keypair for H-Store. These keys are generated using Amazon’s online console and not using ssh-keygen on your local machine. Save these two files as $HOME/.ssh/hstore.pem and $HOME/.ssh/hstore.pem.pub.
- Optional: You can add your access keys to your environment for Boto to use. This will allow you to securely connect to the EC2 web services. Add the following to lines to your $HOME/.bash_profile file. The deployment script will look for these parameters in your environment at run time.
export AWS_ACCESS_KEY_ID='XXXXXXXXXXXXXXXXXXXX' export AWS_SECRET_ACCESS_KEY='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
Execution
The quickest way to automatically deploy H-Store on EC2, execute the built-in OLTP benchmarks, and shutdown the cluster is to execute the following command:
fab start_cluster benchmark stop_cluster |
| Fabric Target | Arguments | Description |
|---|---|---|
| start_cluster | None | This is the main entry point to deploy a new H-Store cluster. The script will look to see whether there are any existing H-Store created instancs already running or stopped (e.g., if the instances’ name begins with “hstore-“). Otherwise, it will create new instances using the type defined in the ec2.ami parameter using the AMI defined in the ec2.ami parameter. |
| benchmark | None | Execute all of the benchmarks using the cluster started by start_cluster. |
| exec_benchmark |
project json=<boolean> |
Execute a single benchmark using the cluster started by start_cluster. The host that will execute the BenchmarkController framework must also be specified. If the json argument is set to true, then the BenchmarkController will print out the final benchmark execution results in a easily parsable JSON format. |
| deploy_hstore | None | Pull down the latest version of H-Store from Subversion and invoke build to compile the source code. If hstore.clean is set to true, then this task will invoke clean-all before compiling. |
| stop_cluster | terminate=<boolean> | Stop all the instances in the H-Store cluster. If terminate is set to true, then all of the instances will be terminated. |
| get_version | None | Get the current Git commit id and date of the deployed version of H-Store database system on the EC2 nodes. |
Configuration
Fabric supports a simple configuration file that allows you to override the default options. The table below lists the configuration parameters that are available to you. For example, to create a 32-partition cluster with 8 partitions assigned instance, one would use the following commands:
echo "ec2.site_type = c1.xlarge" >> hstore.fabric echo "site.count = 4" >> hstore.fabric echo "site.partitions_per_site = 8" >> hstore.fabric fab -c hstore.fabric start_cluster benchmark |
| Name | Default | Description |
|---|---|---|
| ec2.site_type | m1.xlarge | The Amazon EC2 instance type that will be used when creating each HStoreSite node in the H-Store cluster. |
| ec2.client_type | m1.xlarge | The Amazon EC2 instance type that will be used when creating each BenchmarkController client in the benchmark run. |
| ec2.ami | ami-63be790a | |
| ec2.security_group | hstore | The name of the EC2 security group to assign each of the instances to. If this security does not exist, the deployment script will create it for you. By default, this security will block all incoming connections from outside of EC2 except for SSH. Each internal node will be allowed to connect to any other internal node on any port. |
| ec2.keypair | $HOME/.ssh/hstore.pem | The name of the EC2 keypair to use for each of the deployed instances. |
| ec2.region | us-east-1b | The instance region to deploy new instances. It is recommended that all of the instances remain are in the same region to improve throughput. |
| ec2.access_key_id | $AWS_ACCESS_KEY_ID | The Amazon Access Key ID used to access EC2 services. If none is specified, the value in your AWS_ACCESS_KEY_ID environmental variable is used. See Boto documentation on connections. |
| ec2.secret_access_key | $AWS_SECRET_ACCESS_KEY | The Amazon Secret Access Key used to access EC2 services. If none is specified, the value in your AWS_SECRET_ACCESS_KEY environmental variable is used. See Boto documentation on connections. |
| ec2.force_reboot | True | By default, the start_cluster task will always reboot any instance that was already running when it deploys the cluster. If this parameter is set to false, then the script will only reboot any instance that only needs to be restarted (e.g., if it needs to change its |
| ec2.cluster_group | None | If this value is given, all of the instances used by the deployment script will be allocated in a virtual cluster group. Each instance in the cluster will be tagged with the value of this parameter. This option allows you to execute multiple clusters concurrently under a single AWS account. |
| hstore.git | git://github.com/apavlo/h-store.git | The URL to the Subversion branch that will be used to retrieve the H-Store source code and execute the benchmarks. |
| hstore.git_branch | master | The Git branch to check-out when deploying H-Store. |
| hstore.git_options | The Git command-line options to use when pulling down the source code from H-Store repository path defined in the hstore.git parameter. | |
| hstore.clean | false | If set to true, the deployment script will execute clean-all before executing the benchmarks. |
| hstore.exec_prefix | compile | The ant targets to execute before invoking hstore-benchmark in the exec_benchmark task. |
One can also override any of the H-Store configuration parameters in the Fabric environment configuration. For example, to change the amount of memory allocated per HStoreSite to 8GB, one would using the following commands:
echo "site.memory = 8192" >> hstore.fabric fab -c hstore.fabric start_cluster benchmark |
The deployment script will automatically update the site.memory parameter in the H-Store configuration file.
Known Issues
- There is a known bug in Fabric that causes it to fail if its output is piped through tee for logging:
fab -c hstore.fabric benchmark | tee benchmark.log # Fails!
You can use script command instead to achieve the same basic concept:
script -f benchmark.log -c "fab -c hstore.fabric benchmark" # Works!
- Automatically changing the instance type for an already running instance is currently unsupported.
