9
This tutorial demonstrates basic features of Ensemble from a user perspective.
10
An Ensemble user would typically be a devops or a sys-admin who is interested in
9
This tutorial demonstrates basic features of juju from a user perspective.
10
An juju user would typically be a devops or a sys-admin who is interested in
11
11
automated deployment and management of servers and services.
16
The first step for deploying an Ensemble system is to perform bootstrapping.
16
The first step for deploying an juju system is to perform bootstrapping.
17
17
Bootstrapping launches a utility instance that is used in all subsequent
18
18
operations to launch and orchestrate other instances::
22
22
Note that while the command should display a message indicating it has finished
23
23
successfully, that does not mean the bootstrapping instance is immediately
24
24
ready for usage. Bootstrapping an instance can require a couple of minutes. To
25
check on the status of the Ensemble deployment, we can use the status command::
25
check on the status of the juju deployment, we can use the status command::
29
29
If the bootstrapping node has not yet completed bootstrapping, the status
30
30
command may either mention the environment is not yet ready, or may display a
50
50
Note the following, machine "0" has been started. This is the bootstrapping
51
51
node and the first node to be started. The dns-name for the node is printed.
52
52
Also the EC2 instance-id is printed. Since no services are yet deployed to the
53
Ensemble system yet, the list of deployed services is empty
53
juju system yet, the list of deployed services is empty
58
While not a requirement, it is beneficial for the understanding of Ensemble to
59
start a debug-log session. Ensemble's debug-log provides great insight into the
58
While not a requirement, it is beneficial for the understanding of juju to
59
start a debug-log session. juju's debug-log provides great insight into the
60
60
execution of various hooks as they are triggered by various events. It is
61
61
important to understand that debug-log shows events from a distributed
62
62
environment (multiple-instances). This means that log lines will alternate
63
63
between output from different instances. To start a debug-log session, from a
64
64
secondary terminal issue::
67
67
INFO Connecting to environment.
68
68
INFO Enabling distributed debug log.
69
69
INFO Tailing logs - Ctrl-C to stop.
73
73
Deploying service units
74
74
-----------------------
76
Now that we have bootstrapped the Ensemble environment, and started the
76
Now that we have bootstrapped the juju environment, and started the
77
77
debug-log viewer, let's proceed by deploying a mysql service::
79
$ ensemble deploy --repository=examples mysql
79
$ juju deploy --repository=examples mysql
80
80
INFO Connecting to environment.
81
INFO Formula deployed as service: 'mysql'
81
INFO Charm deployed as service: 'mysql'
82
82
INFO 'deploy' command finished successfully
84
84
Checking the debug-log window, we can see the mysql service unit being
85
85
downloaded and started::
87
Machine:1: ensemble.agents.machine DEBUG: Downloading formula
87
Machine:1: juju.agents.machine DEBUG: Downloading charm
89
Machine:1: ensemble.agents.machine INFO: Started service unit mysql/0
89
Machine:1: juju.agents.machine INFO: Started service unit mysql/0
91
91
It is important to note the different debug levels. DEBUG is used for very
92
92
detailed logging messages, usually you should not care about reading such
93
93
messages unless you are trying to debug (hence the name) a specific problem.
94
94
INFO debugging level is used for slightly more important informational
95
messages. In this case, these messages are generated as the mysql formula's
95
messages. In this case, these messages are generated as the mysql charm's
96
96
hooks are being executed. Let's check the current status::
100
100
0: {dns-name: ec2-50-16-61-111.compute-1.amazonaws.com, instance-id: i-2a702745}
101
101
1: {dns-name: ec2-50-16-117-185.compute-1.amazonaws.com, instance-id: i-227e294d}
104
formula: local:mysql-11
104
charm: local:mysql-11
128
128
However we don't have to wait for it to configure, let's proceed deploying
131
$ ensemble deploy --repository=examples wordpress
131
$ juju deploy --repository=examples wordpress
133
133
Let's wait for a minute for all services to complete their configuration cycle and
134
134
get properly started, then issue a status command::
138
138
0: {dns-name: ec2-50-16-61-111.compute-1.amazonaws.com, instance-id: i-2a702745}
139
139
1: {dns-name: ec2-50-16-117-185.compute-1.amazonaws.com, instance-id: i-227e294d}
140
140
2: {dns-name: ec2-184-72-156-54.compute-1.amazonaws.com, instance-id: i-9c7e29f3}
143
formula: local:mysql-11
143
charm: local:mysql-11
163
163
-----------------
165
165
While mysql and wordpress service units have been started, they are still
166
isolated from each other. An important concept for Ensemble is connecting
167
various service units together to create a bigger ensemble! Adding a relation
166
isolated from each other. An important concept for juju is connecting
167
various service units together to create a bigger juju! Adding a relation
168
168
between service units causes hooks to trigger, in effect causing all service
169
169
units to collaborate and work together to reach the desired end state. Adding a
170
170
relation is extremely simple::
172
$ ensemble add-relation wordpress mysql
172
$ juju add-relation wordpress mysql
173
173
INFO Connecting to environment.
174
174
INFO Added mysql relation to all service units.
175
175
INFO 'add_relation' command finished successfully
177
Checking the Ensemble status we see that the db relation now exists with state
177
Checking the juju status we see that the db relation now exists with state
182
182
0: {dns-name: ec2-50-16-61-111.compute-1.amazonaws.com, instance-id: i-2a702745}
183
183
1: {dns-name: ec2-50-16-117-185.compute-1.amazonaws.com, instance-id: i-227e294d}
184
184
2: {dns-name: ec2-184-72-156-54.compute-1.amazonaws.com, instance-id: i-9c7e29f3}
187
formula: local:mysql-11
187
charm: local:mysql-11
188
188
relations: {db: wordpress}
208
208
Tracing hook execution
209
209
----------------------
211
An Ensemble user should never have to trace the execution order of hooks,
211
An juju user should never have to trace the execution order of hooks,
212
212
however if you are the kind of person who enjoys looking under the hood, this
213
213
section is for you. Understanding hook order execution, the parallel nature of
214
214
hook execution across instances, and how relation-set in a hook can trigger the
215
215
execution of another hook is quite interesting and provides insight into
218
Here are a few important messages from the debug-log of this Ensemble run. The
218
Here are a few important messages from the debug-log of this juju run. The
219
219
date field has been deliberately left in this log, in order to understand the
220
220
parallel nature of hook execution.
223
223
* The time the log message was generated
224
224
* Which service unit is causing the log message (for example mysql/0)
225
225
* The message logging level. In this run DEBUG messages are generated by the
226
Ensemble core engine, while WARNING messages are generated by calling
227
ensemble-log from inside formulas (which you can read in the examples
226
juju core engine, while WARNING messages are generated by calling
227
juju-log from inside charms (which you can read in the examples
230
230
Let's view select debug-log messages which can help understand the execution
249
249
14:29:45,688 unit:wordpress/0: unit.hook.api WARNING: Restarting apache2 service
253
253
--------------------
255
255
Assuming your blog got really popular, is having high load and you decided to
256
scale it up (it's a cloud deployment after all). Ensemble makes this magically
256
scale it up (it's a cloud deployment after all). juju makes this magically
257
257
easy. All what is needed is::
259
$ ensemble add-unit wordpress
259
$ juju add-unit wordpress
260
260
INFO Connecting to environment.
261
261
INFO Unit 'wordpress/1' added to service 'wordpress'
262
262
INFO 'add_unit' command finished successfully
265
265
0: {dns-name: ec2-50-16-61-111.compute-1.amazonaws.com, instance-id: i-2a702745}
266
266
1: {dns-name: ec2-50-16-117-185.compute-1.amazonaws.com, instance-id: i-227e294d}
297
297
the database required has already been created and thus decides all needed
298
298
configuration has already been done. On the other hand wordpress/1 reads
299
299
service settings from mysql/0 and starts configuring itself and joining the
300
ensemble. Let's review a short version of debug-log for adding wordpress/1::
300
juju. Let's review a short version of debug-log for adding wordpress/1::
302
302
14:36:19,755 unit:mysql/0: hook.scheduler DEBUG: executing hook for wordpress/1:joined
303
303
14:36:19,755 unit:mysql/0: unit.relation.lifecycle DEBUG: Executing hook db-relation-joined
317
317
Destroying the environment
318
318
--------------------------
320
Once you are done with an Ensemble deployment, you need to terminate
320
Once you are done with an juju deployment, you need to terminate
321
321
all running instances in order to stop paying for them. The
322
322
destroy-environment command will terminate all running instances in an
325
$ ensemble destroy-environment
325
$ juju destroy-environment
327
Ensemble will ask for user confirmation before proceeding as this
327
juju will ask for user confirmation before proceeding as this
328
328
command will destroy service data in the environment as well.
added
removed
docs/source/user-tutorial.rst
