Getting Started with Wakame

Version 0.3 is alpha release to demonstrate how Wakame works. Please note that this version is just for technology preview release.

This document will help you to bring your first Wakame based web cluster up in the EC2 platform. The web cluster consists of four different services:

Load Balancer
Asset Web Server(For static contents)
Application Web Server(For dynamic contents)
Database

Top three services are using the Apache Web Server. The Load Balancer Apache daemon is for handling the initial user's http request and distributing the request to subsidiary web servers. The Load Balancer Apache recognizes the type of http request wheather static content or dynamic content based on the extention of the requested URI (mainly). When the static content is requested, the asset web server will be dispatched the request from the load balancer.

All the other request type will be classified as dynamic so that the application web server will handle those requests. It bundles the Passenger module and is deployed an initial rails project. You will see the famous rails page once everything go well.

Lastly, the database is a MySQL server. The rails application does not have any database connections in this demo but it demonstrats how the MySQL server is setup automatically using an EBS volume.

Prerequisties

To run this middle-ware, you have to get your AWS account ready before trying out. Please follow the steps to setup your AWS account. If you already have the account, make sure that the items below are given from your AWS account page.

Amazon Web Service acesss key & secret key.
pk.pem & cert.pem X.509 Certificate to bundle new AMI image file.
Amazon S3 account and bucket setup to save your modified image.

Bring up the AMI

Once you actived AWS account, the web based management console (AWS Management Console) can be accessible.

Go to "AMIs" tab and look for the public image has the manifest path "wakame/wakame-0.3.1-snapshot20090423.manifest.xml(ami-c25eb9ab)". Click "Launch" button then you will get and see new EC2 instance on the "Instances" tab in your console.

% ssh

Configure AWS Keys

In the same directory (/home/wakame/corelib), set your AWS access information to configuration.rb using text editor.

% sudo vi lib/wakame/configuration.rb

Fillin AWS Access Key ID and Secret Access Key to the bold configuration section. (line 63-64)

    class EC2 < DefaultSet
      def process(config)
        super(config)
        config.config_template_root = File.join(config.root, "config", "template")
        config.config_root = '/home/wakame/config'
        config.vm_manipulation_class = 'Wakame::VmManipulator::EC2'
        config.vm_environment = :EC2

        config.ssh_private_key = '/home/wakame/config/root.id_rsa'

        config.aws_access_key = ''
        config.aws_secret_key = ''
      end
    end

Prepare EC2 Resources (Elastic IP & EBS volume)

To reserve your Elastic IP, the "Elastic IP" tab in AWS console is available. The reserved IP address will be used in the later phase so that take it on your memo.

The EBS volume has to be set up as well. The MySQL instance which will consist of

% cd /home/wakame/corelib
% sudo GEM_HOME=/usr/local/gems /usr/local/gems/bin/rake ec2:mysqlsetupvol
(in /home/wakame/corelib)
/home/wakame/corelib/config/../lib/wakame.rb:26: warning: already initialized constant VERSION
echo 'y' | mkfs.ext3 -q /dev/sdw
/dev/sdw is entire device, not just one partition!
Proceed anyway? (y,n) mount /dev/sdw /mnt/mysql-tmp
/usr/bin/mysql_install_db --datadir=/mnt/mysql-tmp
Installing MySQL system tables...
OK
Filling help tables...
OK

To start mysqld at boot time you have to copy
support-files/mysql.server to the right place for your system

PLEASE REMEMBER TO SET A PASSWORD FOR THE MySQL root USER !
To do so, start the server, then issue the following commands:
/usr/bin/mysqladmin -u root password 'new-password'
/usr/bin/mysqladmin -u root -h domU-12-31-38-00-51-D8.compute-1.internal password 'new-password'

Alternatively you can run:
/usr/bin/mysql_secure_installation

which will also give you the option of removing the test
databases and anonymous user created by default.  This is
strongly recommended for production servers.

See the manual for more instructions.

You can start the MySQL daemon with:
cd /usr ; /usr/bin/mysqld_safe &

You can test the MySQL daemon with mysql-test-run.pl
cd mysql-test ; perl mysql-test-run.pl

