← Back to branch summary

~blamar/+junk/openstack-api-arrrg

« back to all changes in this revision

Viewing changes to vendor/boto/docs/source/autoscale_tut.rst

  • Committer: Jesse Andrews
  • Date: 2010-05-28 06:05:26 UTC
  • Revision ID: git-v1:bf6e6e718cdc7488e2da87b21e258ccc065fe499
initial commit

Show diffs side-by-side

added added

removed removed

Lines of Context:
vendor/boto/docs/source/autoscale_tut.rst
 
1
.. _autoscale_tut:
 
2
 
 
3
=============================================
 
4
An Introduction to boto's Autoscale interface
 
5
=============================================
 
6
 
 
7
This tutorial focuses on the boto interface to the Autoscale service. This
 
8
assumes you are familiar with boto's EC2 interface and concepts.
 
9
 
 
10
Autoscale Concepts
 
11
------------------
 
12
 
 
13
The AWS Autoscale service is comprised of three core concepts:
 
14
 
 
15
 #. *Autoscale Group (AG):* An AG can be viewed as a collection of criteria for
 
16
    maintaining or scaling a set of EC2 instances over one or more availability
 
17
    zones. An AG is limited to a single region.
 
18
 #. *Launch Configuration (LC):* An LC is the set of information needed by the
 
19
    AG to launch new instances - this can encompass image ids, startup data,
 
20
    security groups and keys. Only one LC is attached to an AG.
 
21
 #. *Triggers*: A trigger is essentially a set of rules for determining when to
 
22
    scale an AG up or down. These rules can encompass a set of metrics such as
 
23
    average CPU usage across instances, or incoming requests, a threshold for
 
24
    when an action will take place, as well as parameters to control how long
 
25
    to wait after a threshold is crossed.
 
26
 
 
27
Creating a Connection
 
28
---------------------
 
29
The first step in accessing autoscaling is to create a connection to the service.
 
30
There are two ways to do this in boto.  The first is:
 
31
 
 
32
>>> from boto.ec2.autoscale import AutoScaleConnection
 
33
>>> conn = AutoScaleConnection('<aws access key>', '<aws secret key>')
 
34
 
 
35
Alternatively, you can use the shortcut:
 
36
 
 
37
>>> conn = boto.connect_autoscale()
 
38
 
 
39
A Note About Regions and Endpoints
 
40
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
41
Like EC2 the Autoscale service has a different endpoint for each region. By
 
42
default the US endpoint is used. To choose a specific region, instantiate the
 
43
AutoScaleConnection object with that region's endpoint.
 
44
 
 
45
>>> ec2 = boto.connect_autoscale(host='eu-west-1.autoscaling.amazonaws.com')
 
46
 
 
47
Alternatively, edit your boto.cfg with the default Autoscale endpoint to use::
 
48
 
 
49
    [Boto]
 
50
    autoscale_endpoint = eu-west-1.autoscaling.amazonaws.com
 
51
 
 
52
Getting Existing AutoScale Groups
 
53
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
54
 
 
55
To retrieve existing autoscale groups:
 
56
 
 
57
>>> conn.get_all_groups()
 
58
 
 
59
You will get back a list of AutoScale group objects, one for each AG you have.
 
60
 
 
61
Creating Autoscaling Groups
 
62
---------------------------
 
63
An Autoscaling group has a number of parameters associated with it.
 
64
 
 
65
 #. *Name*: The name of the AG.
 
66
 #. *Availability Zones*: The list of availability zones it is defined over.
 
67
 #. *Minimum Size*: Minimum number of instances running at one time.
 
68
 #. *Maximum Size*: Maximum number of instances running at one time.
 
69
 #. *Launch Configuration (LC)*: A set of instructions on how to launch an instance.
 
70
 #. *Load Balancer*: An optional ELB load balancer to use. See the ELB tutorial
 
71
    for information on how to create a load balancer.
 
72
 
 
73
For the purposes of this tutorial, let's assume we want to create one autoscale
 
74
group over the us-east-1a and us-east-1b availability zones. We want to have
 
75
two instances in each availability zone, thus a minimum size of 4. For now we
 
76
won't worry about scaling up or down - we'll introduce that later when we talk
 
77
about triggers. Thus we'll set a maximum size of 4 as well. We'll also associate
 
78
the AG with a load balancer which we assume we've already created, called 'my_lb'.
 
79
 
 
80
Our LC tells us how to start an instance. This will at least include the image
 
81
id to use, security_group, and key information. We assume the image id, key
 
82
name and security groups have already been defined elsewhere - see the EC2
 
83
tutorial for information on how to create these.
 
84
 
 
85
>>> from boto.ec2.autoscale import LaunchConfiguration
 
86
>>> from boto.ec2.autoscale import AutoScalingGroup
 
87
>>> lc = LaunchConfiguration(name='my-launch_config', image_id='my-ami',
 
88
                             key_name='my_key_name',
 
89
                             security_groups=['my_security_groups'])
 
90
>>> conn.create_launch_configuration(lc)
 
91
 
 
92
We now have created a launch configuration called 'my-launch-config'. We are now
 
93
ready to associate it with our new autoscale group.
 
94
 
 
95
>>> ag = AutoScalingGroup(group_name='my_group', load_balancers=['my-lb'],
 
96
                          availability_zones=['us-east-1a', 'us-east-1b'],
 
97
                          launch_config=lc, min_size=4, max_size=4)
 
98
>>> conn.create_auto_scaling_group(ag)
 
99
 
 
100
We now have a new autoscaling group defined! At this point instances should be
 
101
starting to launch. To view activity on an autoscale group:
 
102
 
 
103
>>> ag.get_activities()
 
104
 [Activity:Launching a new EC2 instance status:Successful progress:100,
 
105
  ...]
 
106
 
 
107
or alternatively:
 
108
 
 
109
>>> conn.get_all_activities(ag)
 
110
 
 
111
This autoscale group is fairly useful in that it will maintain the minimum size without
 
112
breaching the maximum size defined. That means if one instance crashes, the autoscale
 
113
group will use the launch configuration to start a new one in an attempt to maintain
 
114
its minimum defined size. It knows instance health using the health check defined on
 
115
its associated load balancer.
 
116
 
 
117
Scaling a Group Up or Down
 
118
^^^^^^^^^^^^^^^^^^^^^^^^^^
 
119
It might be more useful to also define means to scale a group up or down
 
120
depending on certain criteria. For example, if the average CPU utilization of
 
121
all your instances goes above 60%, you may want to scale up a number of
 
122
instances to deal with demand - likewise you might want to scale down if usage
 
123
drops. These criteria are defined in *triggers*.
 
124
 
 
125
For example, let's modify our above group to have a maxsize of 8 and define means
 
126
of scaling up based on CPU utilization. We'll say we should scale up if the average
 
127
CPU usage goes above 80% and scale down if it goes below 40%.
 
128
 
 
129
>>> from boto.ec2.autoscale import Trigger
 
130
>>> tr = Trigger(name='my_trigger', autoscale_group=ag,
 
131
             measure_name='CPUUtilization', statistic='Average',
 
132
             unit='Percent',
 
133
             dimensions=[('AutoScalingGroupName', ag.name)],
 
134
             period=60, lower_threshold=40,
 
135
             lower_breach_scale_increment='-5',
 
136
             upper_threshold=80,
 
137
             upper_breach_scale_increment='10',
 
138
             breach_duration=360)
 
139
>> conn.create_trigger(tr)
 
140