You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Jul 16, 2020. It is now read-only.
# Ciao Single Machine Development and Test Environment
2
2
3
-
Developing cluster software is complicated if you must actually run a whole cluster on a set of physical machines. This begs for a development environment that is self contained and can be run without any setup.
3
+
Developing cluster software is complicated if you must actually run a whole
4
+
cluster on a set of physical machines. This begs for a development environment
5
+
that is self contained and can be run without any setup.
4
6
5
7
The goals for the Ciao development environment are that it:
6
8
7
9
- Requires very minimal setup by the user
8
-
- Does not affect the user's development system in any manner (i.e. the user can keep the firewall rules, selinux setup,... intact)
9
-
- Supports modes that allow it to run on a range of devices from powerful workstations to less powerful laptops
10
-
- Provides the ability to validate all code changes the user makes against the Ciao release criterion
11
-
12
-
This page documents a way to set up an entire Ciao cluster inside a single machine. This cluster-in-a-machine mode is ideal for developers that desire the ability to build Ciao from sources, make changes and perform quick end to end functional integration testing without requiring multiple machines/VM's, creating a custom networking environment or maintaining a bevy of physical machines and a physical network.
10
+
- Does not affect the user's development system in any manner (i.e. the user
11
+
can keep the firewall rules, selinux setup,... intact)
12
+
- Supports modes that allow it to run on a range of devices from powerful
13
+
workstations to less powerful laptops
14
+
- Provides the ability to validate all code changes the user makes against
15
+
the Ciao release criterion
16
+
17
+
This page documents a way to set up an entire Ciao cluster inside a single
18
+
machine. This cluster-in-a-machine mode is ideal for developers that desire
19
+
the ability to build Ciao from sources, make changes and perform quick end to
20
+
end functional integration testing without requiring multiple machines/VM's,
21
+
creating a custom networking environment or maintaining a bevy of physical
22
+
machines and a physical network.
13
23
14
24
We support two modes of operation:
15
25
16
-
- ciao-down mode: Where a virtual machine is automatically created and launched, and the virtual cluster is setup and tested within the virtual machine
17
-
- bare metal mode: Where the virtual cluster is setup on the host machine itself
26
+
- ciao-down mode: Where a virtual machine is automatically created and
27
+
launched, and the virtual cluster is setup and tested within the virtual
28
+
machine
29
+
- bare metal mode: Where the virtual cluster is setup on the host machine
30
+
itself
18
31
19
-
The ciao-down mode is the preferred mode of development on systems that have the resources and CPU capabilities needed, as it fully isolates the Ciao virtual cluster and sets up an environment in which Ciao is known to work seamlessly. In addition, the ciao-down mode does not require any changes to the user's network firewall setup. However, ciao-down mode does require VT-x nesting to be supported by the host.
32
+
The ciao-down mode is the preferred mode of development on systems that have
33
+
the resources and CPU capabilities needed, as it fully isolates the Ciao
34
+
virtual cluster and sets up an environment in which Ciao is known to work
35
+
seamlessly. In addition, the ciao-down mode does not require any changes to
36
+
the user's network firewall setup. However, ciao-down mode does require
37
+
VT-x nesting to be supported by the host.
20
38
21
-
The bare metal mode is the highest performance mode, but may require some network firewall modification. It also uses less resources and can run on machines whose CPUs do not support VT-x nesting.
39
+
The bare metal mode is the highest performance mode, but may require some
40
+
network firewall modification. It also uses less resources and can run on
41
+
machines whose CPUs do not support VT-x nesting.
22
42
23
-
In both modes Ciao is configured in a special all in one development mode where cluster nodes have dual roles (i.e launcher can be a Network Node and a Compute Node at the same time)
43
+
In both modes Ciao is configured in a special all in one development mode
44
+
where cluster nodes have dual roles (i.e launcher can be a Network Node and
45
+
a Compute Node at the same time)
24
46
25
-
In the text below **machine** refers to the ciao-down VM in the case of the ciao-down mode, it refers to the host system in the case of the bare metal mode.
47
+
In the text below **machine** refers to the ciao-down VM in the case of the
48
+
ciao-down mode, it refers to the host system in the case of the bare metal mode.
26
49
27
50
## Components running on the Machine
28
51
1. Controller
@@ -34,65 +57,57 @@ In the text below **machine** refers to the ciao-down VM in the case of the ciao
34
57
7. Machine Local DHCP Server
35
58
...
36
59
37
-
The machine acts as the Ciao compute node, network node, ciao-controller, ciao-scheduler and also hosts the ciao-webui as well as other openstack and dhcp services.
60
+
The machine acts as the Ciao compute node, network node, ciao-controller,
61
+
ciao-scheduler and also hosts the ciao-webui as well as other openstack
62
+
and dhcp services.
38
63
39
64
## Graphical Overview
40
65
41
66
When the system is functioning the overall setup manifests as follows:
42
67
43
-
As you can see below the Cluster runs on a isolated virtual network resident inside the machine.
44
-
Hence the cluster is invisible outside the machine and completely self contained.
68
+
As you can see below the Cluster runs on a isolated virtual network resident
69
+
inside the machine. Hence the cluster is invisible outside the machine and
If you desire to provide external network connectivity to the workloads then the host needs to act as gateway to the Internet. The host needs to enable ipv4 forwarding and ensure all traffic exiting the cluster via the host is NATed.
81
-
82
-
This assumes the host has a single network interface. For multi homed systems, the setup is more complicated and needs appropriate routing setup which is outside the scope of this document. If you have a custom firewall configuration, you will need set things up appropriately.
83
-
84
-
Very simplistically this can be done by
85
-
```
86
-
iptables -t nat -A POSTROUTING -o $device -j MASQUERADE #$device is the network interface on the host
87
-
88
-
echo 1 > /proc/sys/net/ipv4/ip_forward
89
-
```
90
-
91
104
# Install Go
92
105
On the host install the latest release of go for your distribution
93
106
[Installing Go](https://golang.org/doc/install).
94
107
95
-
> NOTE: Go version 1.7 or later is required for Ciao. Ciao will not work with older version of Go. Hence it is best you download and install the latest version of Go if you distro is not on Go 1.7.
108
+
> NOTE: Go version 1.7 or later is required for Ciao. Ciao will not work with
109
+
older version of Go. Hence it is best you download and install the latest
110
+
version of Go if you distro is not on Go 1.7.
96
111
97
112
You should also ensure that your GOPATH environment variable is set.
98
113
@@ -158,21 +173,23 @@ same location as the directory appears on your host. You can then
158
173
modify the ciao-webui code on your host and build inside the VM.
159
174
160
175
161
-
For more details and full set of capabilities of ciao-down see the full [ciao-down documentation ](https://github.com/01org/ciao/blob/master/testutil/ciao-down/README.md)
176
+
For more details and full set of capabilities of ciao-down see the full
Setup passwordless sudo for the user who will be running the script below.
184
201
202
+
## Cluster External Network Access
203
+
204
+
If you desire to provide external network connectivity to the workloads then
205
+
the host needs to act as gateway to the Internet. The host needs to enable
206
+
ipv4 forwarding and ensure all traffic exiting the cluster via the host is
207
+
NATed.
208
+
209
+
This assumes the host has a single network interface. For multi homed systems,
210
+
the setup is more complicated and needs appropriate routing setup which is
211
+
outside the scope of this document. If you have a custom firewall
212
+
configuration, you will need set things up appropriately.
213
+
214
+
Very simplistically this can be done by
215
+
```
216
+
#$device is the network interface on the host
217
+
iptables -t nat -A POSTROUTING -o $device -j MASQUERADE
218
+
219
+
220
+
echo 1 > /proc/sys/net/ipv4/ip_forward
221
+
```
222
+
223
+
185
224
## Download and build the sources
186
225
187
226
Download and build the ciao sources:
@@ -194,18 +233,23 @@ You should see no errors.
194
233
195
234
# Verify that Ciao is fully functional using the **machine**
196
235
197
-
Now that you have the machine setup (either a bare metal setup or a ciao-down VM setup).
236
+
Now that you have the machine setup (either a bare metal setup or a
237
+
ciao-down VM setup).
238
+
239
+
You can now quickly verify that all aspects of Ciao including VM launch,
240
+
container launch, and networking.
198
241
199
-
You can now quickly verify that all aspects of Ciao including VM launch, container launch, and networking.
200
242
These steps are performed inside the machine.
201
243
202
244
To do this simply run the following:
203
245
```
204
246
cd $GOPATH/src/github.com/01org/ciao/testutil/singlevm
247
+
. ~/local/demo.sh
205
248
#Cleanup any previous setup
206
249
./cleanup.sh
207
250
#Set up the test environment
208
251
./setup.sh
252
+
. ~/local/demo.sh
209
253
#Perform a full cluster test
210
254
./verify.sh
211
255
```
@@ -216,13 +260,32 @@ The ```verify.sh``` script will:
216
260
- Test for ssh reach ability into VMs with private and external IPs
217
261
- Delete all the VM's and Container that were created
218
262
219
-
If the script reports success, it indicates to the developer that any changes made have not broken any functionality across all the Ciao components.
263
+
If the script reports success, it indicates to the developer that any changes
264
+
made have not broken any functionality across all the Ciao components.
265
+
266
+
To quickly test any changes you make run verify.sh and observe no failures.
267
+
268
+
Prior to sumitting a change request to ciao, please run the BAT tests below
269
+
in addition to verify.sh to ensure your changes meet the ciao acceptance
270
+
criterion.
220
271
221
-
Meeting the goal originally outlined at the top of the page, build/setup/running your cluster all-in-one all transpires quickly and easily from the single script. The time needed for ./setup.sh and ./verify.sh to build ciao from source, configure it components into a virtual cluster, then launch and teardown containers and VMs is on the order of one minute total elapsed time.
272
+
Meeting the goal originally outlined at the top of the page, build/setup/running
273
+
your cluster all-in-one all transpires quickly and easily from the single
274
+
script. The time needed for ./setup.sh and ./verify.sh to build ciao from
275
+
source, configure it components into a virtual cluster, then launch and
276
+
teardown containers and VMs is on the order of one minute total elapsed time.
222
277
223
-
##Ongoing Usage
278
+
# Ongoing Usage
224
279
225
-
Once it's finished, the ```setup.sh``` script leaves behind a virtual cluster which can be used to perform manual tests. These tests are performed using the [ciao-cli](https://github.com/01org/ciao/blob/master/ciao-cli/README.md) tool. The ciao-cli tool requires that some environment variables be set up before it will work properly. These variables contain the URLs of the various ciao services and the credentials needed to access these services. The setup.sh script creates a shell source that contains valid values for the newly set up cluster. To initialise these variables you just need to source that file, e.g,
280
+
Once it's finished, the ```setup.sh``` script leaves behind a virtual cluster
281
+
which can be used to perform manual tests. These tests are performed using
282
+
the [ciao-cli](https://github.com/01org/ciao/blob/master/ciao-cli/README.md) tool.
283
+
284
+
The ciao-cli tool requires that some environment variables be set up before it
285
+
will work properly. These variables contain the URLs of the various ciao
286
+
services and the credentials needed to access these services. The setup.sh
287
+
script creates a shell source that contains valid values for the newly set up
288
+
cluster. To initialise these variables you just need to source that file, e.g,
226
289
227
290
```
228
291
. ~/local/demo.sh
@@ -236,9 +299,10 @@ ciao-cli workload list
236
299
237
300
# Running ciao-webui
238
301
239
-
The easiest way to develop and run the ciao-webui is inside a VM built by ciao-down.
240
-
Not only does ciao-down download the web-ui code for you but it also downloads and
241
-
configures all of the dependencies needed to develop the ciao-webui, such as npm.
302
+
The easiest way to develop and run the ciao-webui is inside a VM built by
303
+
ciao-down. Not only does ciao-down download the web-ui code for you but it
304
+
also downloads and configures all of the dependencies needed to develop the
305
+
ciao-webui, such as npm.
242
306
243
307
To run the webui in a ciao-down VM simply execute the following commands
244
308
@@ -258,7 +322,10 @@ to start managing your cluster.
258
322
259
323
# Running the BAT tests
260
324
261
-
The ciao project includes a set of acceptance tests that must pass before each release is made. The tests perform various tasks such as listing workloads, creating and deleting instances, etc. These tests can be run inside the machine
325
+
The ciao project includes a set of acceptance tests that must pass before each
326
+
release is made. The tests perform various tasks such as listing workloads,
327
+
creating and deleting instances, etc. These tests can be run inside the
328
+
machine
262
329
263
330
```
264
331
# Source the demo.sh file if you have not already done so
@@ -275,6 +342,7 @@ To cleanup and tear down the cluster:
275
342
```
276
343
cd $GOPATH/src/github.com/01org/ciao/testutil/singlevm
277
344
#Cleanup any previous setup
345
+
. ~/local/demo.sh
278
346
./cleanup.sh
279
347
```
280
348
@@ -283,7 +351,9 @@ cd $GOPATH/src/github.com/01org/ciao/testutil/singlevm
283
351
- Does not work on Fedora due to default firewall rules.
0 commit comments