You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@brooklyn.apache.org by aledsage <gi...@git.apache.org> on 2014/12/23 15:35:49 UTC
[GitHub] incubator-brooklyn pull request: docs for catalog maintenance
GitHub user aledsage opened a pull request:
https://github.com/apache/incubator-brooklyn/pull/423
docs for catalog maintenance
Buids on (and replaces https://github.com/apache/incubator-brooklyn/pull/399).
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/aledsage/incubator-brooklyn nakomis-copy/docs/catalog-maintenance
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/incubator-brooklyn/pull/423.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #423
----
commit 79cbc96e0e7154ef78bbb4b1c925102126d38f26
Author: Martin Harris <gi...@nakomis.com>
Date: 2014-12-16T16:22:47Z
Adds basic instructions for adding blueprints to and removing blueprints from the catalog
commit f6e69cc9d9d4038263543a41327f3192df9fc438
Author: Martin Harris <gi...@nakomis.com>
Date: 2014-12-19T12:07:35Z
Rebased and relocated to new guide locations
commit d4b7be03a3405c1aea1e946ddebab0901196733a
Author: Martin Harris <gi...@nakomis.com>
Date: 2014-12-19T14:07:52Z
Updated catalog maintenance docs as per PR comments
commit 06102d82bae34134159b8e85207a48e0e80e8e9a
Author: Aled Sage <al...@gmail.com>
Date: 2014-12-23T14:29:43Z
docs for catalog: review comments
----
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: docs for catalog maintenance
Posted by ahgittin <gi...@git.apache.org>.
Github user ahgittin commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/423#discussion_r22217197
--- Diff: docs/guide/use/guide/defining-applications/catalog-maintenance.md ---
@@ -0,0 +1,115 @@
+---
+title: Catalog Maintenance
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, catalog-maintenance]
+---
+
+In addition to deploying [YAML blueprints](creating-yaml.md) directly through the web console, it is possible
+to add YAML blueprints to the catalog via Brooklyn's REST API.
+
+The catalog is a collection of versioned blueprints, which can be deployed directly or referenced
+by other blueprints. Blueprints in the catalog can be deployed via the Brooklyn REST API, or from
+the web-console's 'Catalog' section of the 'Create Application' dialog box.
+
+All YAML blueprints added to the catalog must also contain a `brooklyn.catalog` section.
+
+For a blueprint to be accessible via the 'Create Application' dialog, it must be an Application
+(i.e. the entity at the root of the blueprint must implement `brooklyn.entity.Application`).
+
+<!--
+TODO: Add section that explains how to add plain entities to the catalog and use them either from the App Wizard,
+(and entity UI) or embed the catalog id + version in another YAML
+-->
+
+Let's take the following YAML as a starting point. We will convert it for adding to the catalog,
+such that it will usable through the 'Create Application' dialog.
+
+{% highlight yaml %}
+location: localhost
+
+name: MySQL Database
+services:
+- type: brooklyn.entity.database.mysql.MySqlNode
+ brooklyn.config:
+ datastore.creation.script.url: classpath://visitors-creation-script.sql
+{% endhighlight %}
+
+The first thing we need to do is add a root element that extends `brooklyn.entity.Application`. As we don't require any
--- End diff --
this isn't necessary -- if the root is a non-app it does the right thing (wrap in an app)
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: docs for catalog maintenance
Posted by ahgittin <gi...@git.apache.org>.
Github user ahgittin commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/423#discussion_r22217132
--- Diff: docs/use/guide/defining-applications/toc.json ---
@@ -0,0 +1,21 @@
+[{ "title": "Basic Concepts",
--- End diff --
this file should be removed -- redundant with same file under `docs/guide/use/...`
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: docs for catalog maintenance
Posted by ahgittin <gi...@git.apache.org>.
Github user ahgittin commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/423#discussion_r22217303
--- Diff: docs/guide/use/guide/defining-applications/catalog-maintenance.md ---
@@ -0,0 +1,115 @@
+---
+title: Catalog Maintenance
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, catalog-maintenance]
+---
+
+In addition to deploying [YAML blueprints](creating-yaml.md) directly through the web console, it is possible
+to add YAML blueprints to the catalog via Brooklyn's REST API.
+
+The catalog is a collection of versioned blueprints, which can be deployed directly or referenced
+by other blueprints. Blueprints in the catalog can be deployed via the Brooklyn REST API, or from
+the web-console's 'Catalog' section of the 'Create Application' dialog box.
+
+All YAML blueprints added to the catalog must also contain a `brooklyn.catalog` section.
+
+For a blueprint to be accessible via the 'Create Application' dialog, it must be an Application
+(i.e. the entity at the root of the blueprint must implement `brooklyn.entity.Application`).
+
+<!--
+TODO: Add section that explains how to add plain entities to the catalog and use them either from the App Wizard,
+(and entity UI) or embed the catalog id + version in another YAML
+-->
+
+Let's take the following YAML as a starting point. We will convert it for adding to the catalog,
+such that it will usable through the 'Create Application' dialog.
+
+{% highlight yaml %}
+location: localhost
+
+name: MySQL Database
+services:
+- type: brooklyn.entity.database.mysql.MySqlNode
+ brooklyn.config:
+ datastore.creation.script.url: classpath://visitors-creation-script.sql
+{% endhighlight %}
+
+The first thing we need to do is add a root element that extends `brooklyn.entity.Application`. As we don't require any
+custom application-specific logic, we can use the `brooklyn.entity.basic.BasicApplication` class. We can then add our
+MySqlNode as a child of the BasicApplication. When deploying a YAML blueprint via the YAML page of the 'Add Application'
+dialog, Brooklyn will do this automatically, however, in order to add our blueprint to the catalog, we will need to this
+manually as follows:
+
+{% highlight yaml %}
+location: localhost
+
+name: MySQL Database
+services:
+- type: brooklyn.entity.basic.BasicApplication
+ brooklyn.children:
+ - type: brooklyn.entity.database.mysql.MySqlNode
+ brooklyn.config:
+ datastore.creation.script.url: classpath://visitors-creation-script.sql
+{% endhighlight %}
+
+The next step is to remove the location (as the user will select the location in the GUI), and add a brooklyn.catalog
--- End diff --
say "typically" above, and that it is not necessary?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: docs for catalog maintenance
Posted by ahgittin <gi...@git.apache.org>.
Github user ahgittin commented on the pull request:
https://github.com/apache/incubator-brooklyn/pull/423#issuecomment-67957705
good to have this -- minor comments, merge whenever you want
(i'll be sorting out the docs over christmas btw)
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: docs for catalog maintenance
Posted by ahgittin <gi...@git.apache.org>.
Github user ahgittin commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/423#discussion_r22217385
--- Diff: docs/guide/use/guide/defining-applications/catalog-maintenance.md ---
@@ -0,0 +1,115 @@
+---
+title: Catalog Maintenance
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, catalog-maintenance]
+---
+
+In addition to deploying [YAML blueprints](creating-yaml.md) directly through the web console, it is possible
+to add YAML blueprints to the catalog via Brooklyn's REST API.
+
+The catalog is a collection of versioned blueprints, which can be deployed directly or referenced
+by other blueprints. Blueprints in the catalog can be deployed via the Brooklyn REST API, or from
+the web-console's 'Catalog' section of the 'Create Application' dialog box.
+
+All YAML blueprints added to the catalog must also contain a `brooklyn.catalog` section.
+
+For a blueprint to be accessible via the 'Create Application' dialog, it must be an Application
+(i.e. the entity at the root of the blueprint must implement `brooklyn.entity.Application`).
+
+<!--
+TODO: Add section that explains how to add plain entities to the catalog and use them either from the App Wizard,
--- End diff --
i'd explicitly call out two TODO's:
```
TODO: describe entity addition (this just covers app addition)
TODO: describe how to use the GUI
```
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: docs for catalog maintenance
Posted by ahgittin <gi...@git.apache.org>.
Github user ahgittin commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/423#discussion_r22217218
--- Diff: docs/guide/use/guide/defining-applications/catalog-maintenance.md ---
@@ -0,0 +1,115 @@
+---
+title: Catalog Maintenance
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, catalog-maintenance]
+---
+
+In addition to deploying [YAML blueprints](creating-yaml.md) directly through the web console, it is possible
+to add YAML blueprints to the catalog via Brooklyn's REST API.
+
+The catalog is a collection of versioned blueprints, which can be deployed directly or referenced
+by other blueprints. Blueprints in the catalog can be deployed via the Brooklyn REST API, or from
+the web-console's 'Catalog' section of the 'Create Application' dialog box.
+
+All YAML blueprints added to the catalog must also contain a `brooklyn.catalog` section.
+
+For a blueprint to be accessible via the 'Create Application' dialog, it must be an Application
+(i.e. the entity at the root of the blueprint must implement `brooklyn.entity.Application`).
+
+<!--
+TODO: Add section that explains how to add plain entities to the catalog and use them either from the App Wizard,
+(and entity UI) or embed the catalog id + version in another YAML
+-->
+
+Let's take the following YAML as a starting point. We will convert it for adding to the catalog,
+such that it will usable through the 'Create Application' dialog.
+
+{% highlight yaml %}
+location: localhost
+
+name: MySQL Database
+services:
+- type: brooklyn.entity.database.mysql.MySqlNode
+ brooklyn.config:
+ datastore.creation.script.url: classpath://visitors-creation-script.sql
+{% endhighlight %}
+
+The first thing we need to do is add a root element that extends `brooklyn.entity.Application`. As we don't require any
+custom application-specific logic, we can use the `brooklyn.entity.basic.BasicApplication` class. We can then add our
+MySqlNode as a child of the BasicApplication. When deploying a YAML blueprint via the YAML page of the 'Add Application'
+dialog, Brooklyn will do this automatically, however, in order to add our blueprint to the catalog, we will need to this
+manually as follows:
+
+{% highlight yaml %}
+location: localhost
+
+name: MySQL Database
+services:
--- End diff --
in other words, the next two lines can be removed
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: docs for catalog maintenance
Posted by asfgit <gi...@git.apache.org>.
Github user asfgit closed the pull request at:
https://github.com/apache/incubator-brooklyn/pull/423
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: docs for catalog maintenance
Posted by ahgittin <gi...@git.apache.org>.
Github user ahgittin commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/423#discussion_r22217263
--- Diff: docs/guide/use/guide/defining-applications/catalog-maintenance.md ---
@@ -0,0 +1,115 @@
+---
+title: Catalog Maintenance
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, catalog-maintenance]
+---
+
+In addition to deploying [YAML blueprints](creating-yaml.md) directly through the web console, it is possible
+to add YAML blueprints to the catalog via Brooklyn's REST API.
+
+The catalog is a collection of versioned blueprints, which can be deployed directly or referenced
+by other blueprints. Blueprints in the catalog can be deployed via the Brooklyn REST API, or from
+the web-console's 'Catalog' section of the 'Create Application' dialog box.
+
+All YAML blueprints added to the catalog must also contain a `brooklyn.catalog` section.
+
+For a blueprint to be accessible via the 'Create Application' dialog, it must be an Application
+(i.e. the entity at the root of the blueprint must implement `brooklyn.entity.Application`).
+
+<!--
+TODO: Add section that explains how to add plain entities to the catalog and use them either from the App Wizard,
+(and entity UI) or embed the catalog id + version in another YAML
+-->
+
+Let's take the following YAML as a starting point. We will convert it for adding to the catalog,
+such that it will usable through the 'Create Application' dialog.
+
+{% highlight yaml %}
+location: localhost
+
+name: MySQL Database
+services:
+- type: brooklyn.entity.database.mysql.MySqlNode
+ brooklyn.config:
+ datastore.creation.script.url: classpath://visitors-creation-script.sql
+{% endhighlight %}
+
+The first thing we need to do is add a root element that extends `brooklyn.entity.Application`. As we don't require any
+custom application-specific logic, we can use the `brooklyn.entity.basic.BasicApplication` class. We can then add our
+MySqlNode as a child of the BasicApplication. When deploying a YAML blueprint via the YAML page of the 'Add Application'
+dialog, Brooklyn will do this automatically, however, in order to add our blueprint to the catalog, we will need to this
+manually as follows:
+
+{% highlight yaml %}
+location: localhost
+
+name: MySQL Database
+services:
+- type: brooklyn.entity.basic.BasicApplication
+ brooklyn.children:
+ - type: brooklyn.entity.database.mysql.MySqlNode
+ brooklyn.config:
+ datastore.creation.script.url: classpath://visitors-creation-script.sql
+{% endhighlight %}
+
+The next step is to remove the location (as the user will select the location in the GUI), and add a brooklyn.catalog
+section to tell Brooklyn how the blueprint should be displayed in the 'Add Application' dialog:
+
+{% highlight yaml %}
+brooklyn.catalog:
+ id: MySQL
+ version: 1.0
+ iconUrl: classpath://mysql.png
+ description: MySql is an open source relational database management system (RDBMS)
+
+name: MySQL Database
+services:
+- type: brooklyn.entity.basic.BasicApplication
+ brooklyn.children:
+ - type: brooklyn.entity.database.mysql.MySqlNode
+ brooklyn.config:
+ datastore.creation.script.url: classpath://visitors-creation-script.sql
+{% endhighlight %}
+
+<!--
+TODO: Add section to explain that the brooklyn.catalog section can contain a libraries array, each item pointing to
+an OSGi bundle where the code for the blueprint is hosted. Every type from the blueprint will be searched for in the
+libraries first and then on the standard Brooklyn classpath.
+-->
+
+- The `id: MySQL` section specifies a unique ID used by Brooklyn to identify the catalog item. This ID is also passed to
+`UsageManager.UsageListener.onApplicationEvent` for metering purposes.
+- The `version: 1.0` section provides a unique version for the *blueprint*. NOTE: This is *not* the version of the software
+being installed (in this case MySQL).
+- The `iconUrl: classpath://...` is an optional, but recommended, section that allows you to provide a graphic to be
+displayed in the 'Add Application' dialog alongside the blueprint name. These image files should be placed in the
+`conf` folder to make them available at runtime.
+- The `description: ...` section allows you to give a free-format description of the blueprint, which is displayed in the
+'Add Application' dialog.
+
+To add the blueprint to the catalog, post the YAML file to Brooklyn's REST API by using the `curl` command as
+follows (substituting your own usename:password, URL and file path):
+
+{% highlight bash %}
+curl -u admin:password http://127.0.0.1:8081/v1/catalog --data-binary @/Users/martin/Desktop/ms.yaml
--- End diff --
does `@./ms.yaml` work? if so that would be preferable. (nothing against `martin` but no need to make this personal!)
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: docs for catalog maintenance
Posted by aledsage <gi...@git.apache.org>.
Github user aledsage commented on the pull request:
https://github.com/apache/incubator-brooklyn/pull/423#issuecomment-67959857
Thanks; have incorporated those comments except for the toc changes and the `@./ms.yaml` suggestion.
I also reduced it down to two YAML snippets: the simple one and the catalog one, rather than showing the intermediate text.
Merging now.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: docs for catalog maintenance
Posted by ahgittin <gi...@git.apache.org>.
Github user ahgittin commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/423#discussion_r22217340
--- Diff: docs/guide/use/guide/defining-applications/catalog-maintenance.md ---
@@ -0,0 +1,115 @@
+---
+title: Catalog Maintenance
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, catalog-maintenance]
+---
+
+In addition to deploying [YAML blueprints](creating-yaml.md) directly through the web console, it is possible
+to add YAML blueprints to the catalog via Brooklyn's REST API.
+
+The catalog is a collection of versioned blueprints, which can be deployed directly or referenced
+by other blueprints. Blueprints in the catalog can be deployed via the Brooklyn REST API, or from
+the web-console's 'Catalog' section of the 'Create Application' dialog box.
+
+All YAML blueprints added to the catalog must also contain a `brooklyn.catalog` section.
+
+For a blueprint to be accessible via the 'Create Application' dialog, it must be an Application
+(i.e. the entity at the root of the blueprint must implement `brooklyn.entity.Application`).
+
+<!--
+TODO: Add section that explains how to add plain entities to the catalog and use them either from the App Wizard,
+(and entity UI) or embed the catalog id + version in another YAML
+-->
+
+Let's take the following YAML as a starting point. We will convert it for adding to the catalog,
+such that it will usable through the 'Create Application' dialog.
+
+{% highlight yaml %}
+location: localhost
+
+name: MySQL Database
+services:
+- type: brooklyn.entity.database.mysql.MySqlNode
+ brooklyn.config:
+ datastore.creation.script.url: classpath://visitors-creation-script.sql
+{% endhighlight %}
+
+The first thing we need to do is add a root element that extends `brooklyn.entity.Application`. As we don't require any
--- End diff --
oh i got you -- it needs to be wrapped as an app in order to show up as an app in the catalog. otherwise it shows up as an entity. worth describing that?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---