docs: update catalog description
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/1f48765f Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/1f48765f Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/1f48765f Branch: refs/heads/master Commit: 1f48765fc3e868adcf541a1af0dc8f4f1cb8f792 Parents: f008e27 Author: Aled Sage <[email protected]> Authored: Fri Jan 16 18:22:58 2015 +0000 Committer: Aled Sage <[email protected]> Committed: Fri Jan 16 18:26:50 2015 +0000 ---------------------------------------------------------------------- docs/guide/ops/catalog/index.md | 174 ++++++++++++++++++++++------------- 1 file changed, 111 insertions(+), 63 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1f48765f/docs/guide/ops/catalog/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/ops/catalog/index.md b/docs/guide/ops/catalog/index.md index 4b05afc..8b14b65 100644 --- a/docs/guide/ops/catalog/index.md +++ b/docs/guide/ops/catalog/index.md @@ -1,102 +1,81 @@ --- -title: Catalog Maintenance +title: Catalog layout: website-normal -toc: ../guide_toc.json -categories: [use, guide, catalog-maintenance] --- -In addition to deploying [YAML blueprints](creating-yaml.html) 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 +Brooklyn has a 'catalog', which is a collection of versioned blueprints. +These 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`). -If just deploying via the REST API, then this is not necessary. <!-- -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 +TODO: Clean up confusion in terminology between Catalog item and Blueprint (and Java blueprint?)? --> -Let's take the following YAML as a starting point. - -{% 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 %} - -We will convert it for adding to the catalog, such that it will usable through the -'Create Application' dialog. +### Catalog items -The steps are therefore: +An item to be added to the catalog is defined in YAML. This looks like any other +YAML blueprint, but also has a `brooklyn.catalog` section giving appropriate metadata. -* Add a brooklyn.catalog section to give metadata about the version etc. This is also used - when displaying the blueprint in the 'Add Application' dialog. -* Remove the explicit location (as the user will typically select the location in the GUI). -* 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 via YAML at the REST API, this is not necessary as Brooklyn will do this - automatically). +An example is shown below. {% highlight yaml %} brooklyn.catalog: - id: MySQL + id: org.example.MySQL version: 1.0 iconUrl: classpath://mysql.png description: MySql is an open source relational database management system (RDBMS) + libraries: + - url: http://example.com/path/to/my-dependency-1.2.3.jar + - url: http://example.com/path/to/my-other-dependency-4.5.6.jar -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 +- type: brooklyn.entity.database.mysql.MySqlNode {% endhighlight %} -<!-- -TODO: Add documentation 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.* ---> - To explain the `brooklyn.catalog` section: -- 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 `id: MySQL` section specifies a unique ID used by Brooklyn to identify the catalog item. + Other blueprints can reference the catalog item using this id. - 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 `iconUrl: classpath://...` is an optional, but recommended, section that allows you to provide the URL of a graphic to be +displayed in the 'Add Application' dialog alongside the blueprint name. If using a URL of the form `classpath://...`, then +the image should be on Brooklyn's classpath (e.g. in the `conf` folder of the Brooklyn distro). - 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 +The `libraries` section references OSGi bundles required for the blueprint. It can be omitted if everything +required by the blueprint is already on the Brooklyn classpath. The URLs should be to stable OSGi bundles - +if the bundle at this URL changes then this could impact applications if the Brooklyn server is restarted +or fails over to a standby node. + + +To reference a catalog item in another blueprint, simply use its id and optionally its version number. +For example: + +{% highlight yaml %} +services: +- type: org.example.MySQL:1.0 +{% endhighlight %} + + +### Adding to the Catalog + +To add a catalog item 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 @/path/to/mysql-catalog.yaml {% endhighlight %} -This will add the blueprint to the catalog as shown here: -[](mysql-in-catalog.png) -If you attempt to run the curl command a second time, you will receive an error stating `Updating existing catalog entries is forbidden`. -To update the blueprint, you will need to change the version number in your yaml file before running the curl command -again. This will create a second blueprint. You can then delete the old version via the REST API, using its ID and version -as follows: + +### Deleting from the Catalog + +You can delete a versioned item from the catalog using the REST API. For example, to delete +the item with id `org.example.MySQL` and version `1.0`: {% highlight bash %} curl -u admin:password -X DELETE http://127.0.0.1:8081/v1/catalog/entities/MySQL/1.0 @@ -105,6 +84,75 @@ curl -u admin:password -X DELETE http://127.0.0.1:8081/v1/catalog/entities/MySQL **Note** Catalog items should not be deleted if there are running apps which were created using the same item. During rebinding the catalog item is used to reconstruct the entity. + +### Versioning + +Version numbers follow the OSGi convention. This can have a major, minor, micro and qualifier part. +For example, `1.0`. `1.0.1` or `1.0.1-20150101`. + +If you attempt to deploy the same version of a catalog item a second time, you will receive an +error stating `Updating existing catalog entries is forbidden`. +To update the blueprint, you will need to change the version number in your yaml file and then +POST the new YAML file. + +An exception to this rule is when no version is specified. Re-deploying will automatically +increment an internal version number for that catalog item. + +When referencing a blueprint, if a version number is not specified then the latest version will +be used when the application is deployed. + + +### Special requirements for 'Create Application' dialog + +For a blueprint in the catalog 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`). +In contrast, if a YAML blueprint is deployed direct via the REST API, then this is not necessary. + +For example, the MySql catalog item defined previously could be re-written to use a +`brooklyn.entity.basic.BasicApplication`, because no application-specific logic is +required other than to pass-through the start and stop commands. +the `MySqlNode` is added as a child of the `BasicApplication`. + +{% highlight yaml %} +brooklyn.catalog: + id: org.example.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 +{% endhighlight %} + +When added to the catalog via the HTTP POST command, the blueprint will appear in the 'Create Application' dialog +as shown here: + +[](mysql-in-catalog.png) + +When deploying a new version of a blueprint, the catalog will show both the previous and the new versions +of the blueprint. You may wish to delete the older version, assuming no applications currently running +are using that old version. + +<!-- +TODO: Should improve the 'Create Application' dialog, so that the two versions don't appear on the front page. +Currently they are indistinguisable, if they have the same description/icon. +--> + + +<!-- +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 +--> + +<!-- +TODO: Add documentation 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.* +--> + <!-- TODO: Add documentation about adding policies to the catalog, and explaining how to add items to the UI using the plus icon on the catalog tab*