Please report any problems with the /usr/bin/mysqlbug script!

The latest information about MySQL is available on the web at
http://www.mysql.com
Support MySQL by buying support/licenses at http://shop.mysql.com
umount /mnt/mysql-tmp
Initialized EBS Volume: vol-bc20c3d5

Set Resource Values

Put the Elastic IP and EBS volume ID which you acquire in service.rb.

% cd /home/wakame/corelib
% sudo vi lib/wakame/service.rb


    class Apache_LB < Property
      include WebCluster::HttpLoadBalanceServer
      include ApacheBasicProps

      attr_reader :elastic_ip

      def initialize
        super()
        @listen_port = 80
        @listen_port_https = 443
        @template = ConfigurationTemplate::ApacheTemplate.new(:lb)
        @elastic_ip = '174.12.2.202'
      end

    class MySQL_Master < Property
      attr_reader :basedir, :mysqld_datadir, :mysqld_log_bin, :ebs_volume, :ebs_device

      def initialize
        super()
        @template = ConfigurationTemplate::MySQLTemplate.new()
        @basedir = '/home/wakame/mysql'

        @mysqld_datadir = File.expand_path('data', @basedir)
        @mysqld_log_bin = File.expand_path('mysql-bin.log', @mysqld_datadir)
        @ebs_volume = 'vol-6e280fc7'
        @ebs_device = '/dev/sdd'
        @ebs_mount_option = 'noatime'

        @duplicable = false
      end

Restart wakame-master

Restart the wakame-master process once you modified configuration.rb and service.rb in /home/wakame/corelib/lib.

% sudo /etc/init.d/wakame-master restart
% sudo /etc/init.d/wakame-agent restart

Run wakameadm

"wakameadm" is the commandline interface for running wakame-master process. It communicates to the wakame-master process through DRb protocol.

"status" sub command

% /home/wakame/corelib/bin/wakameadm status
Cluster : Wakame::Service::WebCluster (0)
  Wakame::Service::Apache_LB : 
  Wakame::Service::Apache_WWW : 
  Wakame::Service::Apache_APP : 
  Wakame::Service::MySQL_Master : 

Agents :
  i-22afc74b : 10.252.86.38, 75.101.169.123 load=0.0, 10 sec(s) (1)

"launch_cluster" sub command

% /home/wakame/corelib/bin/wakameadm launch_cluster
% /home/wakame/corelib/bin/wakameadm status
Cluster : Wakame::Service::WebCluster (1)
  Wakame::Service::Apache_LB : 
     b958a8739063e8dacd703b442c555874812b233e (ONLINE)
  Wakame::Service::Apache_WWW : 
     30d7d53c3a5d5838f617a541d0ae13b82d894460 (ONLINE)
  Wakame::Service::Apache_APP : 
     d8dc7be3dbfdd92fc2f52fef0564f12db689dee6 (ONLINE)
  Wakame::Service::MySQL_Master : 
     610a6ff148fe4f2ee1097d5ec8200735d3586f27 (ONLINE)

Instances :
  610a6ff148fe4f2ee1097d5ec8200735d3586f27 : Wakame::Service::MySQL_Master (ONLINE)
    On VM instance: i-22afc74b
  d8dc7be3dbfdd92fc2f52fef0564f12db689dee6 : Wakame::Service::Apache_APP (ONLINE)
    On VM instance: i-22afc74b
  30d7d53c3a5d5838f617a541d0ae13b82d894460 : Wakame::Service::Apache_WWW (ONLINE)
    On VM instance: i-22afc74b
  b958a8739063e8dacd703b442c555874812b233e : Wakame::Service::Apache_LB (ONLINE)
    On VM instance: i-22afc74b

Agents :
  i-22afc74b : 10.252.86.38, 75.101.169.123 load=0.62, 4 sec(s) (1)
    Services (4): Wakame::Service::MySQL_Master, Wakame::Service::Apache_APP, Wakame::Service::Apache_WWW, Wakame::Service::Apache_LB

Your ssh connection will be lost once the Load Balancer process started up successfully. Because the Elastic IP will be mapped to your instance's public IP and old public IP will back to EC2's IP pool. So you have to reconnect to your instance with the Elastic IP.

