diff options
Diffstat (limited to 'docs/source/ec2_tut.rst')
| -rw-r--r-- | docs/source/ec2_tut.rst | 118 |
1 files changed, 103 insertions, 15 deletions
diff --git a/docs/source/ec2_tut.rst b/docs/source/ec2_tut.rst index f8614dbe..d9ffe38c 100644 --- a/docs/source/ec2_tut.rst +++ b/docs/source/ec2_tut.rst @@ -12,23 +12,19 @@ Creating a Connection --------------------- The first step in accessing EC2 is to create a connection to the service. -There are two ways to do this in boto. The first is:: +The recommended way of doing this in boto is:: - >>> from boto.ec2.connection import EC2Connection - >>> conn = EC2Connection('<AWS_ACCESS_KEY_ID>', '<AWS_SECRET_ACCESS_KEY>') + >>> import boto.ec2 + >>> conn = boto.ec2.connect_to_region("us-west-2", + ... aws_access_key_id='<aws access key>', + ... aws_secret_access_key='<aws secret key>') -At this point the variable conn will point to an EC2Connection object. In -this example, the AWS access key and AWS secret key are passed in to the -method explicitely. Alternatively, you can set the boto config environment variables -and then call the constructor without any arguments, like this:: +At this point the variable ``conn`` will point to an EC2Connection object. In +this example, the AWS access key and AWS secret key are passed in to the method +explicitly. Alternatively, you can set the boto config environment variables +and then simply specify which region you want as follows:: - >>> conn = EC2Connection() - -There is also a shortcut function in the boto package, called connect_ec2 -that may provide a slightly easier means of creating a connection:: - - >>> import boto - >>> conn = boto.connect_ec2() + >>> conn = boto.ec2.connect_to_region("us-west-2") In either case, conn will point to an EC2Connection object which we will use throughout the remainder of this tutorial. @@ -41,7 +37,7 @@ stop and terminate instances. In its most primitive form, you can launch an instance as follows:: >>> conn.run_instances('<ami-image-id>') - + This will launch an instance in the specified region with the default parameters. You will not be able to SSH into this machine, as it doesn't have a security group set. See :doc:`security_groups` for details on creating one. @@ -88,3 +84,95 @@ you can request instance termination. To do so you can use the call bellow:: Please use with care since once you request termination for an instance there is no turning back. +Checking What Instances Are Running +----------------------------------- +You can also get information on your currently running instances:: + + >>> reservations = conn.get_all_instances() + >>> reservations + [Reservation:r-00000000] + +A reservation corresponds to a command to start instances. You can see what +instances are associated with a reservation:: + + >>> instances = reservations[0].instances + >>> instances + [Instance:i-00000000] + +An instance object allows you get more meta-data available about the instance:: + + >>> inst = instances[0] + >>> inst.instance_type + u'c1.xlarge' + >>> inst.placement + u'us-west-2' + +In this case, we can see that our instance is a c1.xlarge instance in the +`us-west-2` availability zone. + +================================= +Using Elastic Block Storage (EBS) +================================= + + +EBS Basics +---------- + +EBS can be used by EC2 instances for permanent storage. Note that EBS volumes +must be in the same availability zone as the EC2 instance you wish to attach it +to. + +To actually create a volume you will need to specify a few details. The +following example will create a 50GB EBS in one of the `us-west-2` availability +zones:: + + >>> vol = conn.create_volume(50, "us-west-2") + >>> vol + Volume:vol-00000000 + +You can check that the volume is now ready and available:: + + >>> curr_vol = conn.get_all_volumes([vol.id])[0] + >>> curr_vol.status + u'available' + >>> curr_vol.zone + u'us-west-2' + +We can now attach this volume to the EC2 instance we created earlier, making it +available as a new device:: + + >>> conn.attach_volume (vol.id, inst.id, "/dev/sdx") + u'attaching' + +You will now have a new volume attached to your instance. Note that with some +Linux kernels, `/dev/sdx` may get translated to `/dev/xvdx`. This device can +now be used as a normal block device within Linux. + +Working With Snapshots +---------------------- + +Snapshots allow you to make point-in-time snapshots of an EBS volume for future +recovery. Snapshots allow you to create incremental backups, and can also be +used to instantiate multiple new volumes. Snapshots can also be used to move +EBS volumes across availability zones or making backups to S3. + +Creating a snapshot is easy:: + + >>> snapshot = conn.create_snapshot(vol.id, 'My snapshot') + >>> snapshot + Snapshot:snap-00000000 + +Once you have a snapshot, you can create a new volume from it. Volumes are +created lazily from snapshots, which means you can start using such a volume +straight away:: + + >>> new_vol = snapshot.create_volume('us-west-2') + >>> conn.attach_volume (new_vol.id, inst.id, "/dev/sdy") + u'attaching' + +If you no longer need a snapshot, you can also easily delete it:: + + >>> conn.delete_snapshot(snapshot.id) + True + + |