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
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
|
<!DOCTYPE html>
<html lang='en'>
<head>
<title>
Virtual Machines - LEAP Platform Documentation
</title>
<meta content='width=device-width, initial-scale=1.0' name='viewport'>
<meta charset='UTF-8'>
<base href="" />
<style>
body {
background: #444;
display: flex;
flex-direction: row;
padding: 10px;
margin: 0px;
}
#sidebar {
flex: 0 0 250px;
background: white;
margin-right: 10px;
padding: 20px;
}
#sidebar ul {
list-style-type: none;
padding-left: 0px;
margin: 0;
}
#sidebar li { padding: 4px }
#sidebar li a { text-decoration: none }
#sidebar li.active { background: #444 }
#sidebar li.active a { color: white }
#sidebar li.level1 { padding-left: 20px }
#sidebar li.level2 { padding-left: 40px }
#main {
flex: 1 1 auto;
background: white;
padding: 20px;
}
#title-box {
padding-bottom: 20px;
border-bottom: 5px solid #eee;
}
#title-box h1 {
margin-top: 0px;
}
pre {
padding: 10px;
background: #eef;
}
code {
background: #eef;
}
table {border-collapse: collapse}
table td {
border: 1px solid #ccc;
padding: 4px;
vertical-align: top;
}
</style>
</head>
<body>
<div id='sidebar'>
<ul>
<li class=''>
<a href='../../index.html'>Home</a>
</li>
<li class='semi-active level0'>
<a class='' href='../guide.html'>Guide</a>
</li>
<li class=' level1'>
<a class='' href='getting-started.html'>Getting Started</a>
</li>
<li class=' level1'>
<a class='' href='config.html'>Configuration Files</a>
</li>
<li class=' level1'>
<a class='' href='nodes.html'>Nodes</a>
</li>
<li class=' level1'>
<a class='' href='keys-and-certificates.html'>Keys and Certificates</a>
</li>
<li class=' level1'>
<a class='' href='domains.html'>Domains</a>
</li>
<li class=' level1'>
<a class='' href='provider-configuration.html'>Provider Configuration</a>
</li>
<li class=' level1'>
<a class='' href='environments.html'>Environments</a>
</li>
<li class='active level1'>
<a class='' href='virtual-machines.html'>Virtual Machines</a>
</li>
<li class=' level1'>
<a class='' href='miscellaneous.html'>Miscellaneous</a>
</li>
<li class=' level1'>
<a class='' href='commands.html'>Command Line Reference</a>
</li>
<li class=' level0'>
<a class='' href='../tutorials.html'>Tutorials</a>
</li>
<li class=' level0'>
<a class='' href='../services.html'>Services</a>
</li>
<li class=' level0'>
<a class='' href='../upgrading.html'>Upgrading</a>
</li>
<li class=' level0'>
<a class='' href='../troubleshooting.html'>Troubleshooting</a>
</li>
<li class=' level0'>
<a class='' href='../details.html'>Details</a>
</li>
</ul>
</div>
<div id='main'>
<div id='title-box'>
<h1>Virtual Machines</h1>
<div id='summary'>Running LEAP platform on remote virtual machines</div>
</div>
<div id='content-box'>
<div id="TOC"><ol>
<li>
<a href="virtual-machines/index.html#introduction">Introduction</a>
</li>
<li>
<a href="virtual-machines/index.html#configuration">Configuration</a>
</li>
<li>
<a href="virtual-machines/index.html#usage">Usage</a>
</li>
<li>
<a href="virtual-machines/index.html#keeping-state-synchronized">Keeping State Synchronized</a>
</li>
<li>
<a href="virtual-machines/index.html#multiple-authentication-profiles">Multiple authentication profiles</a>
</li>
</ol></div>
<h2><a name="introduction"></a>Introduction</h2>
<p>You can use the <code>leap</code> command line to easily manage remote virtual machines.</p>
<p>Note: there are two types of virtual machines that <code>leap</code> can handle:</p>
<ul>
<li><strong>Local</strong> virtual machines running with vagrant, for use in testing.</li>
<li><strong>Remote</strong> virtual machines hosted by a cloud provider like AWS or Rackspace.</li>
</ul>
<p>This guide is for “remote virtual machines”. For “local virtual machines” see <a href="../tutorials/vagrant.html">Vagrant</a>.</p>
<p>Currently, only Amazon AWS is supported as a cloud provider.</p>
<h2><a name="configuration"></a>Configuration</h2>
<p>To get started with virtual machines, you must configure a <code>cloud.json</code> file with your API credentials for the virtual machine vendor. This file lives in the root of your provider directory.</p>
<p>For example:</p>
<pre><code>{
"my_aws": {
"api": "aws",
"vendor": "aws",
"auth": {
"region": "us-west-2",
"aws_access_key_id": "xxxx my key id xxxx",
"aws_secret_access_key": "xxxx my access key xxxx"
}
}
}
</code></pre>
<p>This will configure a cloud “authentication profile” called “my_aws”. This profile will be used by default if there is only one. See below for managing multiple authentication profiles.</p>
<p><em>Required cloud.json properties</em></p>
<ul>
<li><code>$profile</code>: In this case, ‘my_aws’.</li>
<li><code>$profile.api</code>: For now, must always be “aws”.</li>
<li><code>$profile.vendor</code>: For now, must always be “aws”.</li>
<li><code>$profile.auth</code>: API specific authentication configuration for this profile. In the case of AWS, it must include <code>auth.region</code>, <code>auth.aws_access_key_id</code>, and <code>aws_secret_access_key</code>.</li>
</ul>
<p><em>Additional cloud.json properties</em></p>
<p>In addition to required configuration properties, these are optional:</p>
<ul>
<li><code>$profile.default_image</code>: What image to use for new nodes by default. Generally, you should not specify this, because it will automatically select the right Debian image for your region. A node can override this with the property <code>vm.image</code>.</li>
<li><code>$profile.default_options</code>: This is passed directly to the cloud API, and so is specific to whichever API you are using. The node can override this with the property <code>vm.options</code>.</li>
</ul>
<p>A more complete example <code>cloud.json</code>:</p>
<pre><code>{
"my_aws": {
"api": "aws",
"vendor": "aws",
"auth": {
"region": "us-west-2",
"aws_access_key_id": "xxxx my key id xxxx",
"aws_secret_access_key": "xxxx my access key xxxx"
},
"default_image": "ami-98e114f8",
"default_options": {
"InstanceType": "t2.nano"
}
}
}
</code></pre>
<p>See also:</p>
<ul>
<li><a href="https://aws.amazon.com/ec2/instance-types/">Available instance types for AWS</a></li>
<li><a href="https://aws.amazon.com/pt/blogs/security/wheres-my-secret-access-key/">Where’s My Secret Access Key?</a></li>
</ul>
<h2><a name="usage"></a>Usage</h2>
<p>See <code>leap help vm</code> for a description of all the possible commands.</p>
<p>In order to be able to create new virtual machine instances, you need to register your SSH key with the VM vendor.</p>
<pre><code>leap vm key-register
</code></pre>
<p>You only have to do this once, and only people who will be creating new VM instances need to do this.</p>
<p>Once you have done that, you just <code>leap vm add</code> to create the virtual machine and then <code>leap vm start</code> to actually boot it.</p>
<pre><code>leap vm add mynode
leap vm start mynode
</code></pre>
<p>You can specify seed values to <code>leap vm add</code>. For example:</p>
<pre><code>leap vm add mynode services:webapp tags:seattle vm.options.InstanceType:t2.small
</code></pre>
<p>For an email provider installation, you should specify the following seeds:</p>
<pre><code>leap vm add mynode services:webapp,couchdb,soledad,mx
</code></pre>
<p>Check to see what the status is of all VMs:</p>
<pre><code>leap vm status
</code></pre>
<p>If it looks good, you can now deploy to the new server:</p>
<pre><code>leap node init mynode
leap deploy mynode
</code></pre>
<p>To stop the VM:</p>
<pre><code>leap vm stop mynode
</code></pre>
<p>To destroy the VM and clean up its storage space:</p>
<pre><code>leap vm rm mynode
</code></pre>
<p>In general, you should remove VMs instead of stopping them, unless you plan on stopping the VM for a short amount of time. A stopped VM will still use disk space and still incur charges.</p>
<h2><a name="keeping-state-synchronized"></a>Keeping State Synchronized</h2>
<p>The LEAP platform stores all its state information in flat static files. The virtual machine vendor, however, also has its own state.</p>
<p>On the provider side, VM state is stored in node configuration files in <code>nodes/*.json</code>. Of particular importance are the properties <code>ip_address</code> and <code>vm.id</code>.</p>
<p>Most of the time, you should not have any trouble: the <code>leap vm</code> commands will keep things in sync. However, if the state of your configuration files gets out of sync with the state of the virtual machines, it can cause problems.</p>
<p>The command <code>leap vm status</code> will warn you whenever it detects a problem and it will usually propose a fix.</p>
<p>Typically, the fix is to manually update the binding between a local node configuration and the running remote virtual machine, like so:</p>
<pre><code>leap vm bind NODE_NAME VM_ID
</code></pre>
<h2><a name="multiple-authentication-profiles"></a>Multiple authentication profiles</h2>
<p>If you have multiple profiles configured in <code>cloud.json</code>, you can specify which one you want to use:</p>
<ul>
<li>Set the <code>vm.auth</code> property in the node configuration to match the name of the authentication profile.</li>
<li>Or, pass <code>--auth PROFILE_NAME</code> on the command line.</li>
</ul>
</div>
</div>
</body>
</html>
|
