ONLamp.com    
 Published on ONLamp.com (http://www.onlamp.com/)
 See this if you're having trouble printing code examples


Creating Applications with Amazon EC2 and S3

by Judith Myerson
05/13/2008

Introduction

To create applications with the Amazon Elastic Compute Cloud (Amazon EC2), you do four things. First you create an Amazon Machine Image (AMI) to package all your software into one image -- your operating system, configuration settings, applications, and libraries. The AMI contains all the information you need to boot instances of your software.

Second, you upload this AMI for storage in the Amazon S3 (Amazon Simple Storage Service) service. Once in the storage, the AMI is available that you can securely access the AMI .Youíll need access to SSH client to talk to the S3.

Third, you register your AMI with Amazon EC2. You will get a unique number (ID) for it.

Fourth you use this AMI ID and the Amazon EC2 web service APIs to run, monitor, and terminate one or more instances of this AMI. We will tell you how to work with the command line tools and Java libraries later in this article. You must have Java version 5 or later installed to use the tools. You pay only for what you use. There is no minimum fee.

Interfaces to the web service APIs for other programming languages, including Perl, Python and Ruby will be available at a future date.

Signing up for Amazon S3 and Amazon E2

If you already have an Amazon S3 account, skip this section. To sign up, go to the Amazon S3 home page.Then in the Signup for AWS block on the upper right corner, click on a hyperlink to signup.

After following online instructions, you submit to create Amazon Web Services account. The AWS then sends you an email about your new account.

In the email you receive, you will be directed to click on an URL. You will find AWS Access Key Identifiers on the web page. Be sure to copy your AWS accountís Access Key ID and Secret Access Key and put them in a secure place. You will need them to bundle you own image.

To sign up your AWS account for the Amazon EC2 service, log into your AWS account and then follow the link to Amazon EC2 in the Infrastructure Services section in the left panel.Click Your Web Services Account button at the upper right corner to bring down a menu of choices. Select ìAWS Access Identifiers.î Go to the ìX.509 Certificateî section and then click the Create New button to create a new certificate or the Upload button to upload your own certificate.

You can only have one certificate associated with your AWS account. You must download your Private Key file, and store it in a secure location. AWS does not store your private key information. You will not be able to download the Private Key file at any other time. If you do not download now or you lose the Private Key file, you will have to create a new certificate and private key.

After downloading your private key file, you must download your certificate file. You will need both files when you set up command-line tools.

Getting the Command Line tools

If you already have the tools, skip this section.

First, get the Command Line tools from the Amazon EC2 Resource Center and then unzip the file.

Second, set the environmental variable to locate the Command Line tools like this:

$ export EC2_HOME=<path-to-tools>

C:\> set EC2_HOME=<path-to-tools>

The variable is set to the path of the directory into which the command line tools were unzipped. The directory is named in the format of ec2-api-tools-A.B-rrrr and contains sub-directories named bin and lib

Third, add the bin subdirectory like this:

$ export PATH=$PATH:$EC2_Home/bin

C:> set PATH=%PATH%;%ec2_HOME%\bin

You need to identify yourself to the command line tools so they know which credentials to use for requests.

First, set the variable EC2_PRIVATE_KEY to reference your private key file like this:

$ export EC2_PRIVATE_KEY=~/.ec2/<your-private-key>

C:> set EC2_PRIVATE_KEY=c:\ec2\<your-private-key>

To find your private key, right click on the file and then click Properties and copy the information. The file ends with the .pem extension.

Second, set the variable EC2_CERT to reference to your X509 certificate. Here is an example:

$ export EC2_CERT=~/.ec2/<your-cert>

C:> set EC2_CERT=c:\ec2\<your-cert>

To find your certificate number, right click on the file and then click Properties and copy the information. The file ends with the .pem extension.

Running one or more instances

Before you begin, make sure you have the following environmental variables correctly set up:

JAVA_HOME

EC2_HOME

EC2_PRIVATE_KEY

EC2_CERT

Step 1: Launching an instance

If you have not found a public AMI and not generated a keypair you need to launch an instance, skip to step 4:

To launch an instance of the AMI ID, type:

PROMPT> ec2-run-instances <ami-identifier> -k gsg keypair

In the output you will get an instance identifier, the value immediately next to the INSTANCE tag, like this:

INSTANCE i-10a64379 ami-5bae4b32 pending gsg-keypair

You use the identifier to manipulate this instance (including terminating it when you are done).

Once you launch an instance, you will be billed per hour for CPU time. If you leave this how-to article any time, make sure you terminate any instance you have started. To terminate the instances go to the Finishing Up section.

It's a good idea to check how the instance is doing. Wait a few minutes and then do the following:

PROMPT> ec2-describe-instances <instance-identifier>

In the output you will see next to the INSTANCE TAG the instance and AMI identifiers and then the instanceís DSN name (hostname). You will see the instance state just before the keypair name read ërunningí indicating the instance has been set up and has started running. Here is a sample output:

INSTANCE i-10a64379 ami-5bae4b32 domU-12-34-31-00-00-05.usma1.compute.amazonaws.com running gsg-keypair

There may be still a short time before the instance is accessible over the network.

Step 2: Authorizing Network Access to Your Instances

Before you reach your instance over the internet, authorize traffic to it like this:

PROMPT> ec2-authorize default -p 22 PROMPT> ec2-authorize default -p 80

The first command authorizes network access instances in your default group on the standard ssh port (22).

The second command opens up the standard http port (80). For details on controlled network security groups, see the Amazon EC2 Developer Guide.

Step 3: Connecting to your instance

Open your web browser and go to the instance hostname indicated in the first step in the output of the ec2-describe-instances. If the website times out, your instance may not have finished starting up yet. Wait a few minutes and then try again.

Login as root and exercise full control over this instance.

PROMPT> ssh -i id_rsa-gsg-keypair root@<instance-host-name>

Your machine may have a different name for the sshcommand or use different command line options. Consult the documentation for your machine.

When you are done, skip to the next section on creating one or more images.

Step 4: Finding an AMI

To run an instance, you must find a suitable AMI to run. At the prompt enter:

PROMPT> ec2-describe-images

This will give you all public and private AMIs.

In the output, look for the line containing the public image identified by the ec2-public-images/getting-started.manifest.xml value in the third column for one of the IMAGE tags. The value in the second column is the AMI ID for the same IMAGE tag.

Step 5: Generating a Keypair

Use a public/private keypair to ensure that only you will have access. One half of this keypair will be embedded into your instance to allow you login securely without a password using the other half of the keypair. Every keypair you generate requires a name, such as gsg-keypair like this:

PROMPT> ec2-add-keypair gsg-keypair

You need to save the private key returned in a local file named id_rsa-gsg-keypair. Make sure you include ------BEGIN RSA PRIVATE KEY------ at the top and ------END RSA PRIVATE KEY----- at the bottom.

If you do not put this file in your current directory, you should specify the full path when using the ssh command.

If you are using OpenSSH, set the permissions of this file so you are the only one who can read it. Here is an example:

$ chmod 600 id_rsa-gsg-keypair; ls -l id_rsa-gsg-keypair

Return to the first step to complete the process.

Creating one or more images.

You can create custom AMIs (private) and use them to launch as many instances as you need. You can take a look at the other public AMIs that are far better suited to basing the new AMIs.

Step 1: Modify an existing image

Modify an image on the main web page by replacing some of the static content with your name to personalize it like this:

# sed -i -e 's/Congratulations!/Congratulations<your-name>!/' /var/www/html/index.html

You can confirm date and time of the file update like this:

# ls -l /var/www/html/index.html

# date

Here is a sample output for the ls command:

-rw-rw-r-- 1 root root 1872 Jun 21 09:33 /var/www/html/index.html

The date and time in the output of the ls command should match the output of the date command.

Step 2: Bundling

Copy your private key to the machine being bundled. You do not need the certificate:

PROMPT> scp -i id_rsa-gsg-keypair <your-private-key> root@<instance-host-name>

Bundle your image using your AWS account ID as your username.

# ec2-bundle-vol -d /mnt -k ~root/<your-private-key> -u <your-AWS-account-id> -s 1536

Confirm all necessary manifest file and image parts are found in the /mnt directory:

# ls -l /mnt/image.*

Step 3: Uploading to Amazon S3

Upload the bundle to S3 like this:

# ec2-upload-bundle -b <your-s3-bucket> -m /mnt/image.manifest.xml -a <aws-access-key-id> -s <aws-secret-access-key>

You will get continuous feedback until the upload has completed.

Step 4: Registering the AMI

You must register with Amazon EC2, so you can locate it and run instances based on it. Do the folowing:

PROMPT> ec2-register <your-s3-bucket> /image.manifest.xml

In the output, you will get an AMI identifier, the value next to the IMAGE tag.

Step 5: Running instances

Run the instances as follows:

PROMPT> ec2-run-instances <ami-identifier>

In the output, you will get an instance identifier, the value next to the INSTANCE tag. Here is a sample output:

INSTANCE i-10a64379 ami-5bae4b32 pending

Finishing up

First, deregister your AMI like this:

PROMPT> ec2-register <ami-identifier>

Second, delete your AMI with the following command:

PROMPT> ec2-delete-bundle -b <your-s3-bucket> -p image -a <aws-access-key-id> -s <aws-secret-access-key>

Third, terminate your instances.

PROMPT> ec2-terminate-instances <instance-identifier>

Wait a few minutes for the instance to terminate because you need to clean up your data. Check on the status of the instance as done in the first step in the Running one or more instances section.

You can also terminate your instances by logging onto the instances with your ssh tool and running the shutdown -h command. If you forgot to include the -h option, you will put your instance into single user mode.

Application examples

Here are two examples - one using a public image and the other using a private image.

Example 1: Using a public image assuming a keypair has been generated

PROMPT> ec2-run-instances <ami-identifier> -k gsg keypair

PROMPT> ec2-describe-instances <instance-identifier>

PROMPT> ec2-authorize default -p 22

PROMPT> ec2-authorize default -p 80

PROMPT> ssh -i id_rsa-gsg-keypair root@<instance-host-name>

Example 2: Creating and using a private image

# sed -i -e 's/Congratulations!/Congratulations<your-name>!/' /var/www/html/index.html

# ls -l /var/www/html/index.html

# date

PROMPT> scp -i id_rsa-gsg-keypair <your-private-key> <instance-host-name>

# ec2-bundle-vol -d /mnt -k ~root/<your-private-key> -u <your-AWS-account-id> -s 1536

# ls -l /mnt/image.*

# ec2-upload-bundle -b <your-s3-bucket> -m /mnt/image.manifest.xml -a <aws-access-key-id> -s <aws-secret-access-key>

PROMPT> ec2-register <your-s3-bucket> /image.manifest.xml

PROMPT> ec2-run-instances <ami-identifier>

PROMPT> ec2-describe-instances <instance-identifier>

PROMPT> ec2-authorize default -p 22

PROMPT> ec2-authorize default -p 80

PROMPT> ssh -i id_rsa-gsg-keypair root@<instance-host-name>

Using PuTTY

PuTTY is a free SSH client for Windows. PuTTY also comes with PuTTYgen, a key generation program, and pscp, a secure copy command line tool.

To convert your private key to PuTTy format, do the following:

Step 1: Launch PuTTYgen and load id_rsa-gsg-keypair (see step 5 in the Running one or more instances section). The private key file must end with a newline character.

Step 2. Save the key as id_rsa-gs-keypair.ppk.

To use SSH with PuTTY, do the following:

Step 3. Run PuTTY and go to Connection -> SSH -> Auth.

Step 4. Under Authentication parameters click on Browse… and select the PuTTY private key file you generated in step 2.

Step 5. Under session fill in your EC2 instance host name or IP address.

Step 6. Click on Open to connect to your EC2 instance.

To use SCP with PuTTY, do the following:

Step 7. Use the scp command to copy the private key and X.509 certificate as shown in step 2 on Creating one or more images section.

Step 8. Run the same command with pscp like this:

C:\> pscp -i id_rsa-gsg-keypair.ppk <your-private-key> <your-certificate> root@<instance host name>

Judith Myerson is a systems architect and engineer. Her areas of interest include enterprise-wide systems, database technologies, network & system administration, security, operating systems, programming, desktop environments, software engineering, web development, and project management. You can contact her at jmyerson@c2040.com


Return to ONLamp.com.

Copyright © 2009 O'Reilly Media, Inc.