-
Notifications
You must be signed in to change notification settings - Fork 20
/
README-AWS
257 lines (217 loc) · 13 KB
/
README-AWS
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
Amazon Web Services
======================================
Allowed commands:
create - create an environment of instances, optional VPCs, load balancers, etc.
destroy - delete a previously created environment
suspend - "stop" all instances in the environment. NOTE - there are many differences between this
and the "suspend" command for VMware. You won't be billed for instance usage, but you will be billed
for your EBS volume. Amazon actually will deprovision your VM and save your associated EBS.
When you restart a stopped instance, it will have a new IP address, DNS name, etc.
resume - start all stopped instances in the environment.
-----------
Credentials
-----------
You will need to create a credentials file with information from
your Amazon Web Services account. There is a template file in
example-config/credentials-templates/aws.creds.template.key
You will need to replace the access.key and secret.key with the
access key and secret key associated with your AWS account. You
can find this information at :
https://portal.aws.amazon.com/gp/aws/securityCredentials
access.key = Access Key ID
secret.key = Secret Access Key
-----------
Templates
-----------
The general layout of an AWS Environment Template is the following:
The number in the parenthesis is the number of those elements allowed.
context(1)
└── environment(1)
├── instance(n)
│ ├── boot-actions(1)
│ │ └── script(n)
│ │ └── param(n)
│ ├── post-create-actions(1)
│ │ └── ssh(n)
│ └── security-group-ref(n)
├── load-balancer(n)
│ ├── health-check(1)
│ └── listener(n)
└── vpc(1)
├── inet-gwy(1)
├── route-table(n)
│ └── route(n)
├── subnet(n)
└── vpc-security-group(n)
└── rule(n)
The following is a list of elements available in the xml:
[ The hierarchy represents which elements go under which in the xml ]
o context: The context holds the whole environment. It has one or more
xmlns attributes, which specify map an xml namespace to a package. The
packages it points to should contain a properties file named:
x2o.classes
for VMware use: xmlns="com.urbancode.uprovision.tasks.vmware"
for AWS use: xmlns="com.urbancode.uprovision.tasks.aws"
o environment: The environment contains the Virtual Private Cloud (only 1
VPC per environment). The name of the environment is used as a prefix
on the name tags in AWS.
o vpc: This is the core network. It is made with a CIDR (x.x.x.x/y).
For more information on CIDR notation, see:
http://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing
o subnet: Subnets are smaller networks inside of the VPC. They each
have their own CIDR which is a sub-set of the VPC's CDIR. Each
subnet has a zone property which specifies a region that the subnet
will be located in. If any instances in this subnet need to be
behind an Elastic Load Balancer, the zone of this subnet must match
that of the load balancer.
o inet-gwy: The Internet Gateway attaches to a VPC and allows
internet access from inside the VPC.
o route-table: Each VPC has a "Main" route table that cannot be
deleted. Route Tables can be associated with a single subnet
subnet. There can only be one "default" Route Table, which all new
subnets will use if no Route Table is specified. The default Route
Table will attempt to make a Route to allow instances to reach the
internet if an Internet Gateway exists.
o route: Routes are elements of a Route Table. They contain a
target, which can be an Internet Gateway, a NAT (a specially
configured instance), or an ENI (Elastic Network Interface). They
also contain a destination, which is described by a CIDR block.
* For more information on Route Tables and Routes, see:
http://docs.amazonwebservices.com/AmazonVPC/latest/UserGuide/VPC_Routing.html
o vpc-security-group: A Security Group essentially acts as a firewall.
They can be applied to multiple instances (and/or load balancers)
and allow or disallow incoming or outgoing traffic on specified
ports. A Security Group contains a collection of Rules, which
contain the details on the traffic rules. They also have a name and
description.
o rule: A Rule contains a source, which will apply to rule to just
traffic from the specified CIDR. A Rule also contains a protocol,
which the rule will apply only to traffic using that protocol, a
port range, which is the range of ports the rule will apply to,
and an inbound flag, which if set to false, will apply the rule
to outbound traffic.
o instance: The representation of the EC2 instance that will be
launched.
-name: the name of the instance. The number of the instance will be
automatically appended to the end of the instance name once it has
been launched.
e.g. an instance with the name "web" and count "2" will launch instances:
web00 and web01
-ami-id: the id of of the Amazon Machine Image to use for the instance
-subnet-name: the name of the subnet to launch the instance into
-count: the number of instances with these same details you would like
to launch
-elastic-ip: a flag that if set to true, will assign an Elastic Ip
Address to this instance. This allows you to reach the instance
from outside of the VPC.
* AWS has a default of 5 EIPs per account. For more info, see:
http://aws.amazon.com/contact-us/eip_limit_request/
-private-key-ref: The Key Pair (SSH key) that the instance will be
accessable by. You can find these in your AWS account. This is also
the key that will be used to run the SSH Post Create Actions.
-image-size: The size, or type, of the instance you want to create.
VPCs currently cannot support instances of size t1.micro.
valid values: m1.small, c1.medium, m1.medium, m1.large, m1.xlarge,
m2.xlarge, m2.2xlarge, m2.4xlarge, c1.xlarge
For more info, see:
http://aws.amazon.com/ec2/instance-types/
-kernel-id: This is the id of the kernel you would like to use. It is
recommended that you leave this empty, as it will use the default kernel
for the AMI.
-ramdisk-id: This is the id of the RAM disk you would like to use. It is
recommended that you leave this empty, as it will use the default RAM disk
for the AMI.
-load-balancer: the name of the load balancer the instance will be
registered with
-priority: This is the order in which the instance will be launched
in. The instances with the lowest priority will be completely
launched first. This means that the instance will hit the 'running'
state, the 'ok' status, all boot-actions will be ran, then the
post-create-actions will be ran. You can have multiple instances
with the same priority and they will all be launched at once.
o security-group-ref: This is just a reference to the Security Group
you would like to apply to the instance. You can have multiple of
these.
o boot-actions: This is a list of actions that will be run at
FIRST BOOT of the instance. These actions are run as root and are
referered to as User-Data by Amazon. This will automatically
convert the script to Base64 as required by Amazon. The whole
user-data script (but not including the contents of external
scripts) will be resolved for any properties that may show up.
Script can be 16KB max.
-shell: This is the shell that the user-data will be run with.
o script: This is a action that will grab a script from the given
URL and run it with the specified shell. This grabs the script
using 'wget'. You can have multiple script elements.
o param: These are parameters for a given script. They will be
ran in order from first to last defined.
o post-create-actions: This contains all the actions to be ran after
the instance has fully started.
o ssh: Connects to an instance via ssh. The instance should have an
Elastic Ip, allowing outside traffic in, along with allowing
inbound traffic on port 22.
* include any used key-pair files (.pem) in ~/.terraform/
o load-balancer: An Elastic Load Balancer by Amazon for load balancing
instances.
-name: the name of the load balancer.
-subnet-name: the subnet to associate with the load balancer
-app-cookie-name: the name of the cookie your application uses.
You can leave this blank if you want the load balancer to handle
the cookies.
o listener: Where and how the load balancer listens
-protocol: Valid values: http, https, tcp, ssh
-instance-port: The port on the instance to send traffic to
-load-balancer-port: Port to listen on
-cert-id: Use only if you are using a secure protocol
o health-check: This is how the load balancer determines whether or
not an instance is health and can accept traffic or not. The
instance must return a status 200 OK in order to be considered a
successful check.
-interval: the frequency of checks on instances
-timeout: how long before a check on the instance will timeout
-unhealthy-count: How many consecutive checks before an instance
is determined to be unhealthy
-healthy-count: How many consecuctive checks before an instance
is determined to be healthy
-protocol: the protocol on which to check the instance
-port: the port to check the instance on
-path: the path on the instance to check
* For more information on any of these elements, check the Amazon Web Services
documentation at: http://aws.amazon.com/documentation/ec2/
-----------
Other Notes
-----------
When an instance is launched, two properties are set. One for
the public ip address, and one for the private ip address. These
can be used with ${INSTANCENAME.public.ip} ${INSTANCENAME.private.ip}
e.g. If you launch an instance with name "web" and count "2", you can
access the ips of the two instances with these properties:
${web00.private.ip} ${web01.public.ip} etc
Note: a public ip address (aka Elastic IP) will only be assigned if
the elastic-ip flag on an instance is set to true.
Check the example AWS template in the example-config/xml-templates
for more information on creating templates.
In order for any Post Create Actions to run on an Amazon EC2
instance, the instance must have an Elastic Ip Address assigned
to it. You must also have the key-pair (ssh key) that the instance
was created with in your ~/.terraform directory.
The Elastic Ip Address is neccessary since the instances are
launched inside of a Virtual Private Cloud. The EIP allows you to
communicate with those instances from outside of the VPC.
File Information
The key-pair file is needed for connecting to the server. You
must also know what user that key-pair was associated with. This is
determined when the AMI (Amazon Machine Image) is created.
IMPORTANT: Launching public images without a key pair ID will leave
them inaccessible. The public key material is made available to the
instance at boot time by placing it in the openssh_id.pub file on a
logical device that is exposed to the instance as /dev/sda2 (the
ephemeral store). The format of this file is suitable for use as an
entry within ~/.ssh/authorized_keys (the OpenSSH format). This can
be done at boot (e.g., as part of rc.local) allowing for secure
access without passwords. Optional user data can be provided in the
launch request. All instances that collectively comprise the launch
request have access to this data For more information, see Instance
Metadata.
NOTE: If any of the AMIs have a product code attached for which the
user has not subscribed, the instance launch will fail.