← Back to branch summary

~ntt-pf-lab/nova/monkey_patch_notification

« back to all changes in this revision

Viewing changes to vendor/boto/docs/source/elb_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/elb_tut.rst
 
1
.. _elb_tut:
 
2
 
 
3
==========================================================
 
4
An Introduction to boto's Elastic Load Balancing interface
 
5
==========================================================
 
6
 
 
7
This tutorial focuses on the boto interface for Elastic Load Balancing
 
8
from Amazon Web Services.  This tutorial assumes that you have already
 
9
downloaded and installed boto, and are familiar with the boto ec2 interface.
 
10
 
 
11
Elastic Load Balancing Concepts
 
12
-------------------------------
 
13
Elastic Load Balancing (ELB) is intimately connected with Amazon's Elastic
 
14
Compute Cloud (EC2) service. Using the ELB service allows you to create a load
 
15
balancer - a DNS endpoint and set of ports that distributes incoming requests
 
16
to a set of ec2 instances. The advantages of using a load balancer is that it
 
17
allows you to truly scale up or down a set of backend instances without
 
18
disrupting service. Before the ELB service you had to do this manually by
 
19
launching an EC2 instance and installing load balancer software on it (nginx,
 
20
haproxy, perlbal, etc.) to distribute traffic to other EC2 instances.
 
21
 
 
22
Recall that the ec2 service is split into Regions and Availability Zones (AZ).
 
23
At the time of writing, there are two Regions - US and Europe, and each region
 
24
is divided into a number of AZs (for example, us-east-1a, us-east-1b, etc.).
 
25
You can think of AZs as data centers - each runs off a different set of ISP
 
26
backbones and power providers. ELB load balancers can span multiple AZs but
 
27
cannot span multiple regions. That means that if you'd like to create a set of
 
28
instances spanning both the US and Europe Regions you'd have to create two load
 
29
balancers and have some sort of other means of distributing requests between
 
30
the two loadbalancers. An example of this could be using GeoIP techniques to
 
31
choose the correct load balancer, or perhaps DNS round robin. Keep in mind also
 
32
that traffic is distributed equally over all AZs the ELB balancer spans. This
 
33
means you should have an equal number of instances in each AZ if you want to
 
34
equally distribute load amongst all your instances.
 
35
 
 
36
Creating a Connection
 
37
---------------------
 
38
The first step in accessing ELB is to create a connection to the service.
 
39
There are two ways to do this in boto.  The first is:
 
40
 
 
41
>>> from boto.ec2.elb import ELBConnection
 
42
>>> conn = ELBConnection('<aws access key>', '<aws secret key>')
 
43
 
 
44
There is also a shortcut function in the boto package, called connect_elb
 
45
that may provide a slightly easier means of creating a connection:
 
46
 
 
47
>>> import boto
 
48
>>> conn = boto.connect_elb()
 
49
 
 
50
In either case, conn will point to an ELBConnection object which we will
 
51
use throughout the remainder of this tutorial.
 
52
 
 
53
A Note About Regions and Endpoints
 
54
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
55
Like EC2 the ELB service has a different endpoint for each region. By default
 
56
the US endpoint is used. To choose a specific region, instantiate the
 
57
ELBConnection object with that region's endpoint.
 
58
 
 
59
>>> ec2 = boto.connect_elb(host='eu-west-1.elasticloadbalancing.amazonaws.com')
 
60
 
 
61
Alternatively, edit your boto.cfg with the default ELB endpoint to use::
 
62
 
 
63
    [Boto]
 
64
    elb_endpoint = eu-west-1.elasticloadbalancing.amazonaws.com
 
65
 
 
66
Getting Existing Load Balancers
 
67
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
68
 
 
69
To retrieve any exiting load balancers:
 
70
 
 
71
>>> conn.get_all_load_balancers()
 
72
 
 
73
You will get back a list of LoadBalancer objects.
 
74
 
 
75
Creating a Load Balancer
 
76
------------------------
 
77
To create a load balancer you need the following:
 
78
 #. The specific **ports and protocols** you want to load balancer over, and what port
 
79
    you want to connect to all instances.
 
80
 #. A **health check** - the ELB concept of a *heart beat* or *ping*. ELB will use this health
 
81
    check to see whether your instances are up or down. If they go down, the load balancer
 
82
    will no longer send requests to them.
 
83
 #. A **list of Availability Zones** you'd like to create your load balancer over.
 
84
 
 
85
Ports and Protocols
 
86
^^^^^^^^^^^^^^^^^^^
 
87
An incoming connection to your load balancer will come on one or more ports -
 
88
for example 80 (HTTP) and 443 (HTTPS). Each can be using a protocol -
 
89
currently, the supported protocols are TCP and HTTP.  We also need to tell the
 
90
load balancer which port to route connects *to* on each instance.  For example,
 
91
to create a load balancer for a website that accepts connections on 80 and 443,
 
92
and that routes connections to port 8080 and 8443 on each instance, you would
 
93
specify that the load balancer ports and protocols are:
 
94
 
 
95
 * 80, 8080, HTTP
 
