PageRenderTime 22ms CodeModel.GetById 15ms app.highlight 4ms RepoModel.GetById 1ms app.codeStats 0ms

/boto-2.5.2/docs/source/ec2_tut.rst

#
ReStructuredText | 90 lines | 66 code | 24 blank | 0 comment | 0 complexity | 0eea157d98a91f5f373b772c2e375356 MD5 | raw file
 1.. _ec2_tut:
 2
 3=======================================
 4An Introduction to boto's EC2 interface
 5=======================================
 6
 7This tutorial focuses on the boto interface to the Elastic Compute Cloud
 8from Amazon Web Services.  This tutorial assumes that you have already
 9downloaded and installed boto.
10
11Creating a Connection
12---------------------
13
14The first step in accessing EC2 is to create a connection to the service.
15There are two ways to do this in boto.  The first is::
16
17    >>> from boto.ec2.connection import EC2Connection
18    >>> conn = EC2Connection('<AWS_ACCESS_KEY_ID>', '<AWS_SECRET_ACCESS_KEY>')
19
20At this point the variable conn will point to an EC2Connection object.  In
21this example, the AWS access key and AWS secret key are passed in to the
22method explicitely.  Alternatively, you can set the boto config environment variables
23and then call the constructor without any arguments, like this::
24
25    >>> conn = EC2Connection()
26
27There is also a shortcut function in the boto package, called connect_ec2
28that may provide a slightly easier means of creating a connection::
29
30    >>> import boto
31    >>> conn = boto.connect_ec2()
32
33In either case, conn will point to an EC2Connection object which we will
34use throughout the remainder of this tutorial.
35
36Launching Instances
37-------------------
38
39Possibly, the most important and common task you'll use EC2 for is to launch,
40stop and terminate instances. In its most primitive form, you can launch an
41instance as follows::
42
43    >>> conn.run_instances('<ami-image-id>')
44    
45This will launch an instance in the specified region with the default parameters.
46You will not be able to SSH into this machine, as it doesn't have a security
47group set. See :doc:`security_groups` for details on creating one.
48
49Now, let's say that you already have a key pair, want a specific type of
50instance, and you have your :doc:`security group <security_groups>` all setup.
51In this case we can use the keyword arguments to accomplish that::
52
53    >>> conn.run_instances(
54            '<ami-image-id>',
55            key_name='myKey',
56            instance_type='c1.xlarge',
57            security_groups=['your-security-group-here'])
58
59The main caveat with the above call is that it is possible to request an
60instance type that is not compatible with the provided AMI (for example, the
61instance was created for a 64-bit instance and you choose a m1.small instance_type).
62For more details on the plethora of possible keyword parameters, be sure to
63check out boto's :doc:`EC2 API reference <ref/ec2>`.
64
65Stopping Instances
66------------------
67Once you have your instances up and running, you might wish to shut them down
68if they're not in use. Please note that this will only de-allocate virtual
69hardware resources (as well as instance store drives), but won't destroy your
70EBS volumes -- this means you'll pay nominal provisioned EBS storage fees
71even if your instance is stopped. To do this, you can do so as follows::
72
73    >>> conn.stop_instances(instance_ids=['instance-id-1','instance-id-2', ...])
74
75This will request a 'graceful' stop of each of the specified instances. If you
76wish to request the equivalent of unplugging your instance(s), simply add
77``force=True`` keyword argument to the call above. Please note that stop
78instance is not allowed with Spot instances.
79
80Terminating Instances
81---------------------
82Once you are completely done with your instance and wish to surrender both
83virtual hardware, root EBS volume and all other underlying components
84you can request instance termination. To do so you can use the call bellow::
85
86    >>> conn.terminate_instances(instance_ids=['instance-id-1','instance-id-2', ...])
87
88Please use with care since once you request termination for an instance there
89is no turning back.
90