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

  1. 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'
  2. 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.
  3. 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.