96
 * 443, 8443, TCP
 
97
 
 
98
This says that the load balancer will listen on two ports - 80 and 443.
 
99
Connections on 80 will use an HTTP load balancer to forward connections to port
 
100
8080 on instances. Likewise, the load balancer will listen on 443 to forward
 
101
connections to 8443 on each instance using the TCP balancer. We need to
 
102
use TCP for the HTTPS port because it is encrypted at the application
 
103
layer. Of course, we could specify the load balancer use TCP for port 80,
 
104
however specifying HTTP allows you to let ELB handle some work for you -
 
105
for example HTTP header parsing.
 
106
 
 
107
 
 
108
Configuring a Health Check
 
109
^^^^^^^^^^^^^^^^^^^^^^^^^^
 
110
A health check allows ELB to determine which instances are alive and able to
 
111
respond to requests. A health check is essentially a tuple consisting of:
 
112
 
 
113
 * *target*: What to check on an instance. For a TCP check this is comprised of::
 
114
 
 
115
        TCP:PORT_TO_CHECK
 
116
 
 
117
   Which attempts to open a connection on PORT_TO_CHECK. If the connection opens
 
118
   successfully, that specific instance is deemed healthy, otherwise it is marked
 
119
   temporarily as unhealthy. For HTTP, the situation is slightly different::
 
120
 
 
121
        HTTP:PORT_TO_CHECK/RESOURCE
 
122
 
 
123
   This means that the health check will connect to the resource /RESOURCE on
 
124
   PORT_TO_CHECK. If an HTTP 200 status is returned the instance is deemed healthy.
 
125
 * *interval*: How often the check is made. This is given in seconds and defaults to 30.
 
126
   The valid range of intervals goes from 5 seconds to 600 seconds.
 
127
 * *timeout*: The number of seconds the load balancer will wait for a check to return a
 
128
   result.
 
129
 * *UnhealthyThreshold*: The number of consecutive failed checks to deem the instance
 
130
   as being dead. The default is 5, and the range of valid values lies from 2 to 10.
 
131
 
 
132
The following example creates a health check called *instance_health* that simply checks
 
133
instances every 20 seconds on port 80 over HTTP at the resource /health for 200 successes.
 
134
 
 
135
>>> import boto
 
136
>>> from boto.ec2.elb import HealthCheck
 
137
>>> conn = boto.connect_elb()
 
138
>>> hc = HealthCheck('instance_health', interval=20, target='HTTP:8080/health')
 
139
 
 
140
Putting It All Together
 
141
^^^^^^^^^^^^^^^^^^^^^^^
 
142
 
 
143
Finally, let's create a load balancer in the US region that listens on ports 80 and 443
 
144
and distributes requests to instances on 8080 and 8443 over HTTP and TCP. We want the
 
145
load balancer to span the availability zones *us-east-1a* and *us-east-1b*:
 
146
 
 
147
>>> lb = conn.create_load_balancer('my_lb', ['us-east-1a', 'us-east-1b'],
 
148
                                   [(80, 8080, 'http'), (443, 8443, 'tcp')])
 
149
>>> lb.configure_health_check(hc)
 
150
 
 
151
The load balancer has been created. To see where you can actually connect to it, do:
 
152
 
 
153
>>> print lb.dns_name
 
154
my_elb-123456789.us-east-1.elb.amazonaws.com
 
155
 
 
156
You can then CNAME map a better name, i.e. www.MYWEBSITE.com to the above address.
 
157
 
 
158
Adding Instances To a Load Balancer
 
159
-----------------------------------
 
160
 
 
161
Now that the load balancer has been created, there are two ways to add instances to it:
 
162
 
 
163
 #. Manually, adding each instance in turn.
 
164
 #. Mapping an autoscale group to the load balancer. Please see the Autoscale
 
165
    tutorial for information on how to do this.
 
166
 
 
167
Manually Adding and Removing Instances
 
168
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
169
 
 
170
Assuming you have a list of instance ids, you can add them to the load balancer
 
171
 
 
172
>>> instance_ids = ['i-4f8cf126', 'i-0bb7ca62']
 
173
>>> lb.register_instances(instance_ids)
 
174
 
 
175
Keep in mind that these instances should be in Security Groups that match the
 
176
internal ports of the load balancer you just created (for this example, they
 
177
should allow incoming connections on 8080 and 8443).
 
178
 
 
179
To remove instances:
 
180
 
 
181
>>> lb.degregister_instances(instance_ids)
 
182
 
 
183
Modifying Availability Zones for a Load Balancer
 
184
------------------------------------------------
 
185
 
 
186
If you wanted to disable one or more zones from an existing load balancer:
 
187
 
 
188
>>> lb.disable_zones(['us-east-1a'])
 
189
 
 
190
You can then terminate each instance in the disabled zone and then deregister then from your load
 
191
balancer.
 
192
 
 
193
To enable zones:
 
194
 
 
195
>>> lb.enable_zones(['us-east-1c'])
 
196
 
 
197
Deleting a Load Balancer
 
198
------------------------
 
199
 
 
200
>>> lb.delete()
 
201
 
 
202