forked from nimbusproject/cloudinit.d
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.txt
184 lines (147 loc) · 8.05 KB
/
README.txt
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
cloudinit.d
===========
cloudinit.d is a tool for launching and configuring a set of
interdependent VMs in a cloud (or set of clouds).
The most primitive feature of cloudinit.d is the ability to launch and
configure Virtual Machines. That building block is used to arrange
'boot levels'. Any one boot-level is a collection of VMs that can be
launched at the same time and have no dependencies on each other.
However, Any VM that is running in boot-level N can depend on values and
attributes from any VM run in boot-level N - 1.
Boot Level Example
------------------
To further explain boot level we lay out an example. Let say we want to
run a database driven web application. This application requires 3
instances of the apache web server (for load balancing), all of which
source the same static content from a shared file system and interact
with the same postgres database. This application needs the following
Virtual Machines:
- an NFS server
- a postgres database
- 3 apache web servers
The web server VMs mount the NFS file system and connect to the postgres
database, thus they cannot be started until the NFS VM and the postgres
VM are started.
To launch this application with cloudinit.d the NFS VM and the Postgres
VM would be put into boot level 1, and the 3 Apache VMs would be put
into boot-level 2.
Not only do the web server VMs need the NFS and Postgres to exist, but
they also need to know various bit of information about there specific
instances (like the IP address). Cloud-boot provides a mechanism to
query lower boot level VMs from information. Thus it is a complete tool
for launching many interdependent virtual machines.
Booting and configuring a single instance
-----------------------------------------
Before diving into the details of boot level creation we must first
explain how to launch and configure a single VM with cloudinit.d. As
input cloudinit.d takes a set of configuration files (these will be
discussed in detail later). Here we will just introduce the 'service'
section of the configuration file. This is the part of the
configuration that describes a single VM instance and how it should be
launched, configured, and tested. Below is a sample service section:
[svc-webserver]
image: ami-blahblah
iaas: us-east-1
ssh_username: ubuntu
allocation: m1.small
sshkeyname: ooi
localsshkeypath: ~/.ssh/ooi.pem
readypgm: /opt/sample/sample-test.sh
bootpgm: setuphost.sh
bootconf: sample.json
deps1: sample-deps.conf
deps2: <other dep files>
Here cloudinit.d it instructed to launch the image 'ami-blahblah' in the
cloud 'us-east-1'. The sshkeyname is the security handle known by the
cloud and localsshkeypath is the path a key on the local file system.
Allocation is the type (or size) of the instance required. All of those
values are the information needed just to launch an image in the cloud
and the security handles to access it.
The last four values are used to setup the VM once it is launched.
Often times it is of value to launch a standard VM and customize it
(install needed software, setup user accounts, etc) after it has begun.
The bootpgm key points to a file that is uploaded to the VM and run as
root via sudo (this implies that the ssh_username account must be able
to run sudo without a password). The intention of the bootpgm is to set
up the VM. The user can run any command it likes at their own risk.
The remaining keys allow the user to pass variable information from on
VM to another and are described in the next section.
The next parameter 'readypgm' is a path to a localfile that tests to see
if the VM is ready for use. Once the VM is launched and configured this
file is transfered to it and run. The program should check to see that
all services needed by this host are running properly and thus the
machine is ready to be used. The program should block until either it
determines that machine and all of its services have booted and are
ready to go, or it determines that the boot definitively failed. The
read_timeout parameter describes in seconds how long to wait for the VM
to be ready before timing out and thus considering the boot a failure.
The final value, deps is a list of key value pairs both needed by this
VM and provided by this VM to other VMs. This parameter will be
discussed in the next section.
Service Deps
------------
We see above how to create a single stands- alone VM. Now we will
discuss how to create a VM that depends on other VMs, and more
specifically, how to to get needed variables from those dependencies.
In the above example we have a web server that depended on a database.
The database VM is launched in level 1 and the web server is launched in
level 2. In order for the web server to connect to the database it
needs that VM's IP address. However, this is unknown until the database
VM is launched and running. It is not information that can be
prearranged in the boot-script, instead it must be dynamically
determined at runtime.
The 'deps' file provides a way to describe the values the associated VM
needs from those run in a previous boot level. In our example where the
[svc-webserver] VM needs the IP of a [svc-database] the deps file for
the svc-webserver would have the following:
[deps]
database_ip: ${database.ipaddress}
This tells cloudinit.d to look at all the previous boot levels and search
for a service named [svc-database]. Once found it is told to ask that
service the value of its variable 'ipaddress'. This information can
then be used by the bootpgm to properly launch the [svc-webserver].
Boot-level Files
---------------
Now that we can describe a single VM and a way to get dynamic variables
from 1 VM to another, we can talk about how to arrange them into
boot-levels.
Each boot-level is a single configuration file that consists of [svc-*]
sections as described above. (Details on the svc-* sections can be found
in sample-level.conf). Every service in this section is started,
configured and tested at the same time. The have no dependencies on
each. The boot level is not considered complete until every single
service has started and its ready program has completed successfully.
If any svc fails, the entire boot level fails.
Once we have boot levels described we simply need to describe their
order. This is done in a top-level configuration file. (see
sample-top.conf for details). here is an example:
[runlevels]
level1: sample-level1.conf
level2: level2.conf
level3: level3.conf
level4: level4.conf
This is a very basic configuration file that lists the run levels in
order by pointing at the configuration file for each level.
bootpgm and readypgm
--------------------
There are no restrictions imposed upon these programs. The
responsibility of creating safe programs that do the intended function
is entirely upon the user. The programs are uploaded to the VMs /tmp
directory and run as root. Cloudboot expects that bootpgm will
contextualize the system (anyway it wants) and it expects the readypgm
to return a 0 or a 1 stating if the system is ready or not.
The value for each program can be a single executable file, or it can be
tarball. If the filename ends in 'tar.gz' cloudboot will upload it,
then run tar -zxf on it. It expects the tarball to contain a single
root with the same name as itself, without the tar.gz extension. It
further expects all of the files to be under that directory including an
executable named 'run.sh'. As soon as the expansion of the tarball is
complete 'run.sh' is executed.
The bootpgm program can take advantage of the bootconf json file. This
file can be full of variables from values determined by the given
services dependencies. The user creates the template for this file and
uses the plan configuration value 'bootconf' to tell cloudboot where the
template is. Cloudboot then uses all the values it has from the
services 'deps' file to fill in the template. This file is always
uploaded to: /tmp/nimbusconf/bootconf.json. The users bootconf program
can read it in to determine the needed values.