explain the top-level-blueprint catalog syntax, and discourage it addresses @neykov 's code review comment
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/a0ddec10 Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/a0ddec10 Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/a0ddec10 Branch: refs/heads/master Commit: a0ddec104b5741b188916960b95333cf1eca3a97 Parents: 1f529fc Author: Alex Heneveld <[email protected]> Authored: Sun Apr 12 23:02:22 2015 -0500 Committer: Alex Heneveld <[email protected]> Committed: Thu Apr 16 01:25:40 2015 -0500 ---------------------------------------------------------------------- docs/guide/ops/catalog/index.md | 37 ++++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 12 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a0ddec10/docs/guide/ops/catalog/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/ops/catalog/index.md b/docs/guide/ops/catalog/index.md index 9eeca9c..401979c 100644 --- a/docs/guide/ops/catalog/index.md +++ b/docs/guide/ops/catalog/index.md @@ -49,17 +49,6 @@ brooklyn.catalog: <blueprint-or-resource-definition> ``` -In some cases it is desired to define a default blueprint in a catalog file, -so that the catalog file can be used unchanged to launch an application. -To support this use case, the following format is also supported: - -```yaml -<blueprint-definition> -brooklyn.catalog: - <catalog-metadata> -``` - - #### Catalog Metadata @@ -93,7 +82,8 @@ In addition to the above fields, exactly **one** of the following is also requir - `items`: a list of catalog items, where each entry in the map follows the same schema as the `brooklyn.catalog` value, and the keys in these map override any metadata specified as a sibling of this `items` key (or, in the case of `libraries` they add to the list); - if there are references between items, then order is important, with forward references not supported. + if there are references between items, then order is important, + `items` are processed in order, depth-first, and forward references are not supported. The following optional catalog metadata is supported: @@ -204,6 +194,29 @@ The items this will install are: (This must be supplied after `riak-cluster`, because it refers to `riak-cluster`.) +#### Legacy Syntax + +The following legacy and experimental syntax is also supported: + +```yaml +<blueprint-definition> +brooklyn.catalog: + <catalog-metadata> +``` + +In this format, the `brooklyn.catalog` block is optional; +and an `id` in the `<blueprint-definition>` will be used to determine the catalog ID. +This is primarily supplied for OASIS CAMP 1.1 compatibility, +where the same YAML blueprint can be POSTed to the catalog endpoint to add to a catalog +or POSTed to the applications endpoint to deploy an instance. +(This syntax is discouraged as the latter usage, +POSTing to the applications endpoint, +will ignored the `brooklyn.catalog` information; +this means references to any `item` blocks in the `<catalog-metadata>` will not be resolved, +and any OSGi `libraries` defined there will not be loaded.) + + + ### Templates and the Add-Application Wizard When a `template` is added to the catalog, the blueprint will appear in the 'Create Application' dialog
