Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 185 lines (147 sloc) 8.24 kb
eb0364d @buzztroll Changing the name in the readme
buzztroll authored
1 cloudinit.d
2 ===========
b677b52 @buzztroll adding the ability to have ssh forwarding enabled on the bootpgm
buzztroll authored
3
eb0364d @buzztroll Changing the name in the readme
buzztroll authored
4 cloudinit.d is a tool for launching and configuring a set of
b677b52 @buzztroll adding the ability to have ssh forwarding enabled on the bootpgm
buzztroll authored
5 interdependent VMs in a cloud (or set of clouds).
6
eb0364d @buzztroll Changing the name in the readme
buzztroll authored
7 The most primitive feature of cloudinit.d is the ability to launch and
b677b52 @buzztroll adding the ability to have ssh forwarding enabled on the bootpgm
buzztroll authored
8 configure Virtual Machines. That building block is used to arrange
9 'boot levels'. Any one boot-level is a collection of VMs that can be
10 launched at the same time and have no dependencies on each other.
11 However, Any VM that is running in boot-level N can depend on values and
12 attributes from any VM run in boot-level N - 1.
13
14 Boot Level Example
15 ------------------
16
17 To further explain boot level we lay out an example. Let say we want to
18 run a database driven web application. This application requires 3
19 instances of the apache web server (for load balancing), all of which
20 source the same static content from a shared file system and interact
21 with the same postgres database. This application needs the following
22 Virtual Machines:
23
24 - an NFS server
25 - a postgres database
26 - 3 apache web servers
27
28 The web server VMs mount the NFS file system and connect to the postgres
29 database, thus they cannot be started until the NFS VM and the postgres
30 VM are started.
31
eb0364d @buzztroll Changing the name in the readme
buzztroll authored
32 To launch this application with cloudinit.d the NFS VM and the Postgres
b677b52 @buzztroll adding the ability to have ssh forwarding enabled on the bootpgm
buzztroll authored
33 VM would be put into boot level 1, and the 3 Apache VMs would be put
34 into boot-level 2.
35
36 Not only do the web server VMs need the NFS and Postgres to exist, but
37 they also need to know various bit of information about there specific
38 instances (like the IP address). Cloud-boot provides a mechanism to
39 query lower boot level VMs from information. Thus it is a complete tool
40 for launching many interdependent virtual machines.
41
42 Booting and configuring a single instance
43 -----------------------------------------
44
45 Before diving into the details of boot level creation we must first
eb0364d @buzztroll Changing the name in the readme
buzztroll authored
46 explain how to launch and configure a single VM with cloudinit.d. As
47 input cloudinit.d takes a set of configuration files (these will be
b677b52 @buzztroll adding the ability to have ssh forwarding enabled on the bootpgm
buzztroll authored
48 discussed in detail later). Here we will just introduce the 'service'
49 section of the configuration file. This is the part of the
50 configuration that describes a single VM instance and how it should be
51 launched, configured, and tested. Below is a sample service section:
52
53
54 [svc-webserver]
55 image: ami-blahblah
56 iaas: us-east-1
57 ssh_username: ubuntu
58 allocation: m1.small
59 sshkeyname: ooi
60 localsshkeypath: ~/.ssh/ooi.pem
61 readypgm: /opt/sample/sample-test.sh
62 bootpgm: setuphost.sh
63 bootconf: sample.json
64 deps1: sample-deps.conf
65 deps2: <other dep files>
66
67
eb0364d @buzztroll Changing the name in the readme
buzztroll authored
68 Here cloudinit.d it instructed to launch the image 'ami-blahblah' in the
b677b52 @buzztroll adding the ability to have ssh forwarding enabled on the bootpgm
buzztroll authored
69 cloud 'us-east-1'. The sshkeyname is the security handle known by the
70 cloud and localsshkeypath is the path a key on the local file system.
71 Allocation is the type (or size) of the instance required. All of those
72 values are the information needed just to launch an image in the cloud
73 and the security handles to access it.
74
75 The last four values are used to setup the VM once it is launched.
76 Often times it is of value to launch a standard VM and customize it
77 (install needed software, setup user accounts, etc) after it has begun.
78 The bootpgm key points to a file that is uploaded to the VM and run as
79 root via sudo (this implies that the ssh_username account must be able
80 to run sudo without a password). The intention of the bootpgm is to set
81 up the VM. The user can run any command it likes at their own risk.
82 The remaining keys allow the user to pass variable information from on
83 VM to another and are described in the next section.
84
85 The next parameter 'readypgm' is a path to a localfile that tests to see
86 if the VM is ready for use. Once the VM is launched and configured this
87 file is transfered to it and run. The program should check to see that
88 all services needed by this host are running properly and thus the
89 machine is ready to be used. The program should block until either it
90 determines that machine and all of its services have booted and are
91 ready to go, or it determines that the boot definitively failed. The
92 read_timeout parameter describes in seconds how long to wait for the VM
93 to be ready before timing out and thus considering the boot a failure.
94
95 The final value, deps is a list of key value pairs both needed by this
96 VM and provided by this VM to other VMs. This parameter will be
97 discussed in the next section.
98
99 Service Deps
100 ------------
101
102 We see above how to create a single stands- alone VM. Now we will
103 discuss how to create a VM that depends on other VMs, and more
104 specifically, how to to get needed variables from those dependencies.
105
106 In the above example we have a web server that depended on a database.
107 The database VM is launched in level 1 and the web server is launched in
108 level 2. In order for the web server to connect to the database it
109 needs that VM's IP address. However, this is unknown until the database
110 VM is launched and running. It is not information that can be
111 prearranged in the boot-script, instead it must be dynamically
112 determined at runtime.
113
114 The 'deps' file provides a way to describe the values the associated VM
115 needs from those run in a previous boot level. In our example where the
116 [svc-webserver] VM needs the IP of a [svc-database] the deps file for
117 the svc-webserver would have the following:
118
119
120 [deps]
121 database_ip: ${database.ipaddress}
122
123
eb0364d @buzztroll Changing the name in the readme
buzztroll authored
124 This tells cloudinit.d to look at all the previous boot levels and search
b677b52 @buzztroll adding the ability to have ssh forwarding enabled on the bootpgm
buzztroll authored
125 for a service named [svc-database]. Once found it is told to ask that
126 service the value of its variable 'ipaddress'. This information can
127 then be used by the bootpgm to properly launch the [svc-webserver].
128
129 Boot-level Files
130 ---------------
131
132 Now that we can describe a single VM and a way to get dynamic variables
133 from 1 VM to another, we can talk about how to arrange them into
134 boot-levels.
135
136 Each boot-level is a single configuration file that consists of [svc-*]
137 sections as described above. (Details on the svc-* sections can be found
138 in sample-level.conf). Every service in this section is started,
139 configured and tested at the same time. The have no dependencies on
140 each. The boot level is not considered complete until every single
141 service has started and its ready program has completed successfully.
142 If any svc fails, the entire boot level fails.
143
144 Once we have boot levels described we simply need to describe their
145 order. This is done in a top-level configuration file. (see
146 sample-top.conf for details). here is an example:
147
148 [runlevels]
149 level1: sample-level1.conf
150 level2: level2.conf
151 level3: level3.conf
152 level4: level4.conf
153
154 This is a very basic configuration file that lists the run levels in
155 order by pointing at the configuration file for each level.
156
157 bootpgm and readypgm
158 --------------------
159
160 There are no restrictions imposed upon these programs. The
161 responsibility of creating safe programs that do the intended function
162 is entirely upon the user. The programs are uploaded to the VMs /tmp
163 directory and run as root. Cloudboot expects that bootpgm will
164 contextualize the system (anyway it wants) and it expects the readypgm
165 to return a 0 or a 1 stating if the system is ready or not.
166
167 The value for each program can be a single executable file, or it can be
168 tarball. If the filename ends in 'tar.gz' cloudboot will upload it,
169 then run tar -zxf on it. It expects the tarball to contain a single
170 root with the same name as itself, without the tar.gz extension. It
171 further expects all of the files to be under that directory including an
172 executable named 'run.sh'. As soon as the expansion of the tarball is
173 complete 'run.sh' is executed.
174
175 The bootpgm program can take advantage of the bootconf json file. This
176 file can be full of variables from values determined by the given
177 services dependencies. The user creates the template for this file and
178 uses the plan configuration value 'bootconf' to tell cloudboot where the
179 template is. Cloudboot then uses all the values it has from the
180 services 'deps' file to fill in the template. This file is always
181 uploaded to: /tmp/nimbusconf/bootconf.json. The users bootconf program
182 can read it in to determine the needed values.
183
184
Something went wrong with that request. Please try again.