Upgrade gsutil to 3.4

third_party/gsutil/20110627/boto/docs/source/ec2_tut.rst

-.. _ec2_tut:
-
-=======================================
-An Introduction to boto's EC2 interface
-=======================================
-
-This tutorial focuses on the boto interface to the Elastic Compute Cloud
-from Amazon Web Services.  This tutorial assumes that you have already
-downloaded and installed boto.
-
-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:
-
->>> from boto.ec2.connection import EC2Connection
->>> conn = EC2Connection('<aws 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 environment variables:
-
-AWS_ACCESS_KEY_ID - Your AWS Access Key ID
-AWS_SECRET_ACCESS_KEY - Your AWS Secret Access Key
-
-and then call the constructor without any arguments, like this:
-
->>> 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()
-
-In either case, conn will point to an EC2Connection object which we will
-use throughout the remainder of this tutorial.
-
-A Note About Regions
---------------------
-The 2008-12-01 version of the EC2 API introduced the idea of Regions.
-A Region is geographically distinct and is completely isolated from
-other EC2 Regions.  At the time of the launch of the 2008-12-01 API
-there were two available regions, us-east-1 and eu-west-1.  Each
-Region has it's own service endpoint and therefore would require
-it's own EC2Connection object in boto.
-
-The default behavior in boto, as shown above, is to connect you with
-the us-east-1 region which is exactly the same as the behavior prior
-to the introduction of Regions.
-
-However, if you would like to connect to a region other than us-east-1,
-there are a couple of ways to accomplish that.  The first way, is to
-as EC2 to provide a list of currently supported regions.  You can do
-that using the regions function in the boto.ec2 module:
-
->>> import boto.ec2
->>> regions = boto.ec2.regions()
->>> regions
-[RegionInfo:eu-west-1, RegionInfo:us-east-1]
->>> 
-
-As you can see, a list of available regions is returned.  Each region
-is represented by a RegionInfo object.  A RegionInfo object has two
-attributes; a name and an endpoint.
-
->>> eu = regions[0]
->>> eu.name
-u'eu-west-1'
->>> eu.endpoint
-u'eu-west-1.ec2.amazonaws.com'
->>>
-
-You can easily create a connection to a region by using the connect
-method of the RegionInfo object:
-
->>> conn_eu = eu.connect()
->>> conn_eu
-<boto.ec2.connection.EC2Connection instance at 0xccaaa8>
->>> 
-
-The variable conn_eu is now bound to an EC2Connection object connected
-to the endpoint of the eu-west-1 region and all operations performed via
-that connection and all objects created by that connection will be scoped
-to the eu-west-1 region.  You can always tell which region a connection
-is associated with by accessing it's region attribute:
-
->>> conn_eu.region
-RegionInfo:eu-west-1
->>>
-
-Supporting EC2 objects such as SecurityGroups, KeyPairs, Addresses,
-Volumes, Images and SnapShots are local to a particular region.  So
-don't expect to find the security groups you created in the us-east-1
-region to be available in the eu-west-1 region.
-
-Some objects in boto, such as SecurityGroup, have a new method called
-copy_to_region which will attempt to create a copy of the object in
-another region.  For example:
-
->>> regions
-[RegionInfo:eu-west-1, RegionInfo:us-east-1]
->>> conn_us = regions[1].connect()
->>> groups = conn_us.get_all_security_groups()
->>> groups
-[SecurityGroup:alfresco, SecurityGroup:apache, SecurityGroup:vnc,
-SecurityGroup:appserver2, SecurityGroup:FTP, SecurityGroup:webserver,
-SecurityGroup:default, SecurityGroup:test-1228851996]
->>> us_group = groups[0]
->>> us_group
-SecurityGroup:alfresco
->>> us_group.rules
-[IPPermissions:tcp(22-22), IPPermissions:tcp(80-80), IPPermissions:tcp(1445-1445)]
->>> eu_group = us_group.copy_to_region(eu)
->>> eu_group.rules
-[IPPermissions:tcp(22-22), IPPermissions:tcp(80-80), IPPermissions:tcp(1445-1445)]
-
-In the above example, we chose one of the security groups available
-in the us-east-1 region (the group alfresco) and copied that security
-group to the eu-west-1 region.  All of the rules associated with the
-original security group will be copied as well.
-
-If you would like your default region to be something other than
-us-east-1, you can override that default in your boto config file
-(either ~/.boto for personal settings or /etc/boto.cfg for system-wide
-settings).  For example:
-
-[Boto]
-ec2_region_name = eu-west-1
-ec2_region_endpoint = eu-west-1.ec2.amazonaws.com
-
-The above lines added to either boto config file would set the default
-region to be eu-west-1.
-
-Images & Instances
-------------------
-
-An Image object represents an Amazon Machine Image (AMI) which is an
-encrypted machine image stored in Amazon S3.  It contains all of the
-information necessary to boot instances of your software in EC2.
-
-To get a listing of all available Images:
-
->>> images = conn.get_all_images()
->>> images
-[Image:ami-20b65349, Image:ami-22b6534b, Image:ami-23b6534a, Image:ami-25b6534c, Image:ami-26b6534f, Image:ami-2bb65342, Image:ami-78b15411, Image:ami-a4aa4fcd, Image:ami-c3b550aa, Image:ami-e4b6538d, Image:ami-f1b05598]
->>> for image in images:
-...    print image.location
-ec2-public-images/fedora-core4-base.manifest.xml
-ec2-public-images/fedora-core4-mysql.manifest.xml
-ec2-public-images/fedora-core4-apache.manifest.xml
-ec2-public-images/fedora-core4-apache-mysql.manifest.xml
-ec2-public-images/developer-image.manifest.xml
-ec2-public-images/getting-started.manifest.xml
-marcins_cool_public_images/fedora-core-6.manifest.xml
-khaz_fc6_win2003/image.manifest
-aes-images/django.manifest
-marcins_cool_public_images/ubuntu-6.10.manifest.xml
-ckk_public_ec2_images/centos-base-4.4.manifest.xml
-
-The most useful thing you can do with an Image is to actually run it, so let's
-run a new instance of the base Fedora image:
-
->>> image = images[0]
->>> image.location
-ec2-public-images/fedora-core4-base.manifest.xml
->>> reservation = image.run()
-
-This will begin the boot process for a new EC2 instance.  The run method
-returns a Reservation object which represents a collection of instances
-that are all started at the same time.  In this case, we only started one
-but you can check the instances attribute of the Reservation object to see
-all of the instances associated with this reservation:
-
->>> reservation.instances
-[Instance:i-6761850e]
->>> instance = reservation.instances[0]
->>> instance.state
-u'pending'
->>>
-
-So, we have an instance booting up that is still in the pending state.  We
-can call the update method on the instance to get a refreshed view of it's
-state:
-
->>> instance.update()
->>> instance.state
-u'pending'
->>> # wait a few minutes
->>> instance.update()
->>> instance.state
-u'running'
-
-So, now our instance is running.  The time it takes to boot a new instance
-varies based on a number of different factors but usually it takes less than
-five minutes.
-
-Now the instance is up and running you can find out its DNS name like this:
-
->>> instance.dns_name
-u'ec2-72-44-40-153.z-2.compute-1.amazonaws.com'
-
-This provides the public DNS name for your instance.  Since the 2007--3-22
-release of the EC2 service, the default addressing scheme for instances
-uses NAT-addresses which means your instance has both a public IP address and a
-non-routable private IP address.  You can access each of these addresses
-like this:
-
->>> instance.public_dns_name
-u'ec2-72-44-40-153.z-2.compute-1.amazonaws.com'
->>> instance.private_dns_name
-u'domU-12-31-35-00-42-33.z-2.compute-1.internal'
-
-Even though your instance has a public DNS name, you won't be able to
-access it yet because you need to set up some security rules which are
-described later in this tutorial.
-
-Since you are now being charged for that instance we just created, you will
-probably want to know how to terminate the instance, as well.  The simplest
-way is to use the stop method of the Instance object:
-
->>> instance.stop()
->>> instance.update()
->>> instance.state
-u'shutting-down'
->>> # wait a minute
->>> instance.update()
->>> instance.state
-u'terminated'
->>>
-
-When we created our new instance, we didn't pass any args to the run method
-so we got all of the default values.  The full set of possible parameters
-to the run method are:
-
-min_count - The minimum number of instances to launch.
-max_count - The maximum number of instances to launch.
-keypair - Keypair to launch instances with (either a KeyPair object or a string with the name of the desired keypair.
-security_groups - A list of security groups to associate with the instance.  This can either be a list of SecurityGroup objects or a list of strings with the names of the desired security groups.
-user_data - Data to be made available to the launched instances.  This should be base64 encoded according to the EC2 documentation.
-
-So, if I wanted to create two instances of the base image and launch them
-with my keypair, called gsg-keypair, I would to this:
-
->>> reservation.image.run(2,2,'gsg-keypair')
->>> reservation.instances
-[Instance:i-5f618536, Instance:i-5e618537]
->>> for i in reservation.instances:
-...    print i.status
-u'pending'
-u'pending'
->>>
-
-Later, when you are finished with the instances you can either stop each
-individually or you can call the stop_all method on the Reservation object:
-
->>> reservation.stop_all()
->>>
-
-If you just want to get a list of all of your running instances, use
-the get_all_instances method of the connection object.  Note that the
-list returned is actually a list of Reservation objects (which contain
-the Instances) and that the list may include recently terminated instances
-for a small period of time subsequent to their termination.
-
->>> instances = conn.get_all_instances()
->>> instances
-[Reservation:r-a76085ce, Reservation:r-a66085cf, Reservation:r-8c6085e5]
->>> r = instances[0]
->>> for inst in r.instances:
-...    print inst.state
-u'terminated'
->>>
-
-A recent addition to the EC2 api's is to allow other EC2 users to launch
-your images.  There are a couple of ways of accessing this capability in
-boto but I'll show you the simplest way here.  First of all, you need to
-know the Amazon ID for the user in question.  The Amazon Id is a twelve
-digit number that appears on your Account Activity page at AWS.  It looks
-like this:
-
-1234-5678-9012
-
-To use this number in API calls, you need to remove the dashes so in our
-example the user ID would be 12345678912.  To allow the user associated
-with this ID to launch one of your images, let's assume that the variable
-image represents the Image you want to share.  So:
-
->>> image.get_launch_permissions()
-{}
->>>
-
-The get_launch_permissions method returns a dictionary object two possible
-entries; user_ids or groups.  In our case we haven't yet given anyone
-permission to launch our image so the dictionary is empty.  To add our
-EC2 user:
-
->>> image.set_launch_permissions(['123456789012'])
-True
->>> image.get_launch_permissions()
-{'user_ids': [u'123456789012']}
->>>
-
-We have now added the desired user to the launch permissions for the Image
-so that user will now be able to access and launch our Image.  You can add
-multiple users at one time by adding them all to the list you pass in as
-a parameter to the method.  To revoke the user's launch permissions:
-
->>> image.remove_launch_permissions(['123456789012'])
-True
->>> image.get_launch_permissions()
-{}
->>>
-
-It is possible to pass a list of group names to the set_launch_permissions
-method, as well.  The only group available at the moment is the group "all"
-which would allow any valid EC2 user to launch your image.
-
-Finally, you can completely reset the launch permissions for an Image with:
-
->>> image.reset_launch_permissions()
-True
->>>
-
-This will remove all users and groups from the launch permission list and
-makes the Image private, again.
-
-Security Groups
-----------------
-
-Amazon defines a security group as:
-
-"A security group is a named collection of access rules.  These access rules
- specify which ingress, i.e. incoming, network traffic should be delivered
- to your instance."
-
-To get a listing of all currently defined security groups:
-
->>> rs = conn.get_all_security_groups()
->>> print rs
-[SecurityGroup:appserver, SecurityGroup:default, SecurityGroup:vnc, SecurityGroup:webserver]
->>>
-
-Each security group can have an arbitrary number of rules which represent
-different network ports which are being enabled.  To find the rules for a
-particular security group, use the rules attribute:
-
->>> sg = rs[1]
->>> sg.name
-u'default'
->>> sg.rules
-[IPPermissions:tcp(0-65535),
- IPPermissions:udp(0-65535),
- IPPermissions:icmp(-1--1),
- IPPermissions:tcp(22-22),
- IPPermissions:tcp(80-80)]
->>>
-
-In addition to listing the available security groups you can also create
-a new security group.  I'll follow through the "Three Tier Web Service"
-example included in the EC2 Developer's Guide for an example of how to
-create security groups and add rules to them.
-
-First, let's create a group for our Apache web servers that allows HTTP
-access to the world:
-
->>> web = conn.create_security_group('apache', 'Our Apache Group')
->>> web
-SecurityGroup:apache
->>> web.authorize('tcp', 80, 80, '0.0.0.0/0')
-True
->>>
-
-The first argument is the ip protocol which can be one of; tcp, udp or icmp.
-The second argument is the FromPort or the beginning port in the range, the
-third argument is the ToPort or the ending port in the range and the last
-argument is the CIDR IP range to authorize access to.
-
-Next we create another group for the app servers:
-
->>> app = conn.create_security_group('appserver', 'The application tier')
->>>
-
-We then want to grant access between the web server group and the app
-server group.  So, rather than specifying an IP address as we did in the
-last example, this time we will specify another SecurityGroup object.
-
->>> app.authorize(src_group=web)
-True
->>>
-
-Now, to verify that the web group now has access to the app servers, we want to
-temporarily allow SSH access to the web servers from our computer.  Let's
-say that our IP address is 192.168.1.130 as it is in the EC2 Developer
-Guide.  To enable that access:
-
->>> web.authorize(ip_protocol='tcp', from_port=22, to_port=22, cidr_ip='192.168.1.130/32')
-True
->>>
-
-Now that this access is authorized, we could ssh into an instance running in
-the web group and then try to telnet to specific ports on servers in the
-appserver group, as shown in the EC2 Developer's Guide.  When this testing is
-complete, we would want to revoke SSH access to the web server group, like this:
-
->>> web.rules
-[IPPermissions:tcp(80-80),
- IPPermissions:tcp(22-22)]
->>> web.revoke('tcp', 22, 22, cidr_ip='192.168.1.130/32')
-True
->>> web.rules
-[IPPermissions:tcp(80-80)]
->>>
-
-
-
-
-
-
-