Merge lp:~marcoceppi/juju-core/sentry-docs into lp:juju-core/docs
- sentry-docs
- Merge into docs
Proposed by
Marco Ceppi
| Status: | Merged |
|---|---|
| Approved by: | Nick Veitch |
| Approved revision: | no longer in the source branch. |
| Merged at revision: | 221 |
| Proposed branch: | lp:~marcoceppi/juju-core/sentry-docs |
| Merge into: | lp:juju-core/docs |
| Diff against target: |
273 lines (+125/-29) 1 file modified
htmldocs/tools-amulet.html (+125/-29) |
| To merge this branch: | bzr merge lp:~marcoceppi/juju-core/sentry-docs |
| Related bugs: |
| Reviewer | Review Type | Date Requested | Status |
|---|---|---|---|
| charmers | Pending | ||
|
Review via email:
|
|||
Commit message
Description of the change
Add sentry documentation
To post a comment you must log in.
Preview Diff
[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
| 1 | === modified file 'htmldocs/tools-amulet.html' | |||
| 2 | --- htmldocs/tools-amulet.html 2014-01-09 17:58:56 +0000 | |||
| 3 | +++ htmldocs/tools-amulet.html 2014-01-21 18:21:00 +0000 | |||
| 4 | @@ -21,16 +21,8 @@ | |||
| 5 | 21 | </head> | 21 | </head> |
| 6 | 22 | <!--End-Head--> | 22 | <!--End-Head--> |
| 7 | 23 | 23 | ||
| 8 | 24 | |||
| 9 | 25 | |||
| 10 | 26 | |||
| 11 | 27 | |||
| 12 | 28 | |||
| 13 | 29 | |||
| 14 | 30 | <body class="resources"> | 24 | <body class="resources"> |
| 15 | 31 | |||
| 16 | 32 | <!--Header--> | 25 | <!--Header--> |
| 17 | 33 | |||
| 18 | 34 | <header class="banner global" role="banner"> | 26 | <header class="banner global" role="banner"> |
| 19 | 35 | <nav role="navigation" class="nav-primary nav-right"> | 27 | <nav role="navigation" class="nav-primary nav-right"> |
| 20 | 36 | <div class="logo"> | 28 | <div class="logo"> |
| 21 | @@ -108,7 +100,7 @@ | |||
| 22 | 108 | 100 | ||
| 23 | 109 | </div> | 101 | </div> |
| 24 | 110 | <div data-section="windows"> | 102 | <div data-section="windows"> |
| 26 | 111 | <p>Amulet is available via Pip:</p> | 103 | <p>Amulet is available via Pip:</p> |
| 27 | 112 | 104 | ||
| 28 | 113 | <pre class="prettyprint lang-bash">pip install amulet</pre> | 105 | <pre class="prettyprint lang-bash">pip install amulet</pre> |
| 29 | 114 | </div> | 106 | </div> |
| 30 | @@ -163,7 +155,7 @@ | |||
| 31 | 163 | <h2 id="functionality">Core functionality</h2> | 155 | <h2 id="functionality">Core functionality</h2> |
| 32 | 164 | <p>This section is deigned to outline the core functions of Amulet. Again, please refer to the developer documentation for an exhaustive list of functions and methods. | 156 | <p>This section is deigned to outline the core functions of Amulet. Again, please refer to the developer documentation for an exhaustive list of functions and methods. |
| 33 | 165 | 157 | ||
| 35 | 166 | <h3>amulet.deployer</h3> | 158 | <h3 id="amulet.deployer">amulet.deployer</h3> |
| 36 | 167 | 159 | ||
| 37 | 168 | <p>The Deployer module houses several classes for interacting and setting up an environment. These classes and methods are outlined below | 160 | <p>The Deployer module houses several classes for interacting and setting up an environment. These classes and methods are outlined below |
| 38 | 169 | 161 | ||
| 39 | @@ -186,11 +178,11 @@ | |||
| 40 | 186 | </p> | 178 | </p> |
| 41 | 187 | <p>Once an environment has been set up, deployer can still drive the environment outside of of juju-deployer. So the same commands (add, relate, configure, expose) will instead interact directly with the environment by using either the Juju API or the juju commands.</p> | 179 | <p>Once an environment has been set up, deployer can still drive the environment outside of of juju-deployer. So the same commands (add, relate, configure, expose) will instead interact directly with the environment by using either the Juju API or the juju commands.</p> |
| 42 | 188 | 180 | ||
| 44 | 189 | <h4 id="object">Class:</h4> | 181 | <h4 id="Deployment">Class:</h4> |
| 45 | 190 | <p><code>Deployment(juju_env=None, series='precise', sentries=True, juju_deployer='juju-deployer', sentry_template=None)</code></p> | 182 | <p><code>Deployment(juju_env=None, series='precise', sentries=True, juju_deployer='juju-deployer', sentry_template=None)</code></p> |
| 46 | 191 | 183 | ||
| 47 | 192 | <h4>Methods:</h4> | 184 | <h4>Methods:</h4> |
| 49 | 193 | <details><summary><code class="method">Deployment.add(service, charm=None, units=1)</code> | 185 | <details id="Deployment.add"><summary><code class="method">Deployment.add(service, charm=None, units=1)</code> |
| 50 | 194 | 186 | ||
| 51 | 195 | <p>Add a new service to the deployment schema.</p></summary> | 187 | <p>Add a new service to the deployment schema.</p></summary> |
| 52 | 196 | 188 | ||
| 53 | @@ -205,29 +197,29 @@ | |||
| 54 | 205 | d.add('personal-wp', charm='~marcoceppi/wordpress', units=2) | 197 | d.add('personal-wp', charm='~marcoceppi/wordpress', units=2) |
| 55 | 206 | </pre> | 198 | </pre> |
| 56 | 207 | </details> | 199 | </details> |
| 58 | 208 | <details><summary><code class="method">Deployment.build_relations()</code> | 200 | <details id="Deployment.build_relations"><summary><code class="method">Deployment.build_relations()</code> |
| 59 | 209 | 201 | ||
| 60 | 210 | <p>Private method invoked during deployer_map. Creates relation mapping.</p></summary></details> | 202 | <p>Private method invoked during deployer_map. Creates relation mapping.</p></summary></details> |
| 61 | 211 | 203 | ||
| 63 | 212 | <details><summary><code class="method">Deployment.build_sentries()</code> | 204 | <details id="Deployment.build_sentries"><summary><code class="method">Deployment.build_sentries()</code> |
| 64 | 213 | 205 | ||
| 65 | 214 | <p>Private method invoked during deployer_map. Creates sentries for services.</p> | 206 | <p>Private method invoked during deployer_map. Creates sentries for services.</p> |
| 66 | 215 | </summary></details> | 207 | </summary></details> |
| 68 | 216 | <details><summary><code class="method">Deployment.configure(service, **options)</code> | 208 | <details id="Deployment.configure"><summary><code class="method">Deployment.configure(service, **options)</code> |
| 69 | 217 | 209 | ||
| 70 | 218 | <p>Change configuration options for a service.</p></summary> | 210 | <p>Change configuration options for a service.</p></summary> |
| 71 | 219 | 211 | ||
| 72 | 220 | <ul><li><code>service</code> The service to configure.</li> | 212 | <ul><li><code>service</code> The service to configure.</li> |
| 74 | 221 | <li><code>**options</code> Seed with key=val.</li></ul> | 213 | <li><code>options</code> Dict of configuration options.</li></ul> |
| 75 | 222 | <pre class="prettyprint lang-python"> | 214 | <pre class="prettyprint lang-python"> |
| 76 | 223 | import amulet | 215 | import amulet |
| 77 | 224 | 216 | ||
| 78 | 225 | d = amulet.Deployment() | 217 | d = amulet.Deployment() |
| 79 | 226 | d.add('postgresql') | 218 | d.add('postgresql') |
| 81 | 227 | d.configure('postgresql', autovacuum=True, cluster_name='cname') | 219 | d.configure('postgresql', {'autovacuum': True, 'cluster_name': 'cname'}) |
| 82 | 228 | </pre> | 220 | </pre> |
| 83 | 229 | </details> | 221 | </details> |
| 85 | 230 | <details><summary><code class="method">Deployment.deployer_map(services, relations)</code> | 222 | <details id="Deployment.deployer_map"><summary><code class="method">Deployment.deployer_map(services, relations)</code> |
| 86 | 231 | 223 | ||
| 87 | 232 | <p>Create deployer file from provided services and relations.</p> | 224 | <p>Create deployer file from provided services and relations.</p> |
| 88 | 233 | </summary> | 225 | </summary> |
| 89 | @@ -236,7 +228,7 @@ | |||
| 90 | 236 | <li><code>relations</code> List of relations to map.</li> | 228 | <li><code>relations</code> List of relations to map.</li> |
| 91 | 237 | </ul> | 229 | </ul> |
| 92 | 238 | </details> | 230 | </details> |
| 94 | 239 | <details><summary><code class="method">Deployment.expose(service)</code> | 231 | <details id="Deployment.expose"><summary><code class="method">Deployment.expose(service)</code> |
| 95 | 240 | 232 | ||
| 96 | 241 | <p>Indicate if a service should be exposed after deployment.</p></summary> | 233 | <p>Indicate if a service should be exposed after deployment.</p></summary> |
| 97 | 242 | 234 | ||
| 98 | @@ -248,13 +240,13 @@ | |||
| 99 | 248 | d.add('varnish') | 240 | d.add('varnish') |
| 100 | 249 | d.expose('varnish') | 241 | d.expose('varnish') |
| 101 | 250 | </pre></details> | 242 | </pre></details> |
| 103 | 251 | <details><summary><code class="method">Deployment.load(deploy_cfg)</code> | 243 | <details id="Deployment.load"><summary><code class="method">Deployment.load(deploy_cfg)</code> |
| 104 | 252 | 244 | ||
| 105 | 253 | <p>Import an existing deployer object.</p> | 245 | <p>Import an existing deployer object.</p> |
| 106 | 254 | </summary> | 246 | </summary> |
| 107 | 255 | <ul><li><code>deploy_cfg</code> Already parsed deployer yaml/json file.</li></ul> | 247 | <ul><li><code>deploy_cfg</code> Already parsed deployer yaml/json file.</li></ul> |
| 108 | 256 | </details> | 248 | </details> |
| 110 | 257 | <details><summary><code class="method">Deployment.relate(*args)</code> | 249 | <details id="Deployment.relate"><summary><code class="method">Deployment.relate(*args)</code> |
| 111 | 258 | 250 | ||
| 112 | 259 | <p>Relate two services together.</p></summary> | 251 | <p>Relate two services together.</p></summary> |
| 113 | 260 | 252 | ||
| 114 | @@ -274,7 +266,7 @@ | |||
| 115 | 274 | </pre> | 266 | </pre> |
| 116 | 275 | </details> | 267 | </details> |
| 117 | 276 | 268 | ||
| 119 | 277 | <details><summary><code class="method">Deployment.setup(timeout=600)</code> | 269 | <details id="Deployment.setup"><summary><code class="method">Deployment.setup(timeout=600)</code> |
| 120 | 278 | 270 | ||
| 121 | 279 | <p>This will create the deployer mapping, create any sentries that are required, and execute juju-deployer with the generated mapping.</p></summary> | 271 | <p>This will create the deployer mapping, create any sentries that are required, and execute juju-deployer with the generated mapping.</p></summary> |
| 122 | 280 | 272 | ||
| 123 | @@ -294,7 +286,7 @@ | |||
| 124 | 294 | pass | 286 | pass |
| 125 | 295 | 287 | ||
| 126 | 296 | </pre></details> | 288 | </pre></details> |
| 128 | 297 | <h3>amulet.sentry</h3> | 289 | <h3 id="amulet.sentry">amulet.sentry</h3> |
| 129 | 298 | <p>Sentries are an additional service built in to the Deployment tool which allow an author the ability to dig deeper in to a deployment environment. This is done by adding a set of tools to each service/unit deployed via a subordinate charm and a final "relation sentry" charm is deployed which all relations are proxied through. In doing so you can inspect on each service/unit deployed as well as receive detailed information about what data is being sent by which units/service during a relation.</p> | 290 | <p>Sentries are an additional service built in to the Deployment tool which allow an author the ability to dig deeper in to a deployment environment. This is done by adding a set of tools to each service/unit deployed via a subordinate charm and a final "relation sentry" charm is deployed which all relations are proxied through. In doing so you can inspect on each service/unit deployed as well as receive detailed information about what data is being sent by which units/service during a relation.</p> |
| 130 | 299 | 291 | ||
| 131 | 300 | <p>Sentries can be accessed from within your deployment using the sentry object. Using the above example from ## Deployer, each service and unit can be accessed using the following:</p> | 292 | <p>Sentries can be accessed from within your deployment using the sentry object. Using the above example from ## Deployer, each service and unit can be accessed using the following:</p> |
| 132 | @@ -306,11 +298,120 @@ | |||
| 133 | 306 | d.add('mysql') | 298 | d.add('mysql') |
| 134 | 307 | d.setup() | 299 | d.setup() |
| 135 | 308 | 300 | ||
| 136 | 301 | d.sentry.wait() | ||
| 137 | 302 | |||
| 138 | 309 | d.sentry.unit['mysql/0'] | 303 | d.sentry.unit['mysql/0'] |
| 139 | 310 | d.sentry.unit['mediawiki/0'] | 304 | d.sentry.unit['mediawiki/0'] |
| 140 | 311 | </pre> | 305 | </pre> |
| 141 | 312 | <p>Sentries provide several methods for which you can use to gather information about an environment. The following are a few examples.</p> | 306 | <p>Sentries provide several methods for which you can use to gather information about an environment. The following are a few examples.</p> |
| 142 | 313 | 307 | ||
| 143 | 308 | <h4>Methods</h4> | ||
| 144 | 309 | |||
| 145 | 310 | <details id="amulet.sentry.wait"><summary><code class="method">wait(timeout=300)</code> | ||
| 146 | 311 | |||
| 147 | 312 | <p>Wait for all hooks to finish execution on deployment</p> | ||
| 148 | 313 | </summary> | ||
| 149 | 314 | <ul><li><code>timeout</code> Duration in seconds to wait before raising exception, default 300 seconds</li></ul> | ||
| 150 | 315 | |||
| 151 | 316 | <p>If timeout is met prior to ready state, <code>TimeoutError</code> is raised.</p> | ||
| 152 | 317 | </details> | ||
| 153 | 318 | |||
| 154 | 319 | <h3 id="amulet.sentry.unit">amulet.sentry.unit</h3> | ||
| 155 | 320 | <p>Each unit is assigned a <a href="#UnitSentry.from_unitdata">UnitSentry</a></p> | ||
| 156 | 321 | |||
| 157 | 322 | <h4 id="UnitSentry.from_unitdata">Class:</h4> | ||
| 158 | 323 | <p><code>UnitSentry.from_unitdata(unit, unit_data, port=9001, sentry=None)</code></p> | ||
| 159 | 324 | |||
| 160 | 325 | <ul> | ||
| 161 | 326 | <li><code>unit</code> - <code>service/#</code> formatted string of unit name</li> | ||
| 162 | 327 | <li><code>unit_data</code> - Object of unit status output</li> | ||
| 163 | 328 | <li><code>port</code> - Sentry port</li> | ||
| 164 | 329 | <li><code>sentry</code> - RelationSentry</li> | ||
| 165 | 330 | </ul> | ||
| 166 | 331 | |||
| 167 | 332 | <h4>Methods:</h4> | ||
| 168 | 333 | <details id="UnitSentry.directory"><summary><code class="method">UnitSentry.directory(dir)</code> | ||
| 169 | 334 | |||
| 170 | 335 | <p>See <a href='#UnitSentry.directory_stat'>UnitSentry.directory_stat()</a></p> | ||
| 171 | 336 | </summary></details> | ||
| 172 | 337 | |||
| 173 | 338 | <details id="UnitSentry.directory_contents"><summary><code class="method">UnitSentry.directory_contents(dir)</code> | ||
| 174 | 339 | |||
| 175 | 340 | <p>Return files and directories of directory</p> | ||
| 176 | 341 | </summary> | ||
| 177 | 342 | <ul><li><code>dir</code> Directory on remote machine</li></ul> | ||
| 178 | 343 | |||
| 179 | 344 | <p>Example of output</p> | ||
| 180 | 345 | |||
| 181 | 346 | <pre class="prettyprint">{'files': [] | ||
| 182 | 347 | 'directories': []}</pre> | ||
| 183 | 348 | </details> | ||
| 184 | 349 | |||
| 185 | 350 | <details id="UnitSentry.directory_stat"><summary><code class="method">UnitSentry.directory_stat(dir)</code> | ||
| 186 | 351 | |||
| 187 | 352 | <p>Return stat of directory</p> | ||
| 188 | 353 | </summary> | ||
| 189 | 354 | <ul><li><code>dir</code> Directory on remote machine</li></ul> | ||
| 190 | 355 | |||
| 191 | 356 | <p>Example of output</p> | ||
| 192 | 357 | |||
| 193 | 358 | <pre class="prettyprint">{'mtime': fs_stat.st_mtime, | ||
| 194 | 359 | 'size': fs_stat.st_size, | ||
| 195 | 360 | 'uid': fs_stat.st_uid, | ||
| 196 | 361 | 'gid': fs_stat.st_gid, | ||
| 197 | 362 | 'mode': fs_stat.st_mode}</pre> | ||
| 198 | 363 | </details> | ||
| 199 | 364 | |||
| 200 | 365 | <details id="UnitSentry.file"><summary><code class="method">UnitSentry.file(filename)</code> | ||
| 201 | 366 | |||
| 202 | 367 | <p>See <a href='#UnitSentry.file_stat'>UnitSentry.file_stat()</a></p> | ||
| 203 | 368 | </summary> | ||
| 204 | 369 | </details> | ||
| 205 | 370 | |||
| 206 | 371 | <details id="UnitSentry.file_contents"><summary><code class="method">UnitSentry.file_contents(filename)</code> | ||
| 207 | 372 | |||
| 208 | 373 | <p>Return contents of filename</p> | ||
| 209 | 374 | </summary> | ||
| 210 | 375 | <ul><li><code>filename</code> File on remote machine</li></ul> | ||
| 211 | 376 | </details> | ||
| 212 | 377 | |||
| 213 | 378 | <details id="UnitSentry.file_stat"><summary><code class="method">UnitSentry.file_stat(filename)</code> | ||
| 214 | 379 | |||
| 215 | 380 | <p>Return stat of path</p> | ||
| 216 | 381 | </summary> | ||
| 217 | 382 | <ul><li><code>filename</code> File on remote machine</li></ul> | ||
| 218 | 383 | |||
| 219 | 384 | <p>Example of output</p> | ||
| 220 | 385 | |||
| 221 | 386 | <pre class="prettyprint">{'mtime': fs_stat.st_mtime, | ||
| 222 | 387 | 'size': fs_stat.st_size, | ||
| 223 | 388 | 'uid': fs_stat.st_uid, | ||
| 224 | 389 | 'gid': fs_stat.st_gid, | ||
| 225 | 390 | 'mode': fs_stat.st_mode}</pre> | ||
| 226 | 391 | </details> | ||
| 227 | 392 | |||
| 228 | 393 | <details id="UnitSentry.relation"><summary><code class="method">UnitSentry.relation(from_rel, to_rel)</code> | ||
| 229 | 394 | |||
| 230 | 395 | <p>Return stat of path</p> | ||
| 231 | 396 | </summary> | ||
| 232 | 397 | <ul><li><code>from_rel</code> The relation of the unit eg <code>rel</code></li> | ||
| 233 | 398 | <li><code>to_rel</code> Service and relation connection, eg: <code>service:rel</code></li></ul> | ||
| 234 | 399 | |||
| 235 | 400 | <p>Output is an object of key, val relation data</p> | ||
| 236 | 401 | </details> | ||
| 237 | 402 | |||
| 238 | 403 | <details id="UnitSentry.run"><summary><code class="method">UnitSentry.run(command)</code> | ||
| 239 | 404 | |||
| 240 | 405 | <p>Execute specified command as root on remote machine</p> | ||
| 241 | 406 | </summary> | ||
| 242 | 407 | <ul><li><code>command</code> Shell command to execute</li></ul> | ||
| 243 | 408 | |||
| 244 | 409 | <p>Returns a tuple of output string and exit code</p> | ||
| 245 | 410 | |||
| 246 | 411 | <pre class="prettyprint">>>> d.sentry.unit['ubuntu/0'].run('whoami') | ||
| 247 | 412 | ('root', 0)</pre> | ||
| 248 | 413 | </details> | ||
| 249 | 414 | |||
| 250 | 314 | <h2 id="examples">Examples</h2> | 415 | <h2 id="examples">Examples</h2> |
| 251 | 315 | <p>Here are a few examples of Amulet tests</p> | 416 | <p>Here are a few examples of Amulet tests</p> |
| 252 | 316 | 417 | ||
| 253 | @@ -320,7 +421,7 @@ | |||
| 254 | 320 | <pre class="prettyprint lang-python"> | 421 | <pre class="prettyprint lang-python"> |
| 255 | 321 | #!/bin/bash | 422 | #!/bin/bash |
| 256 | 322 | 423 | ||
| 258 | 323 | sudo apt-get install install amulet python-requests | 424 | sudo apt-get install amulet python-requests |
| 259 | 324 | </pre> | 425 | </pre> |
| 260 | 325 | <h4>tests/01-simple</h4> | 426 | <h4>tests/01-simple</h4> |
| 261 | 326 | <pre class="prettyprint lang-python"> | 427 | <pre class="prettyprint lang-python"> |
| 262 | @@ -476,10 +577,5 @@ | |||
| 263 | 476 | </script> | 577 | </script> |
| 264 | 477 | <!--End-Scripts--> | 578 | <!--End-Scripts--> |
| 265 | 478 | 579 | ||
| 266 | 479 | |||
| 267 | 480 | |||
| 268 | 481 | |||
| 269 | 482 | |||
| 270 | 483 | |||
| 271 | 484 | </body></html> | 580 | </body></html> |
| 272 | 485 | 581 | ||
| 273 | 486 | \ No newline at end of file | 582 | \ No newline at end of file |
