Skip to content

Commit 703a468

Browse files
teoteo
committed
[coconut] Add README
1 parent d9a8d7a commit 703a468

2 files changed

Lines changed: 176 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,4 @@
55
1) [Building instructions](hacking/BUILDING.md)
66
2) [Setting up development environment](hacking/DCOS.md)
77
3) [Running O² Control](hacking/RUNNING.md)
8+
4) [Using `coconut`](coconut/README.md)

‎coconut/README.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# `coconut` - the O² control and configuration utility
2+
3+
The O² **co**ntrol and **con**figuration **ut**ility is a command line program for interacting with the O²
4+
Control core.
5+
6+
## Configuration file
7+
8+
`coconut` can be used with no config file, and by default it will look for a running O² Control
9+
core at `127.0.0.1:47102`.
10+
11+
You can check the local `coconut` configuration with
12+
```bash
13+
$ coconut about
14+
```
15+
16+
If no config file is used, the previous command will print out `config: builtin`.
17+
18+
To override this, create a file `~/.config/coconut/settings.yaml` and fill it in along these lines:
19+
```yaml
20+
21+
---
22+
endpoint: "127.0.0.1:47102"
23+
config_endpoint: "consul://some-host-with-consul:8500" # or: "file:///path/to/o2control-core/config.yaml"
24+
log:
25+
#values: panic fatal error warning info debug
26+
level: info
27+
```
28+
29+
## Using `coconut`
30+
31+
`coconut` provides context-sensitive help at every step, including when trying to execute an incomplete command.
32+
The best way to familiarize yourself with it is to simply run `$ coconut`, see what it says and try out
33+
the offered subcommands.
34+
35+
At any step, you can type `$ coconut help <subcommand>` to get information on what you can do and how, for example:
36+
37+
```bash
38+
$ coconut help environment list
39+
The environment list command shows a list of currently active environments.
40+
This includes O² environments in any state.
41+
42+
Usage:
43+
coconut environment list [flags]
44+
45+
Aliases:
46+
list, ls, l
47+
48+
Flags:
49+
-h, --help help for list
50+
51+
Global Flags:
52+
--config string configuration file (default $HOME/.config/coconut/settings.yaml)
53+
--config_endpoint string O² Configuration endpoint as PROTO://HOST:PORT (default "consul://127.0.0.1:8500")
54+
--endpoint string O² Control endpoint as HOST:PORT (default "127.0.0.1:47102")
55+
-v, --verbose show verbose output for debug purposes
56+
57+
```
58+
59+
Assuming there's a running O² Control core and `coconut` is correctly configured, the following command should
60+
return some details on the O² Control core:
61+
62+
```bash
63+
$ coconut info
64+
O² Control core running on 127.0.0.1:47102
65+
framework id: 1f303909-7beb-4bd2-800d-d71470e211d4-0078
66+
environments count: 0
67+
roles count: 0
68+
global state: CONNECTED
69+
```
70+
71+
The global state is `CONNECTED`, which is good, because it means the core is up and talking to the
72+
resource management system (Apache Mesos). No environments and roles running yet, fair enough.
73+
74+
### Creating an environment
75+
76+
If you started the core with the provided `config.yaml`, it should come preloaded with some FairMQ examples.
77+
The main subcommand for dealing with environments is (unsurprisingly) `environment`. Most subcommands have
78+
shortened variants, so you might as well type `env` or `e`. Let's see what's running.
79+
```bash
80+
$ coconut env list
81+
no environments running
82+
```
83+
How do we create one? We can always ask `coconut`.
84+
```bash
85+
$ coconut help env create
86+
The environment create command requests from O² Control the
87+
creation of a new O² environment.
88+
89+
Usage:
90+
coconut environment create [flags]
91+
92+
Aliases:
93+
create, new, c, n
94+
95+
Flags:
96+
-h, --help help for create
97+
-w, --workflow string workflow to be loaded in the new environment
98+
# ...
99+
```
100+
101+
Note that if your `coconut` instance is configured correctly to point to the core's configuration (either Consul
102+
or file), you can use the low level `dump` subcommand to list the available workflow templates.
103+
104+
```bash
105+
$ coconut config dump /o2/control/workflows
106+
```
107+
108+
Let's create an environment by loading the workflow template for the FairMQ 1-n-1 example.
109+
This will take a few seconds.
110+
```bash
111+
$ coconut env create -w fairmq-ex-1-n-1
112+
new environment created
113+
environment id: 8132d249-e1b4-11e8-9f09-a08cfdc880fc
114+
state: CONFIGURED
115+
```
116+
117+
Boom. All environments transition to `CONFIGURED` immediately after creation.
118+
This corresponds to the `READY` state for a FairMQ process, so a lot has already happened behind the scenes.
119+
120+
```bash
121+
$ coconut env list
122+
ID | CREATED | STATE
123+
+--------------------------------------+-------------------------+------------+
124+
8132d249-e1b4-11e8-9f09-a08cfdc880fc | 2018-11-06 12:10:01 CET | CONFIGURED
125+
```
126+
Take note of the environment ID, as it's the primary key for other environment operations.
127+
128+
We can also check what tasks are currently running.
129+
130+
```bash
131+
$ coconut role list
132+
NAME | HOSTNAME | LOCKED
133+
+----------------------------------------------------------------+----------------+--------+
134+
fairmq-ex-1-n-1-processor#813a7311-e1b4-11e8-9f09-a08cfdc880fc | 192.168.65.131 | true
135+
fairmq-ex-1-n-1-processor#813a8b57-e1b4-11e8-9f09-a08cfdc880fc | 192.168.65.131 | true
136+
fairmq-ex-1-n-1-sink#8138df27-e1b4-11e8-9f09-a08cfdc880fc | 192.168.65.131 | true
137+
fairmq-ex-1-n-1-sampler#813a2cb6-e1b4-11e8-9f09-a08cfdc880fc | 192.168.65.131 | true
138+
fairmq-ex-1-n-1-processor#813a4945-e1b4-11e8-9f09-a08cfdc880fc | 192.168.65.131 | true
139+
fairmq-ex-1-n-1-processor#813a5e7a-e1b4-11e8-9f09-a08cfdc880fc | 192.168.65.131 | true
140+
```
141+
142+
### Controlling an environment
143+
144+
Let's start the data flow. If all goes well, `START_ACTIVITY` takes us to `RUNNING`.
145+
146+
```bash
147+
$ coconut env control 8132d249-e1b4-11e8-9f09-a08cfdc880fc --event START_ACTIVITY
148+
transition complete
149+
environment id: 8132d249-e1b4-11e8-9f09-a08cfdc880fc
150+
state: RUNNING
151+
```
152+
153+
We can also query the state of the environment.
154+
155+
```bash
156+
$ coconut env show 8132d249-e1b4-11e8-9f09-a08cfdc880fc
157+
environment id: 8132d249-e1b4-11e8-9f09-a08cfdc880fc
158+
created: 2018-11-06 12:10:01 CET
159+
state: RUNNING
160+
roles: fairmq-ex-1-n-1-processor#813a8b57-e1b4-11e8-9f09-a08cfdc880fc, fairmq-ex-1-n-1-processor#813a7311-e1b4-11e8-9f09-a08cfdc880fc, fairmq-ex-1-n-1-processor#813a5e7a-e1b4-11e8-9f09-a08cfdc880fc, fairmq-ex-1-n-1-processor#813a4945-e1b4-11e8-9f09-a08cfdc880fc, fairmq-ex-1-n-1-sampler#813a2cb6-e1b4-11e8-9f09-a08cfdc880fc, fairmq-ex-1-n-1-sink#8138df27-e1b4-11e8-9f09-a08cfdc880fc
161+
```
162+
163+
And then we go back.
164+
```bash
165+
$ coconut e t 8132d249-e1b4-11e8-9f09-a08cfdc880fc -e STOP_ACTIVITY
166+
transition complete
167+
environment id: 8132d249-e1b4-11e8-9f09-a08cfdc880fc
168+
state: CONFIGURED
169+
```
170+
171+
As of 11/2018 InfoLogger integration is work in progress, so the best way to check what's up with a specific
172+
task is with the Mesos GUI.
173+
On the DC/OS Vagrant test cluster, this is accessible at [http://m1.dcos/mesos/]().
174+
Pick the correct task by ID, Name, State, etc. and click on *Sandbox* in the rightmost column, and then open
175+
`stderr`.

0 commit comments

Comments
 (0)