% ssh ubuntu@174.12.2.202

"propagate_service" sub command

"propagate_service" sub command is for making copy of the exising service. When you specify Wakame::Service::Apache_WWW or Wakame::Service::Apache_APP service, you will get new

% /home/wakame/corelib/bin/wakameadm propagate_service Wakame::Service::Apache_WWW
% /home/wakame/corelib/bin/wakameadm status
Cluster : Wakame::Service::WebCluster (1)
  Wakame::Service::Apache_LB : 
     0d0d698a39d9b6c3817f3a2542838151cf252a36 (ONLINE)
  Wakame::Service::Apache_WWW : 
     8a2085806d4938c56309129aaa1a40b805e0f79b (ONLINE)
     182aa5d460756fbb0165053ba1ea1ffc1b3d4a98 (ONLINE)
  Wakame::Service::Apache_APP : 
     f2192e979dc275b9d716dccdd9fdafeba0b30674 (ONLINE)
  Wakame::Service::MySQL_Master : 
     44549b2c2dd77072df048967ec0583ad3e339083 (ONLINE)

Instances :
  8a2085806d4938c56309129aaa1a40b805e0f79b : Wakame::Service::Apache_WWW (ONLINE)
    On VM instance: i-9789e1fe
  44549b2c2dd77072df048967ec0583ad3e339083 : Wakame::Service::MySQL_Master (ONLINE)
    On VM instance: i-22afc74b
  182aa5d460756fbb0165053ba1ea1ffc1b3d4a98 : Wakame::Service::Apache_WWW (ONLINE)
    On VM instance: i-22afc74b
  f2192e979dc275b9d716dccdd9fdafeba0b30674 : Wakame::Service::Apache_APP (ONLINE)
    On VM instance: i-22afc74b
  0d0d698a39d9b6c3817f3a2542838151cf252a36 : Wakame::Service::Apache_LB (ONLINE)
    On VM instance: i-22afc74b

Agents :
  i-22afc74b : 10.252.86.38, 174.129.221.12 load=0.02, 3 sec(s) (1)
    Services (4): Wakame::Service::MySQL_Master, Wakame::Service::Apache_WWW, Wakame::Service::Apache_APP, Wakame::Service::Apache_LB
  i-9789e1fe : 10.249.70.6, 174.129.98.233 load=0.06, 9 sec(s) (1)
    Services (1): Wakame::Service::Apache_WWW

"migrate_service" sub command

"migrate_service" sub command moves the running service to another EC2 instance.

% /home/wakame/corelib/bin/wakameadm migrate_service f2192e979dc275b9d716dccdd9fdafeba0b30674
% /home/wakame/corelib/bin/wakameadm status
Cluster : Wakame::Service::WebCluster (1)
  Wakame::Service::Apache_LB : 
     0d0d698a39d9b6c3817f3a2542838151cf252a36 (ONLINE)
  Wakame::Service::Apache_WWW : 
     8a2085806d4938c56309129aaa1a40b805e0f79b (ONLINE)
     182aa5d460756fbb0165053ba1ea1ffc1b3d4a98 (ONLINE)
  Wakame::Service::Apache_APP : 
     f89e6d4271d5fd414e61b234b2f4253c3546bb53 (Offline)
     f2192e979dc275b9d716dccdd9fdafeba0b30674 (Migrating...)
  Wakame::Service::MySQL_Master : 
     44549b2c2dd77072df048967ec0583ad3e339083 (ONLINE)

Instances :
  8a2085806d4938c56309129aaa1a40b805e0f79b : Wakame::Service::Apache_WWW (ONLINE)
    On VM instance: i-9789e1fe
  f89e6d4271d5fd414e61b234b2f4253c3546bb53 : Wakame::Service::Apache_APP (Offline)
  44549b2c2dd77072df048967ec0583ad3e339083 : Wakame::Service::MySQL_Master (ONLINE)
    On VM instance: i-22afc74b
  182aa5d460756fbb0165053ba1ea1ffc1b3d4a98 : Wakame::Service::Apache_WWW (ONLINE)
    On VM instance: i-22afc74b
  f2192e979dc275b9d716dccdd9fdafeba0b30674 : Wakame::Service::Apache_APP (Migrating...)
    On VM instance: i-22afc74b
  0d0d698a39d9b6c3817f3a2542838151cf252a36 : Wakame::Service::Apache_LB (ONLINE)
    On VM instance: i-22afc74b

