[cloud-guide] Finish filling in the EC2 section with content from Garrett Holmstrom
Jared Smith
jsmith at fedoraproject.org
Thu Nov 3 17:51:05 UTC 2011
commit 6c34dfdcafe9607e98b3b1e052554b1901fb256e
Author: Jared K. Smith <jsmith at fedoraproject.org>
Date: Tue Nov 1 18:15:40 2011 +0530
Finish filling in the EC2 section with content from Garrett Holmstrom
en-US/AmazonEC2.xml | 208 ++++++++++++++++++++++++++++++++++++++++++++++++++-
1 files changed, 204 insertions(+), 4 deletions(-)
---
diff --git a/en-US/AmazonEC2.xml b/en-US/AmazonEC2.xml
index c95a467..6b11b2a 100644
--- a/en-US/AmazonEC2.xml
+++ b/en-US/AmazonEC2.xml
@@ -259,15 +259,13 @@ beside it. Both of them should be long sets of alphanumeric characters.
Create a file called <filename>.iamrc</filename> in your home directory that
contains those keys in this format:</para>
-<programlisting>
-AWSAccessKeyId=<replaceable>your_access_key_id</replaceable>
+<programlisting format="linespecific">AWSAccessKeyId=<replaceable>your_access_key_id</replaceable>
AWSSecretKey=<replaceable>your_secret_key</replaceable>
</programlisting>
<para>Since euca2ools is designed to work with all AWS-compatible clouds, not just AWS itself, it needs to know which cloud to contact. Create a file called <filename>.eucarc</filename> in your home directory with the following content to point it toward AWS:</para>
-<programlisting>
-export AWS_CREDENTIAL_FILE=~/.iamrc
+<programlisting>export AWS_CREDENTIAL_FILE=~/.iamrc
export EC2_URL=https://ec2.amazonaws.com/
export S3_URL=https://s3.amazonaws.com/
export EUARE_URL=https://iam.amazonaws.com/
@@ -281,7 +279,209 @@ export AWS_SECRET_ACCESS_KEY=$AWSSecretKey
<para>Finally, add these settings to your shell's environment by running: <command><prompt>$ </prompt>source ~/.eucarc</command></para>
+ <section>
+ <title>Installing the euca2ools package</title>
+ <para>Installing the <application>euca2ools</application> package is simple. To do so with yum, run the following command as the <literal>root</literal> user: <command><prompt># </prompt>yum install euca2ools</command></para>
+ <!-- Perhaps consider adding some information about checking your euca2ools installation? -->
+ </section>
+ <section>
+ <title>Choosing your EC2 region</title>
+ <para>Next, choose an EC2 region to use. Things to consider when choosing a region include its geographic location, the pricing for instances in that region, and whether the image you wish to use is available in that region. You can get a list of regions by running the <command>euca-describe-regions</command>, which results in a list such as this:</para>
+
+<screen>REGION eu-west-1 ec2.eu-west-1.amazonaws.com
+REGION us-east-1 ec2.us-east-1.amazonaws.com
+REGION ap-northeast-1 ec2.ap-northeast-1.amazonaws.com
+REGION us-west-1 ec2.us-west-1.amazonaws.com
+REGION ap-southeast-1 ec2.ap-southeast-1.amazonaws.com
+</screen>
+
+ <para>When you choose an EC2 region you can make euca2ools start using it by editing the line that contains <literal>EC2_URL</literal> in your <filename>.eucarc</filename> file. For example:</para>
+
+ <programlisting>export EC2_URL=https://ec2.us-east-1.amazonaws.com/</programlisting>
+
+ <para>After adjusting the region in the <filename>.eucarc</filename> file, reset the settings in your shell's environment by running this command: <command><prompt>$ </prompt>source ~/.eucarc</command></para>
+ </section>
+ <section>
+ <title>Creating a key pair</title>
+ <para>The primary way of logging into Fedora instances running in EC2 is via <application>SSH</application>. Since Fedora instances have no passwords, you need a SSH <emphasis>key pair</emphasis> to log in to them. The private half of this key pair is stored on your computer, while the public half is stored in EC2 so instances can download them as they start. This allows you to securely log into your instances without a password.</para>
+
+ <para>You can have multiple key pairs. Each key pair has its own name. Key pairs are specific to each EC2 region.</para>
+
+ <para>Choose a name for a new key pair and then use the <command>euca-add-keypair</command> command to create it and write the private key to a file. Be sure to choose a name that is easy to remember. To create your new key pair, run the following command, replacing <replaceable>mykey</replaceable> with a memorable name:</para>
+<screen><command><prompt>$ </prompt>euca-add-keypair <replaceable>mykey</replaceable> > <replaceable>mykey</replaceable>.pem</command></screen>
+
+ <important>
+ <title>Key pairs are irreplaceable</title>
+ <para>EC2 does not store the private halves of key pairs. The time you run <command>euca-add-keypair</command> is the only chance you will have to save a copy of the private key. There is no way to recover a lost private key from EC2.</para>
+ </important>
+
+ <para>You can use <code>euca-describe-keypairs</code> to display a list of your keypairs.</para>
+
+<screen><command><prompt>$ </prompt>euca-describe-keypairs</command>
+KEYPAIR mykey1 7b:9b:33:cf:bf:12:4d:62:b6:7c:fa:02:f2:f7:bc:59:e3:7e:40:fb
+KEYPAIR mykey2 f9:93:1e:73:4b:2e:c1:0d:7f:79:e1:bc:c0:d0:7c:95:32:55:b7:dd
+</screen>
+
+ <para>You can use <command>euca-delete-keypairs</command> to delete a keypair. Deleting a keypair does not remove it from instances that are already running; it merely prevents new instances from using it. </para>
+
+<screen><command><prompt>$ </prompt>euca-delete-keypair <replaceable>mykey1</replaceable></command></screen>
+
+ </section>
+ <section>
+ <title>Setting up a security group</title>
+ <para>Each security group has its own set of firewall rules. While this tutorial uses the <literal>default</literal> security group that EC2 provides for you, you can also create your own security groups.</para>
+
+ <para>The <command>euca-authorize</command> command lets you tell EC2 to allow traffic from ranges of IP addresses and ports into a security group. To allow access to SSH (TCP port <literal>22</literal>) running on instances in the <literal>default</literal> security group, run the following command replacing <replaceable>1.2.3.4</replaceable> with the IP address from which you will connect to your EC2 instances.</para>
+<screen><command><prompt>$ </prompt>euca-authorize default -p 22 -s <replaceable>1.2.3.4/32</replaceable></command></screen>
+
+ <para>If you do not specify a range of IP addresses then the port(s) you choose will be open to the entire Internet. For example, the following command allows SSH access from any machine, not just your computer:</para>
+<screen><command><prompt>$ </prompt>euca-authorize default -p 22</command></screen>
+
+ <para>To allow pings and other ICMP traffic you can run:</para>
+<screen><command><prompt>$ </prompt>euca-authorize default -P icmp</command></screen>
+
+ <para>The opposite of <command>euca-authorize</command> is <command>euca-revoke</command>. You can use <command>euca-describe-groups</command> to obtain a list of security groups and the firewall permissions you have applied to them.</para>
+ </section>
</section>
+ <section>
+ <title>Running EC2 Instances</title>
+ <para>Now that our preparation work is done, we can start running EC2 instances.</para>
+ <section>
+ <title>Choosing an image</title>
+ <para>The Cloud SIG maintains an <ulink url="http://fedoraproject.org/wiki/Cloud_SIG/EC2_Images">index of machine images published by Fedora</ulink>. While all of the images for a given release behave the same, they differ by architecture, EC2 region, and where the root filesystem is stored (that is, instance store or EBS). Choose the image that is most appropriate for you and note its ID, which begins with <literal>ami</literal>.</para>
+ </section>
+ <section>
+ <title>Choosing an instance type</title>
+ <para>Amazon offers several instance types, which are <ulink url="http://aws.amazon.com/ec2/instance-types/">detailed on the EC2 web site</ulink>. As of the time of writing, the smallest and cheapest instance types are <literal>m1.small</literal> and <literal>t1.micro</literal>, though each of those carries a restriction: <literal>m1.small</literal> instances must use the i386 architecture. <literal>t1.micro</literal> instances have no instance storage and therefore must boot from EBS. If the image you choose fits neither of these criteria or if you simply need more resources than they can provide then you need to use a larger and more expensive instance type.</para>
+ </section>
+ <section>
+ <title>Running an instance</title>
+ <para>You can start a new instance of the image and instance type you chose with <command>euca-run-instances</command>. To be able to log into the new instance, you must also specify the name of the key pair you created earlier. For example, to run a <literal>t1.micro</literal> instance of the image <literal>ami-7f5a063a</literal> with a key pair named <literal>mykey</literal>, run the following command:</para>
+<screen><command><prompt>$ </prompt>euca-run-instances ami-7f5a063a -t t1.micro -k mykey</command>
+RESERVATION r-4d5ea00a 0123456789ab default
+INSTANCE i-910fbbd6 ami-7f5a063a pending 0 mykey t1.micro 2011-10-11T00:00:00.000Z us-east-1c aki-9ba0f1de
+</screen>
+
+ <para>The output of <command>euca-run-instances</command> contains the ID of the instance you just started. In the example above, the instance's ID is <literal>i-910fbbd6</literal>. You will need this ID to use tools that need to refer to the instance.</para>
+
+ <para>The instance starts in the <literal>pending</literal> state. When it finished booting it changes to the <literal>running</literal> state. When you terminate it it changes to the <literal>shutting-down</literal> and finally <literal>terminated</literal> states.</para>
+ </section>
+ <section>
+ <title>Logging into an instance</title>
+ <para>As the instance starts it obtains an IP address from EC2 and changes to the <literal>running</literal> state. You can check on your instances by running <literal>euca-describe-instances</literal>, optionally with the ID of the instance in question. When the instance is ready (or nearly ready) to use, <command>euca-describe-instances</command> will display the address you can use to log into it:</para>
+
+<screen><command><prompt>$ </prompt>euca-describe-instances</command>
+RESERVATION r-4d5ea00a 0123456789ab default
+INSTANCE i-910fbbd6 ami-7f5a063a ec2-204-236-168-22.us-east-1.compute.amazonaws.com ip-10-170-15-23.us-east-1.compute.internal running 0 mykey t1.micro 2011-10-11T00:00:00.000Z us-east-1c aki-9ba0f1de
+</screen>
+
+ <para>The public address of the instance in this example is <literal>ec2-204-236-168-22.us-east-1.compute.amazonaws.com</literal>. Other useful bits of information from this command include the availability zone in which the instance is running (<literal>us-east-1c</literal> in this case) and the time that the instance started.</para>
+ <para>Once the instance is <literal>running</literal> you can log into it with <command>ssh</command>. On Fedora's images you should log in as the user <literal>ec2-user</literal>:</para>
+<screen><command><prompt>$ </prompt>ssh -i mykey.pem ec2-user at ec2-204-236-168-22.us-east-1.compute.amazonaws.com</command>
+<command><prompt>[ec2-user at i-910fbbd6 ~]$ </prompt>cat /etc/fedora-release</command>
+Fedora release 16 (Verne)
+</screen>
+
+ <para>You can now use the instance as you would use any other computer running Fedora.</para>
+ </section>
+ <section>
+ <title>Terminating an instance</title>
+ <para>When you finish using an instance you should terminate it with the <command>euca-terminate-instances</command> command to free up resources and reduce your costs:</para>
+<screen><command><prompt>$ </prompt>euca-terminate-instances <replaceable>i-910fbbd6</replaceable></command></screen>
+ </section>
+ </section>
+ <section>
+ <title>Using Elastic Block Storage (EBS)</title>
+ <section>
+ <title>Managing volumes</title>
+ <para>EBS volumes act like removable disks that you can attach to instances, except you can create and destroy them at will. Each volume is specific to an availability zone. The following section will show you how to use and manage EBS volumes.</para>
+ <section>
+ <title>Creating volumes</title>
+ <para>You can create a volume of nearly any size, in 1 GiB increments. As of the time of writing, the maximum size of a volume is 1 TiB. To create a new, empty volume, choose a size (in GiB) and the availability zone in which to create it and supply those values to <command>euca-create-volume</command>:</para>
+
+<screen><command><prompt>$ </prompt>euca-create-volume -s 10 -z us-east-1c</command>
+VOLUME vol-23ca3542 10 creating 2011-10-11T00:00:00.000Z
+</screen>
+
+ <para>The command's output contains the ID of the newly-created volume. In the example above, the volume's ID is <literal>vol-23ca3542</literal>. You will need this ID to use tools that need to refer to the volume.</para>
+ </section>
+ <section>
+ <title>Describing volumes</title>
+ <para>The <command>euca-describe-volumes</command> will provide a list of all volumes available to you in the entire region in addition to where they are attached:</para>
+<screen><command><prompt>$ </prompt>euca-describe-volumes</command>
+VOLUME vol-23ca3542 10 us-east-1c available 2011-10-11T00:00:00.000Z
+</screen>
+ </section>
+ <section>
+ <title>Using volumes</title>
+ <para>For an instance to make use of a volume you must first <emphasis>attach</emphasis> the volume to the instance. You also need to supply a <emphasis role="strong">device name</emphasis> that the volume should appear as from inside the instance. The device name you choose must be <literal>/dev/sd<replaceable>X</replaceable></literal>, where <replaceable>X</replaceable> is a letter. It will appear inside the instance as either <literal>/dev/sd<replaceable>X</replaceable></literal> or <literal>/dev/xvd<replaceable>X</replaceable></literal>.</para>
+
+<screen><command><prompt>$ </prompt>euca-attach-volume -i i-910fbbd6 -d /dev/sdf vol-23ca3542</command></screen>
+
+ <note>
+ <title>Volumes are zone-specific</title>
+ <para>Each volume exists only within one availability zone. A volume in a given zone can therefore only be attached to instances that are running in the same zone.</para>
+ </note>
+
+ <para>Once you have attached a volume to the instance it will appear as a disk in the instance's /dev directory, ready to be formatted and used.</para>
+<screen><command><prompt>[ec2-user at i-910fbbd6 ~]$ </prompt>mkfs.ext4 /dev/xvdf</command>
+<command><prompt>[ec2-user at i-910fbbd6 ~]$ </prompt>mount /dev/xvdf /mnt</command>
+</screen>
+
+ <para>When you finish using a volume you can unmount it from within the instance and then <emphasis>detach</emphasis> it:</para>
+<screen><command><prompt>[ec2-user at i-910fbbd6 ~]$ </prompt>umount /dev/xvdf</command>
+<command><prompt>[ec2-user at i-910fbbd6 ~]$ </prompt>logout</command>
+<command><prompt>$ </prompt>euca-detach-volume vol-23ca3542</command>
+</screen>
+ </section>
+ <section>
+ <title>Deleting volumes</title>
+ <para>When you finish using an EBS volume you can delete it to free up resources and reduce your costs:</para>
+<screen><command><prompt>$ </prompt>euca-delete-volume vol-23ca3542</command></screen>
+ </section>
+ </section>
+ <section>
+ <title>Using snapshots</title>
+ <para>Volume snapshots provide an easy way to save a backup copy of an entire volume. Unlike a volume, a snapshot is available to all availability zones within a region, which makes snapshots the simplest way to copy a volume between availability zones.</para>
+ <section>
+ <title>Creating a snapshot</title>
+ <para>You can create a snapshot by providing the name of the volume you wish to take a snapshot of to <command>euca-create-snapshot</command>:</para>
+<screen><command><prompt>$ </prompt>euca-create-snapshot vol-23ca3542</command>
+SNAPSHOT snap-00acc96e vol-23ca3542 pending 2011-10-11T00:00:00.000Z
+</screen>
+
+ <para>The command's output contains the ID of the newly-created snapshot. In the example above, the snapshot's ID is <literal>snap-00acc96e</literal>. You will need this ID to use tools that need to refer to the snapshot.</para>
+ <warning>
+ <title>Volumes should not change while creating snapshots</title>
+ <para>Snapshots take time to complete. While a snapshot is in progress, ensure that the contents of the volume do not change to avoid data corruption. You can monitor a snapshot's progress with <command>euca-describe-snapshots</command>.</para>
+ </warning>
+ </section>
+ <section>
+ <title>Describing snapshots</title>
+ <para>The <command>euca-describe-snapshots</command> will provide a list of all snapshots available to you in the region:</para>
+<screen><command><prompt>$ </prompt>euca-describe-snapshots</command>
+SNAPSHOT snap-00acc96e vol-042d3a6a completed 2011-10-12T05:56:29.000Z 100%
+</screen>
+ <note>
+ <title>Dealing with too much output</title>
+ <para>By default, <command>euca-describe-snapshots</command> will list all snapshots that you can access, including those that you do not own. To narrow down the command's output you can supply a list of snapshots to the command or use any of its numerous methods of filtering output.</para>
+ </note>
+ </section>
+ <section>
+ <title>Creating volumes from snapshots</title>
+ <para>To copy the contents of a snapshot to a new volume, run <code>euca-create-volume</code> and specify a snapshot instead of a size:</para>
+<screen><command><prompt>$ </prompt>euca-create-volume --snapshot snap-00acc96e -z us-east-1c</command></screen>
+ <para>You can create multiple volumes from the same snapshot. Each volume will be independent of the others.</para>
+ </section>
+ <section>
+ <title>Deleting snapshots</title>
+ <para>To delete a snapshot, use <code>euca-delete-snapshot</code>. Any volumes created from that snapshot will be unaffected.</para>
+<screen><command><prompt>$ </prompt>euca-delete-snapshot snap-00acc96e</command></screen>
+ </section>
+ </section>
+ </section>
+
+
<!--
<section>
<title>Connecting to EC2 via Amazon's Web Interface</title>
More information about the docs-commits
mailing list