Skip to content
Permalink
Browse files
Update docs to match the new Brooklyn UI
  • Loading branch information
tbouron committed Jul 20, 2018
1 parent 29c1168 commit 721b55b67c138e63dc6cc7e013603373483dc9c8
Show file tree
Hide file tree
Showing 51 changed files with 52 additions and 68 deletions.
@@ -35,10 +35,10 @@ There are four blueprints that make up this application. Each of them are used t
* [ELK](example_yaml/brooklyn-elk-catalog.bom)

#### Running the example
First, add all four blueprints to the Brooklyn Catalog. This can be done by clicking the 'Catalog' tab, clicking the '+'
symbol and pasting the YAML. Once this is done, click the 'Application' tab, then the '+' button to bring up the add
application wizard. A new Catalog application will be available called 'ELK Stack'. Using the add application wizard,
you should be able to deploy an ELK stack to a location of your choosing. Alternatively use the `br` Brooklyn
First, add all four blueprints to the Brooklyn Catalog. This can be done by going to the "Catalog" module, then clicking the
buttom "Upload to catalog" and selecting the above blueprints (or drag-and-drop them) Once this is done, search for an
entity called "ELK Stack". You will be able to deploy it by clicking on the "Deploy" button from the details page.
Note that you can also perform this operation from the quick launch panel on the homepage. Alternatively use the `br` Brooklyn
command line tool and add the files with `br catalog add`.

#### Exploring the example
@@ -4,14 +4,25 @@ title: Catalog Management

### Catalog Management

The Catalog tab in the web console will show all versions of catalog items,
The Catalog module (from the tile on the homepage, or the module switch on the top right) in the web console will show all versions of catalog items,
and allow you to add new items.


#### Adding to the Catalog

On the UI the "add" button <img src="images/add-to-catalog.png" width="24" alt="add-to-catalog" /> at the top of the menu panel allows the
addition of new Applications to the catalog, via YAML, and of new Locations.
There are three ways of adding items to the catalog from the UI.

1. **From the Catalog Module**: Click on the "Upload to catalog" button located on the top right corner then follow the
instructions. Alternatively, you can directly drag and drop items on the screen. This will accept `*.bom`, `*.jar` and `*.zip` files.

2. **From the Blueprint Composer module**:
If you have composed a blueprint on the fly in the Blueprint Composer, you can save it into the catalog by clicking on the
"Add to catalog button" located on the bottom right on the screen. A modal will then be displayed which will ask you for the
required metadata regarding this new item.

3. **From the Blueprint Importer module**:
If you already have catalog items, you can paste them into the importer editor then click on the "Import button".
This allows you to import any types of items, including locations.

In addition to the GUI, items can be added to the catalog via the REST API
with a `POST` of the YAML file to `/v1/catalog` endpoint.
@@ -31,7 +42,7 @@ br catalog add /path/to/riak.catalog.bom

#### Deleting from the Catalog

On the UI, if an item is selected, a 'Delete' button in the detail panel can be used to delete it from the catalog.
On the UI, if you are viewing a bundle page, a "Delete" button can be used to delete it from the catalog.

Using the REST API, you can delete a versioned item from the catalog using the corresponding endpoint.
For example, to delete the item with id `datastore` and version `1.0` with `curl`:
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
@@ -6,8 +6,8 @@ title: Templates and the Add-Application Wizard

A `template` is a full application. It consists of one or more entities inside an application
(though this is also composable: it can be used as part of another application).
When a `template` is added to the catalog, the blueprint will appear in the 'Create Application' dialog
as shown here:
When a `template` is added to the catalog, the blueprint will appear in quick launch on the homepage. A click on these
items will let you quickly deploy them as shown here:

[![MySQL in Brooklyn Catalog](mysql-in-catalog-w700.png "MySQL in Brooklyn Catalog")](mysql-in-catalog.png)

@@ -27,9 +27,9 @@ Here's a very simple YAML blueprint plan, to explain the structure:
This is the meat of the blueprint plan, as you'll see below.