Agents :
  i-22afc74b : 10.252.86.38, 174.129.221.12 load=0.72, 3 sec(s) (1)
    Services (4): Wakame::Service::MySQL_Master, Wakame::Service::Apache_WWW, Wakame::Service::Apache_APP, Wakame::Service::Apache_LB
  i-9789e1fe : 10.249.70.6, 174.129.98.233 load=0.0, 0 sec(s) (1)
    Services (1): Wakame::Service::Apache_WWW

This shows the result the migrated Apache_APP service to new EC2 instance.

Cluster : Wakame::Service::WebCluster (2)
  Wakame::Service::Apache_LB : 
     0d0d698a39d9b6c3817f3a2542838151cf252a36 (ONLINE)
  Wakame::Service::Apache_WWW : 
     8a2085806d4938c56309129aaa1a40b805e0f79b (ONLINE)
     182aa5d460756fbb0165053ba1ea1ffc1b3d4a98 (ONLINE)
  Wakame::Service::Apache_APP : 
     f89e6d4271d5fd414e61b234b2f4253c3546bb53 (ONLINE)
  Wakame::Service::MySQL_Master : 
     44549b2c2dd77072df048967ec0583ad3e339083 (ONLINE)

Instances :
  8a2085806d4938c56309129aaa1a40b805e0f79b : Wakame::Service::Apache_WWW (ONLINE)
    On VM instance: i-9789e1fe
  f89e6d4271d5fd414e61b234b2f4253c3546bb53 : Wakame::Service::Apache_APP (ONLINE)
    On VM instance: i-ae8ae2c7
  44549b2c2dd77072df048967ec0583ad3e339083 : Wakame::Service::MySQL_Master (ONLINE)
    On VM instance: i-22afc74b
  182aa5d460756fbb0165053ba1ea1ffc1b3d4a98 : Wakame::Service::Apache_WWW (ONLINE)
    On VM instance: i-22afc74b
  0d0d698a39d9b6c3817f3a2542838151cf252a36 : Wakame::Service::Apache_LB (ONLINE)
    On VM instance: i-22afc74b

Agents :
  i-22afc74b : 10.252.86.38, 174.129.221.12 load=0.11, 7 sec(s) (1)
    Services (3): Wakame::Service::MySQL_Master, Wakame::Service::Apache_WWW, Wakame::Service::Apache_LB
  i-9789e1fe : 10.249.70.6, 174.129.98.233 load=0.0, 4 sec(s) (1)
    Services (1): Wakame::Service::Apache_WWW
  i-ae8ae2c7 : 10.254.226.51, 75.101.206.164 load=0.41, 6 sec(s) (1)
    Services (1): Wakame::Service::Apache_APP

"shutdown_cluster" sub command

"shutdown_cluster" sub command will let belong services and EC2 instances terminate. The status display will back to original at the point of launching the cluster.

% /home/wakame/corelib/bin/wakameadm shutdown_cluster
% /home/wakame/corelib/bin/wakameadm status
Cluster : Wakame::Service::WebCluster (0)
  Wakame::Service::Apache_LB : 
  Wakame::Service::Apache_WWW : 
  Wakame::Service::Apache_APP : 
  Wakame::Service::MySQL_Master : 

Agents :
  i-22afc74b : 10.252.86.38, 75.101.169.123 load=0.0, 10 sec(s) (1)

Save the current instance as your AMI (Optional)

As you know, an EC2 instance is stateless virtual machine. All the changes which you have applied so far when you shutdown the instance. If you want to keep the current image and activated Amazon S3 access, a rake task is supplied to save the running instance with new AMI ID.

% cd /home/wakame/corelib
% sudo GEM_HOME=/usr/local/gems /usr/local/gems/bin/rake ec2:bundle[yourbucket/yourimg.manifest.xml]

New AMI ID for wakame/wakame-0.3-snapshot20090422.manifest.xml: ami-e851b681