Skip to content
Permalink
Browse files
Merge commit '5b78602c' into release-5.0-reverted-222
  • Loading branch information
ahgittin committed Sep 4, 2018
2 parents a75819e + 5b78602 commit d4f71853ba15619a2cfbd262e5eb7cb5cc4ece95
Show file tree
Hide file tree
Showing 6 changed files with 192 additions and 84 deletions.
@@ -5,7 +5,7 @@ Contributor Workflow
--------------------

The contributor workflow is identical to that used by the main project, with
pull requests and contributor licenses requried. Therefore you should
pull requests and contributor licenses required. Therefore you should
familiarise yourself with the standard workflow for Apache Brooklyn:

* [Guide for contributors][CONTRIB]
@@ -131,15 +131,15 @@ More details of behaviour in edge conditions can be seen and set via the paramet

#### PrimaryRunning Enricher

- org.apache.brooklyn.policy.ha.PrimaryRunningEnricher
- org.apache.brooklyn.policy.failover.PrimaryRunningEnricher

This adds service not-up and problems entries if the primary is not running,
so that the parent will only be up/healthy if there is a healthy primary.


#### PropagatePrimary Enricher

- org.apache.brooklyn.policy.ha.PropagatePrimaryEnricher
- org.apache.brooklyn.policy.failover.PropagatePrimaryEnricher

This allows selected sensors from the primary to be available at the parent.
As the primary changes, the indicated sensors will be updated to reflect the values from the new primaries.
@@ -23,7 +23,7 @@ brooklyn.catalog:
- <additional-catalog-metadata>
item:
<blueprint-or-resource-definition>
~~~
~~~

Alternatively, a single catalog item can be defined using the following general structure:

@@ -32,9 +32,9 @@ brooklyn.catalog:
<catalog-metadata>
item:
<blueprint-or-resource-definition>
~~~
~~~

For example, the YAML below adds to the catalog a Tomcat entity with some additional default
For example, the YAML below adds to the catalog a Tomcat entity with some additional default
configuration:

~~~ yaml
@@ -51,58 +51,64 @@ brooklyn.catalog:
url: classpath://org/apache/brooklyn/entity/webapp/sample-java-keystore.jks
alias: myname
password: mypass
~~~
~~~


#### Catalog Metadata

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 `<catalog-metadata>` or `<additional-catalog-metadata>` placeholders are,
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 `<catalog-metadata>` or `<additional-catalog-metadata>` placeholders are in the examples above,
with the latter overriding the former unless otherwise specified below.

The following metadata is *required* for all items:

- `id`: a human-friendly unique identifier for how this catalog item will be referenced from blueprints
- `version`: multiple versions of a blueprint can be installed and used simultaneously;
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 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`
###### Required Metadata

**`id`**
A human-friendly unique identifier for how this catalog item will be referenced from blueprints.

**`version`**
Multiple versions of a blueprint can be installed and used simultaneously;
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 [Versioning]({{book.path.docs}}/blueprints/catalog/versioning.md).
(Also note YAML treats numbers differently to Strings. Explicit quotes are recommended, to avoid
`1.10` being interpretted as the number `1.1`.)

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),
we could refer to it in another blueprint with:
For instance, if the catalog contains an item with metadata `{ id: datastore, version: "1.0" }`
we could refer to it in another blueprint with:

~~~ yaml
services:
- type: datastore:1.0
~~~

In addition to the above fields, exactly **one** of the following is also required:

- `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:
`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 metadata from the current hierarchy.
Libraries defined so far in the metadata will be used to load classpath entries. For example:
~~~

**`itemType`**
The type of the item being defined. The supported item types are: `entity`, `template`, `policy`, and `location`.

In addition to `id`, `version`, and `itemType`, exactly **one** of `item` and `items` is also required:

**`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).