Finally, the clipboard in the top-right corner of the example plan box above (hover your cursor over the box) lets you easily copy-and-paste into the web-console:
simply [download and launch]({{book.path.docs}}/start/running.md) Brooklyn,
then in the "Create Application" dialog at the web console
(usually [http://127.0.0.1:8081/](http://127.0.0.1:8081/), paste the copied YAML into the "Yaml" tab of the dialog and press "Finish".
simply [download and launch]({{book.path.docs}}/start/running.md) Brooklyn, open a new browser window (usually) at [http://127.0.0.1:8081/](http://127.0.0.1:8081/).
Click on the tile "Blueprint Composer", then on the double-arrow located on the top right of the screen (to switch to the YAML mode),
paste the copied YAML into the editor and press "Deploy".
There are several other ways to deploy, including `curl` and via the command-line,
and you can configure users, https, persistence, and more,
as described [in the ops guide]({{book.path.docs}}/ops/index.md).
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
@@ -5,7 +5,10 @@ title: Deploying Blueprints

## Launching from a Blueprint

When you first access the web console on [http://127.0.0.1:8081](http://127.0.0.1:8081) you will be requested to create your first application.
When you first access the web console on [http://127.0.0.1:8081](http://127.0.0.1:8081) you will be greeted by the GUI homepage
comprised of:
- the quick launch panel
- links to UI modules

We'll start by deploying an application via a YAML blueprint consisting of the following layers.

@@ -14,9 +17,10 @@ We'll start by deploying an application via a YAML blueprint consisting of the f
- Nginx load balancer
- Tomcat app server cluster

[![Brooklyn web console, showing the YAML tab of the Add Application dialog.](images/add-application-modal-yaml.png)](images/add-application-modal-yaml-large.png)
[![Brooklyn web console, showing the YAML tab of the Add Application dialog.](images/add-blueprint.png)](images/add-blueprint-large.png)

Switch to the YAML tab and copy the blueprint below into the large text box.
Go the "Blueprint Composer" and switch to the YAML editor view (by clicking on the double horizontal arrows icon on the top right corner)
and copy the blueprint below into the editor.

But *before* you submit it, modify the YAML to specify the location where the application will be deployed.

@@ -33,18 +37,18 @@ location:

**NOTE**: See __[Locations]({{book.path.docs}}/locations/index.md)__ in the Operations section of the User Guide for instructions on setting up alternate cloud providers, bring-your-own-nodes, or localhost targets, and storing credentials/locations in a file on disk rather than in the blueprint.

With the modified YAML in the dialog, click "Finish". The dialog will close and Brooklyn will begin deploying your
application. Your application will be shown as "Starting" on the web console's front page.
With the modified YAML, click on the "Deploy" button. Brooklyn will begin deploying your application and redirect you to the
"Application Inspector". In this screen, you will see your application as "Starting".

[![Brooklyn web console, showing the application starting.](images/home-app-starting.png)](images/home-app-starting-large.png)
[![Brooklyn web console, showing the application starting.](images/app-deploying.png)](images/app-deploying-large.png)

Depending on your choice of location it may take some time for the application nodes to start, the next page describes how you can monitor the progress of the application deployment and verify its successful deployment.

## Launching from the Catalog

Instead of pasting the YAML blueprint each time, it can be added to the Brooklyn Catalog where it will be accessible from the Catalog tab of the Create Application dialog.
Instead of pasting the YAML blueprint each time, it can be added to the Brooklyn Catalog where it will be accessible from the "Quick Launch" panel or "Catalog" and "Blueprint Composer" UI modules.

[![Viewing Catalog entries in Add Application dialog.](images/add-application-catalog-web-cluster-with-db.png)](images/add-application-catalog-web-cluster-with-db-large.png)
[![Viewing Catalog entries in Add Application dialog.](images/app-quicklaunch.png)](images/app-quicklaunch-large.png)

<!-- TODO: more detail for adding to catalog? but wait for persistence to be the default,
rather than extensively document default.catalog.bom.
Deleted file not rendered
Deleted file not rendered
Deleted file not rendered
Deleted file not rendered
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Deleted file not rendered
Deleted file not rendered
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
BIN +58.9 KB (200%) guide/ops/gui/images/my-web.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
@@ -2,9 +2,9 @@
title: Monitoring and Managing Applications
---

From the Home page, click on the application name or open the Applications tab.
From the Home page, go the "Application Inspector" module.

We can explore the management hierarchy of the application, which will show us the entities it is composed of. Starting from the application use the arrows to expand out the list of entities, or hover over the arrow until a menu popup is displayed so that you can select `Expand All`.
We can explore the management hierarchy of the application, which will show us the entities it is composed of. Starting from the application use the arrows to expand out the list of entities.

* My Web Cluster (A `BasicApplication`)
* My DB (A `MySqlNode`)
@@ -25,9 +25,9 @@ cluster that fail will be added. These are excluded from the load-balancer's tar

## Activities

The Activity tab allows us to drill down into the tasks each entity is currently executing or has recently completed. It is possible to drill down through all child tasks, and view the commands issued, along with any errors or warnings that occurred.
The "Activities" tab allows us to drill down into the tasks each entity is currently executing or has recently completed. It is possible to drill down through all child tasks, and view the commands issued, along with any errors or warnings that occurred.

For example clicking on the NginxController in the left hand tree and opening its Activity tab you can observe the 'start' task is 'In progress'.
For example clicking on the NginxController in the left hand tree and opening its Activity tab you can observe the 'start' task is 'Finished' and 'Successful', symbolised by a green circle.

**Note**: You may observe different tasks depending on how far your deployment has progressed).

@@ -37,7 +37,7 @@ Clicking on the 'start' task you can discover more details on the actions being

[![My DB Activities Step 2.](images/my-db-activities-step2.png)](images/my-db-activities-step2-large.png)

Continuing to drill down into the 'In progress' tasks you will eventually reach the currently active task where you can investigate the ssh command executed on the target node including the current stdin, stdout and stderr output.
Continuing to drill down into the tasks, you will eventually reach the some where you can investigate the ssh command executed on the target node including the current stdin, stdout and stderr output.

[![My DB Activities Step 3.](images/my-db-activities-step3.png)](images/my-db-activities-step3-large.png)

@@ -57,21 +57,21 @@ services:

Shortly after deployment, the entity fails with the following error:

`Failure running task ssh: customizing TomcatServerImpl{id=e1HP2s8x} (HmyPAozV):
Execution failed, invalid result 127 for customizing TomcatServerImpl{id=e1HP2s8x}`
`Error in task: ssh: customizing TomcatServerImpl{id=u9eof0hszp}
Execution failed, invalid result 127 for customizing TomcatServerImpl{id=u9eof0hszp}`

[![Script failure error in the Brooklyn debug console.](images/script-failure.png)](images/script-failure-large.png)

By selecting the `Activities` tab, we can drill into the task that failed. The list of tasks shown (where the
effectors are shown as top-level tasks) are clickable links. Selecting that row will show the details of
We can drill into the task that failed, directly by clicking the "More information" button or by selecting the `Activities` tab:
the list of tasks shown (where the effectors are shown as top-level tasks) are clickable links. Selecting that row will show the details of
that particular task, including its sub-tasks. We can eventually get to the specific sub-task that failed:

[![Task failure error in the Brooklyn debug console.](images/failed-task.png)](images/failed-task-large.png)

By clicking on the `stderr` link, we can see the script failed with the following error:
By expanding the `stderr` section, we can see the script failed with the following error:

```console
/tmp/brooklyn-20150721-132251052-l4b9-customizing_TomcatServerImpl_i.sh: line 10: mkrid: command not found
/tmp/brooklyn-20180720-121710003-Qh8k-customizing_TomcatServerImpl_i.sh: line 11: mkrid: command not found
```

This tells us *what* went wrong, but doesn't tell us *where*. In order to find that, we'll need to look at the
@@ -84,11 +84,10 @@ In this case, the stack trace is limited to the thread that was used to execute
Failed after 40ms

STDERR
/tmp/brooklyn-20150721-132251052-l4b9-customizing_TomcatServerImpl_i.sh: line 10: mkrid: command not found

/tmp/brooklyn-20180720-121710003-Qh8k-customizing_TomcatServerImpl_i.sh: line 11: mkrid: command not found

STDOUT
Executed /tmp/brooklyn-20150721-132251052-l4b9-customizing_TomcatServerImpl_i.sh, result 127: Execution failed, invalid result 127 for customizing TomcatServerImpl{id=e1HP2s8x}
Executed /tmp/brooklyn-20180720-121710003-Qh8k-customizing_TomcatServerImpl_i.sh, result 127: Execution failed, invalid result 127 for customizing TomcatServerImpl{id=u9eof0hszp}

java.lang.IllegalStateException: Execution failed, invalid result 127 for customizing TomcatServerImpl{id=e1HP2s8x}
at org.apache.brooklyn.entity.software.base.lifecycle.ScriptHelper.logWithDetailsAndThrow(ScriptHelper.java:390)
@@ -411,14 +410,9 @@ AttributeSensor<String> CONNECTOR_STATUS =

Let's go back to the Brooklyn debug console and look for the `webapp.tomcat.connectorStatus`:

[![Sensors view in the Brooklyn debug console.](images/jmx-sensors.png)](images/jmx-sensors-large.png)

As the sensor is not shown, it's likely that it's simply null or not set. We can check this by clicking
the "Show/hide empty records" icon (highlighted in yellow above):

[![All sensors view in the Brooklyn debug console.](images/jmx-sensors-all.png)](images/jmx-sensors-all-large.png)
[![Sensors view in the Brooklyn debug console.](images/jmx-sensors-connector.png)](images/jmx-sensors-connector-large.png)

We know from previous steps that the installation and launch scripts completed, and we know the procecess is running,
The sensor value is null or not set. We know from previous steps that the installation and launch scripts completed, and we know the procecess is running,
but we can see here that the server is not responding to JMX requests. A good thing to check here would be that the
JMX port is not being blocked by iptables, firewalls or security groups
(see the [troubleshooting connectivity guide]({{book.path.docs}}/ops/troubleshooting/connectivity.md)).
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Deleted file not rendered
Deleted file not rendered
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
@@ -48,11 +48,7 @@ set of attributes will vary between different entity types.

[![Sensors view in the Brooklyn debug console.](images/jmx-sensors.png)](images/jmx-sensors-large.png)

Note that null (or not set) sensors are hidden by default. You can click on the `Show/hide empty records`
icon (highlighted in yellow above) to see these sensors as well.

The sensors view is also tabulated. You can configure the numbers of sensors shown per page
(at the bottom). There is also a search bar (at the top) to filter the sensors shown.
There is also a search bar (at the top) to filter the sensors shown.


### Activity View

This file was deleted.

0 comments on commit 721b55b

Please sign in to comment.