From e1381183e0794894f2a4b11c9b74e9e4abbcd91e Mon Sep 17 00:00:00 2001 From: Aled Sage Date: Thu, 23 Jun 2016 09:07:46 +0100 Subject: [PATCH] Catalog format more consistent --- guide/java/gist_generator/gist_generator.bom | 4 +- guide/misc/osgi.md | 1 + guide/ops/catalog/index.md | 147 ++++++++++-------- guide/ops/externalized-configuration.md | 3 +- guide/yaml/entity-configuration.md | 8 +- .../brooklyn-elasticsearch-catalog.bom | 3 +- .../example_yaml/brooklyn-elk-catalog.bom | 55 ++++--- .../example_yaml/brooklyn-kibana-catalog.bom | 3 +- .../brooklyn-logstash-catalog.bom | 4 +- .../vanilla-bash-netcat-catalog.bom | 1 + 10 files changed, 131 insertions(+), 98 deletions(-) diff --git a/guide/java/gist_generator/gist_generator.bom b/guide/java/gist_generator/gist_generator.bom index 5be6b502..89effaf7 100644 --- a/guide/java/gist_generator/gist_generator.bom +++ b/guide/java/gist_generator/gist_generator.bom @@ -1,10 +1,10 @@ brooklyn.catalog: id: example.GistGenerator - version: 1.0 + version: "1.0" + itemType: template description: For programmatically generating GitHub Gists displayName: Gist Generator iconUrl: classpath:///sample-icon.png - itemType: template libraries: - http://search.maven.org/remotecontent?filepath=com/google/code/gson/gson/2.2.2/gson-2.2.2.jar - http:/.developers.cloudsoftcorp.com/brooklyn/guide/java/gist_generator/org.eclipse.egit.github.core-2.1.5.jar diff --git a/guide/misc/osgi.md b/guide/misc/osgi.md index 2af842eb..dd9ba771 100644 --- a/guide/misc/osgi.md +++ b/guide/misc/osgi.md @@ -88,6 +88,7 @@ For example, the `catalog.bom` file for Brooklyn's Webapp bundle looks like (abb version: ... items: - id: org.apache.brooklyn.entity.webapp.nodejs.NodeJsWebAppService + itemType: entity item: type: org.apache.brooklyn.entity.webapp.nodejs.NodeJsWebAppService name: Node.JS Application diff --git a/guide/ops/catalog/index.md b/guide/ops/catalog/index.md index b1e308fa..80e1b2cf 100644 --- a/guide/ops/catalog/index.md +++ b/guide/ops/catalog/index.md @@ -12,10 +12,11 @@ children: --- -Apache Brooklyn provides a **catalog**, which is a persisted collection of versioned blueprints and other resources. -A set of blueprints is loaded from the `default.catalog.bom` in the Brooklyn folder by default and additional ones can be added through the web console or CLI. -Blueprints in the catalog can be deployed directly, via the Brooklyn CLI or the web console, -or referenced in other blueprints using their `id`. +Apache Brooklyn provides a **catalog**, which is a persisted collection of versioned blueprints +and other resources. A set of blueprints is loaded from the `default.catalog.bom` in the Brooklyn +folder by default and additional ones can be added through the web console or CLI. Blueprints in +the catalog can be deployed directly, via the Brooklyn CLI or the web console, or referenced in +other blueprints using their `id`. ### Catalog Items YAML Syntax @@ -25,8 +26,22 @@ specifying the catalog metadata for the items and the actual blueprint or resour #### General YAML Schema + +Catalog items can be defined using the general structure below: + +~~~ yaml +brooklyn.catalog: + + items: + - + item: + + - + item: + +~~~ -A single catalog item can be defined following this general structure: +Alternatively, a single catalog item can be defined using the following general structure: ~~~ yaml brooklyn.catalog: @@ -35,21 +50,23 @@ brooklyn.catalog: ~~~ - -To define multiple catalog items in a single YAML, -where they may share some metadata, -use the following structure: +For example, the YAML below adds to the catalog a Tomcat entity with some additional default +configuration: ~~~ yaml brooklyn.catalog: - items: - - + - id: tomcat-server + version: "1.0.0" + itemType: entity item: - - - - item: - + type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server + brooklyn.config: + webapp.enabledProtocols: https + httpsSsl: + url: classpath://org/apache/brooklyn/entity/webapp/sample-java-keystore.jks + alias: myname + password: mypass ~~~ @@ -58,7 +75,7 @@ brooklyn.catalog: Catalog metadata fields supply the additional information required in order to register an item in the catalog. These fields can be supplied as `key: value` entries where either the `` or `` placeholders are, -with the latter overriding the former unless otherwise specfied below. +with the latter overriding the former unless otherwise specified below. The following metadata is *required* for all items: @@ -67,7 +84,13 @@ The following metadata is *required* for all items: this field disambiguates between blueprints of the same `id`. Note that this is typically *not* the version of the software being installed, but rather the version of the blueprint. For more information on versioning, see below. - (Also note YAML treats numbers differently to Strings. Explicit quotes may sometimes be required.) + (Also note YAML treats numbers differently to Strings. Explicit quotes are recommended, to avoid + `1.10` being interpretted as the number `1.1`.) +- `itemType`: the type of the item being defined. The supported item types are: + - `entity` + - `template` + - `policy` + - `location` To reference a catalog item in another blueprint, simply reference its ID and optionally its version number. For instance, if we've added an item with metadata `{ id: datastore, version: "1.0" }` (such as the example below), @@ -80,20 +103,20 @@ services: In addition to the above fields, exactly **one** of the following is also required: -- `item`: the YAML for a service or policy or location specification - (a map containing `type` and optional `brooklyn.config`) - or a full application blueprint (in the usual YAML format) for a template; **or* +- `item`: the YAML for an entity, or policy, or location specification + (a map containing `type` and optional `brooklyn.config`). For a "template" item, it + should be a map containing `services` (i.e. the usual YAML format for a full application + blueprint). **Or** - `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 `brooklyn.libraries` they add to the list); - if there are references between items, then order is important, + if there are references between items, then order is important: `items` are processed in order, depth-first, and forward references are not supported. Entries - can be URL to another catalog file to include, inheriting the meta from the current hierarchy. - Libraries defined so far in the meta will be used to load classpath entries. For example: + can be URL to another catalog file to include, inheriting the metadata from the current hierarchy. + Libraries defined so far in the metadata will be used to load classpath entries. For example: ~~~ yaml brooklyn.catalog: - displayName: Foo brooklyn.libraries: - http://some.server.or.other/path/my.jar items: @@ -101,31 +124,27 @@ brooklyn.catalog: - some-property: value include: classpath://more-catalog-entries-inside-jar.bom - id: use-from-my-catalog + version: "1.0.0" + itemType: entity item: type: some-type-defined-in-my-catalog-entries + brooklyn.config: + some.config: "some value" ~~~ The following optional catalog metadata is supported: -- `itemType`: the type of the item being defined. - When adding a template (see below) this must be set. - In most other cases this can be omitted and type type will be inferred. - The supported item types are: - - `entity` - - `template` - - `policy` - - `location` -- `name`: a nicely formatted display name for the item, used when presenting it in a GUI -- `description`: supplies an extended textual description for the item +- `name`: a nicely formatted display name for the item, used when presenting it in a GUI. +- `description`: supplies an extended textual description for the item. - `iconUrl`: points to an icon for the item, used when presenting it in a GUI. - The URL prefix `classpath` is supported but these URLs may *not* refer items in any OSGi bundle in the `brooklyn.libraries` section - (to prevent requiring all OSGi bundles to be loaded at launch). - Icons are instead typically installed either at the server from which the OSGi bundles or catalog items are supplied - or in the `conf` folder of the Brooklyn distro. -- `scanJavaAnnotations` [experimental]: if provided (as `true`), this will scan any locally provided - library URLs for types annotated `@Catalog` and extract metadata to include them as catalog items. - If no libraries are specified this will scan the default classpath. - This feature is experimental and may change or be removed. + The URL prefix `classpath` is supported but these URLs may *not* refer to resources in any OSGi + bundle in the `brooklyn.libraries` section (to prevent requiring all OSGi bundles to be loaded + at launch). Icons are instead typically installed either at the web server from which the OSGi + bundles or catalog items are supplied or in the `conf` folder of the Brooklyn distro. +- `scanJavaAnnotations` [experimental; deprecated]: if provided (as `true`), this will scan any + locally provided library URLs for types annotated `@Catalog` and extract metadata to include + them as catalog items. If no libraries are specified this will scan the default classpath. + This feature will likely be removed. Also note that external OSGi dependencies are not supported and other metadata (such as versions, etc) may not be applied. - `brooklyn.libraries`: a list of pointers to OSGi bundles required for the catalog item. @@ -135,7 +154,7 @@ The following optional catalog metadata is supported: Libraries should be supplied in the form `brooklyn.libraries: [ "http://...", "http://..." ]`, or as - `brooklyn.libraries: [ { name: symbolic-name, version: 1.0, url: http://... }, ... ]` if `symbolic-name:1.0` + `brooklyn.libraries: [ { name: symbolic-name, version: "1.0", url: http://... }, ... ]` if `symbolic-name:1.0` might already be installed from a different URL and you want to skip the download. Note that these URLs should point at immutable OSGi bundles; if the contents at any of these URLs changes, the behaviour of the blueprint may change @@ -160,14 +179,15 @@ and its implementation will be the Java class `org.apache.brooklyn.entity.nosql. ~~~ yaml brooklyn.catalog: id: datastore - version: 1.0 + version: "1.0" itemType: template iconUrl: classpath://org/apache/brooklyn/entity/nosql/riak/riak.png name: Datastore (Riak) description: Riak is an open-source NoSQL key-value data store. item: - type: org.apache.brooklyn.entity.nosql.riak.RiakNode - name: Riak Node + services: + - type: org.apache.brooklyn.entity.nosql.riak.RiakNode + name: Riak Node ~~~ @@ -177,15 +197,17 @@ This YAML will install three items: ~~~ yaml brooklyn.catalog: - version: 1.1 + version: "1.1" iconUrl: classpath://org/apache/brooklyn/entity/nosql/riak/riak.png description: Riak is an open-source NoSQL key-value data store. items: - id: riak-node + itemType: entity item: type: org.apache.brooklyn.entity.nosql.riak.RiakNode name: Riak Node - id: riak-cluster + itemType: entity item: type: org.apache.brooklyn.entity.nosql.riak.RiakCluster name: Riak Cluster @@ -195,12 +217,6 @@ brooklyn.catalog: item: services: - type: riak-cluster - location: - jclouds:softlayer: - region: sjc01 - # identity and credential must be set unless they are specified in your brooklyn.properties - # identity: XXX - # credential: XXX brooklyn.config: # the default size is 3 but this can be changed to suit your requirements initial.size: 3 @@ -209,7 +225,7 @@ brooklyn.catalog: minRam: 8gb ~~~ -The items this will install are: +The items this will add to the catalog are: - `riak-node`, as before, but with a different name - `riak-cluster` as a convenience short name for the `org.apache.brooklyn.entity.nosql.riak.RiakCluster` class @@ -228,7 +244,7 @@ In addition to blueprints, locations can be added to the Apache Brooklyn catalog ~~~ yaml brooklyn.catalog: id: vagrant - version: 1.0 + version: "1.0" itemType: location name: Vagrant getting started location item: @@ -252,7 +268,7 @@ location: vagrant #### Legacy Syntax -The following legacy and experimental syntax is also supported: +The following legacy and experimental syntax is also supported, but deprecated: ~~~ yaml @@ -275,6 +291,8 @@ and any OSGi `brooklyn.libraries` defined there will not be loaded.) ### 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: @@ -298,7 +316,13 @@ with a `POST` of the YAML file to `/v1/catalog` endpoint. To do this using `curl`: ~~~ bash -curl http://127.0.0.1:8081/v1/catalog --data-binary @/path/to/riak.catalog.bom +curl -u admin:password http://127.0.0.1:8081/v1/catalog --data-binary @/path/to/riak.catalog.bom +~~~ + +Or using the CLI: + +~~~ bash +br add-catalog /path/to/riak.catalog.bom ~~~ @@ -311,9 +335,10 @@ Using the REST API, you can delete a versioned item from the catalog using the c For example, to delete the item with id `datastore` and version `1.0` with `curl`: ~~~ bash -curl -X DELETE http://127.0.0.1:8081/v1/catalog/applications/datastore/1.0 +curl -u admin:password -X DELETE http://127.0.0.1:8081/v1/catalog/applications/datastore/1.0 ~~~ + **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. @@ -326,7 +351,7 @@ Deprecation applies to a specific version of a catalog item, so the full id including the version number is passed to the REST API as follows: ~~~ bash -curl -X POST http://127.0.0.1:8081/v1/catalog/entities/MySQL:1.0/deprecated/true +curl -u admin:password -X POST http://127.0.0.1:8081/v1/catalog/entities/MySQL:1.0/deprecated/true ~~~ @@ -347,9 +372,9 @@ When referencing a blueprint, if a version number is not specified the latest non-snapshot version will be loaded when an entity is instantiated. -### CLI Options +### Brooklyn Server Command Line Arguments -The `brooklyn` CLI includes several commands for working with the catalog. +The command line arguments when launching `brooklyn` include several commands for working with the catalog. * `--catalogAdd ` will add the catalog items in the `bom` file * `--catalogReset` will reset the catalog to the initial state diff --git a/guide/ops/externalized-configuration.md b/guide/ops/externalized-configuration.md index b0c85cde..f891b82b 100644 --- a/guide/ops/externalized-configuration.md +++ b/guide/ops/externalized-configuration.md @@ -128,7 +128,8 @@ The same blueprint language DSL can be used within YAML catalog items. For examp brooklyn.catalog: id: com.example.myblueprint - version: 1.2.3 + version: "1.2.3" + itemType: entity brooklyn.libraries: - > $brooklyn:formatString("https://%s:%s@repo.example.com/libs/myblueprint-1.2.3.jar", diff --git a/guide/yaml/entity-configuration.md b/guide/yaml/entity-configuration.md index fcd05118..538e2fe1 100644 --- a/guide/yaml/entity-configuration.md +++ b/guide/yaml/entity-configuration.md @@ -49,7 +49,8 @@ The example below illustrates the principles: brooklyn.catalog: items: - id: entity-config-example - displayName: Entity Config Example + itemType: entity + name: Entity Config Example item: type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess brooklyn.parameters: @@ -182,8 +183,9 @@ parent entity's value will never be inherited: brooklyn.catalog: items: - id: entity-config-example - version: 1.1.0-SNAPSHOT - displayName: Entity Config Example + version: "1.1.0-SNAPSHOT" + itemType: entity + name: Entity Config Example item: type: org.apache.brooklyn.entity.machine.MachineEntity brooklyn.parameters: diff --git a/guide/yaml/example_yaml/brooklyn-elasticsearch-catalog.bom b/guide/yaml/example_yaml/brooklyn-elasticsearch-catalog.bom index bbed240d..e069721d 100644 --- a/guide/yaml/example_yaml/brooklyn-elasticsearch-catalog.bom +++ b/guide/yaml/example_yaml/brooklyn-elasticsearch-catalog.bom @@ -1,6 +1,7 @@ brooklyn.catalog: id: elasticsearch - version: 1.0 + version: "1.0" + itemType: entity iconUrl: https://avatars0.githubusercontent.com/u/6764390?v=3&s=400 name: Elasticsearch license: Apache-2.0 diff --git a/guide/yaml/example_yaml/brooklyn-elk-catalog.bom b/guide/yaml/example_yaml/brooklyn-elk-catalog.bom index fbc9ab85..f4a6efc3 100644 --- a/guide/yaml/example_yaml/brooklyn-elk-catalog.bom +++ b/guide/yaml/example_yaml/brooklyn-elk-catalog.bom @@ -1,35 +1,34 @@ brooklyn.catalog: - version: 1.0 + id: ELK-Stack + version: "1.0" + itemType: template iconUrl: https://avatars0.githubusercontent.com/u/6764390?v=3&s=400 license: Apache-2.0 issues_url: https://github.com/Graeme-Miller/brooklyn-elk/issues - itemType: template + name: ELK Stack + description: | + Simple ELK stack deployment: provisions Elasticsearch, Kibana and Logtash as a child of Apache Tomcat 8 item: - type: org.apache.brooklyn.entity.stock.BasicApplication - name: ELK Stack - id: ELK-Stack - description: | - Simple ELK stack deployment: provisions Elasticsearch, Kibana and Logtash as a child of Apache Tomcat 8 services: - - type: elasticsearch - id: es - name: Elasticsearch Cluster - brooklyn.config: - install.version: 1.4.4 - - type: kibana-standalone - id: kibana - name: Kibana Server - customize.latch: $brooklyn:entity("es").attributeWhenReady("service.isUp") - brooklyn.config: - kibana.elasticsearch.ip: $brooklyn:entity("es").attributeWhenReady("host.address.first") - kibana.elasticsearch.port: $brooklyn:entity("es").config("elasticsearch.http.port") - - type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server - id: tomcat - customize.latch: $brooklyn:entity("es").attributeWhenReady("service.isUp") + - type: elasticsearch + id: es + name: Elasticsearch Cluster + brooklyn.config: + install.version: 1.4.4 + - type: kibana-standalone + id: kibana + name: Kibana Server + customize.latch: $brooklyn:entity("es").attributeWhenReady("service.isUp") + brooklyn.config: + kibana.elasticsearch.ip: $brooklyn:entity("es").attributeWhenReady("host.address.first") + kibana.elasticsearch.port: $brooklyn:entity("es").config("elasticsearch.http.port") + - type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server + id: tomcat + customize.latch: $brooklyn:entity("es").attributeWhenReady("service.isUp") + brooklyn.config: + children.startable.mode: background_late + brooklyn.children: + - type: logstash-child + name: Logstash Child brooklyn.config: - children.startable.mode: background_late - brooklyn.children: - - type: logstash-child - name: Logstash Child - brooklyn.config: - logstash.elasticsearch.host: $brooklyn:entity("es").attributeWhenReady("urls.http.withBrackets") + logstash.elasticsearch.host: $brooklyn:entity("es").attributeWhenReady("urls.http.withBrackets") diff --git a/guide/yaml/example_yaml/brooklyn-kibana-catalog.bom b/guide/yaml/example_yaml/brooklyn-kibana-catalog.bom index ee006d2d..90eda9ea 100644 --- a/guide/yaml/example_yaml/brooklyn-kibana-catalog.bom +++ b/guide/yaml/example_yaml/brooklyn-kibana-catalog.bom @@ -1,8 +1,9 @@ brooklyn.catalog: - version: 0.0.2 + version: "0.0.2" iconUrl: http://blog.arungupta.me/wp-content/uploads/2015/07/kibana-logo.png items: - id: kibana-standalone + itemType: entity name: "Kibana server" description: "Single Kibana server" description: | diff --git a/guide/yaml/example_yaml/brooklyn-logstash-catalog.bom b/guide/yaml/example_yaml/brooklyn-logstash-catalog.bom index 7c431f57..5285e2b8 100644 --- a/guide/yaml/example_yaml/brooklyn-logstash-catalog.bom +++ b/guide/yaml/example_yaml/brooklyn-logstash-catalog.bom @@ -1,8 +1,9 @@ brooklyn.catalog: - version: 1.5.5 + version: "1.5.5" iconUrl: http://logstash.net/images/logstash.png items: - id: logstash-standalone + itemType: entity name: "Logstash server" description: "Single Logstash server" item: @@ -45,6 +46,7 @@ brooklyn.catalog: nohup /opt/logstash/logstash-${VERSION}/bin/logstash agent -f ${CONFIG_DIR} -l /var/log/logstash/logstash.log & echo $! > $PID_FILE - id: logstash-child + itemType: entity name: "Logstash Child" description: | Logstash server to be embedded as a child of a SoftwareProcess who diff --git a/guide/yaml/example_yaml/vanilla-bash-netcat-catalog.bom b/guide/yaml/example_yaml/vanilla-bash-netcat-catalog.bom index 75518186..6416ab79 100644 --- a/guide/yaml/example_yaml/vanilla-bash-netcat-catalog.bom +++ b/guide/yaml/example_yaml/vanilla-bash-netcat-catalog.bom @@ -1,6 +1,7 @@ brooklyn.catalog: id: netcat-example version: "1.0" + itemType: entity item: type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess name: Simple Netcat Server