**`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 the 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:
`items` are processed in order, depth-first, and forward references are not supported. Entries
can be URLs 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:
brooklyn.libraries:
- http://some.server.or.other/path/my.jar
- http://example.com/path/my.jar
items:
- classpath://my-catalog-entries-inside-jar.bom
- some-property: value
@@ -116,39 +122,78 @@ brooklyn.catalog:
some.config: "some value"
~~~


##### Optional Metadata

The following optional catalog metadata is supported:

- `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 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.
This can be omitted if blueprints are pure YAML and everything required is included in the classpath and catalog.
Where custom Java code or bundled resources is needed, however, OSGi JARs supply
a convenient packaging format and a very powerful versioning format.
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`
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
whenever a bundle is reloaded in a Brooklyn server,
and if entities have been deployed against that version, their behavior may change in subtle or potentially incompatible ways.
To avoid this situation, it is highly recommended to use OSGi version stamps as part of the URL.
- `include`: A 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. `include` must be used
when you have sibling properties. If it's the only property it may be skipped by having the URL as the
value - see `items` example above.

**`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 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 and catalog items are supplied or in the `conf` directory of the Brooklyn distro.

**`brooklyn.libraries`**
A list of pointers to OSGi bundles required for the catalog item.
This can be omitted if blueprints are pure YAML and everything required is included in the classpath and catalog.
Where custom Java code or bundled resources is needed, however, OSGi JARs supply
a convenient packaging format and a very powerful versioning format.

Libraries can be supplied in short form:
~~~yaml
brooklyn.libraries:
- "http://example.com/bundle-1.0.2.jar"
- "http://example.com/another-bundle-3.3.0.jar"
~~~

Or in long form:
~~~yaml
brooklyn.libraries:
- name: "symbolic-name"
version: "1.0"
url: "http://example.com/bundle-1.0.jar"
auth:
username: $brooklyn:external("myprovider", "username")
password: $brooklyn:external("myprovider", "password")
~~~
The only mandatory property in the long form is `url`. Brooklyn will skip the download when a bundle with matching `name` and `version` is already installed.

URLs should point at immutable OSGi bundles;
if the contents at any of these URLs changes, the behaviour of the blueprint may change
whenever a bundle is reloaded in a Brooklyn server,
and if entities have been deployed against that version, their behavior may change in subtle or potentially incompatible ways.
To avoid this situation, it is highly recommended to use OSGi version stamps as part of the URL.

Specify `auth` if the resource at `url` requires authentication to access.
Do not write the username and password directly into the file; instead
use [external configuration]({{book.path.docs}}/ops/externalized-configuration.md)
to reference the values.

**`include`**
A 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. `include` must be used
when you have sibling properties. If it's the only property it may be skipped by having the URL as the
value - see `items` example above.


##### Deprecated Metadata

The following metadata is no longer supported and will be ignored in a future release:

**`scanJavaAnnotations`**
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.


#### Catalog YAML Examples
@@ -172,7 +217,7 @@ brooklyn.catalog:
services:
- type: org.apache.brooklyn.entity.nosql.riak.RiakNode
name: Riak Node
~~~
~~~


##### Multiple Items
@@ -207,15 +252,15 @@ brooklyn.catalog:
provisioning.properties:
# you can also define machine specs
minRam: 8gb
~~~
~~~

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
- `datastore`, now pointing at the `riak-cluster` blueprint, in SoftLayer and with the given size and machine spec,
- `datastore`, now pointing at the `riak-cluster` blueprint, in SoftLayer and with the given size and machine spec,
as the default implementation for anyone
requesting a `datastore` (and if installed atop the previous example, new references to `datastore`
requesting a `datastore` (and if installed atop the previous example, new references to `datastore`
will access this version because it is a higher number);
because it is a template, users will have the opportunity to edit the YAML (see below).
(This must be supplied after `riak-cluster`, because it refers to `riak-cluster`.)
@@ -258,14 +303,14 @@ The following legacy and experimental syntax is also supported, but deprecated:
<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.
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,
(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,

0 comments on commit d4f7185

Please sign in to comment.