brooklyn-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alex Heneveld <alex.henev...@cloudsoftcorp.com>
Subject Re: [PROPOSAL] catalog YAML format consistency
Date Mon, 20 Jun 2016 12:56:14 GMT

I like this direction but I think we should stage as follows:

NOW - agree short-term preferred syntax for catalog items (but nothing 
deprecated, not major change)

SOON - define new improved and more powerful syntax, similar to 
preferred -- but allowing arbitrary types, interfaces, mixins

My thinking is we need a bigger overhaul (I've been mulling this over) 
so let's not do too much churn until then.

--a


On 20/06/2016 13:47, Aled Sage wrote:
> Hi all,
>
> The YAML format for adding catalog items accepts several different 
> ways of defining them. This has led to our examples being 
> inconsistent, our code more complicated, and potential confusion for 
> users when they see different things that turn out to mean the same.
>
> I think we should standardise on one approach, and deprecate the other 
> ways.
>
> ---
>
> _*Current Code*_
>
> An example .bom file is shown below:
>
>     brooklyn.catalog:
>   items:
>   - id: entity1
>     version: "1.0.0"
>     itemType: entity
>     item:
>       type: org.apache.brooklyn.entity.machine.MachineEntity
>
> Variants:
>
>  * If defining just a single item in the .bom file, you can optionally
>    miss out the "items".
>  * You can miss out the "itemType" - it will guess at it by trying to
>    treat it as an entity, a template, a location or a policy. The
>    default is "entity".
>  * You can include "services:" for entity or template types, or you can
>    miss it out if there is just one entity in the item.
>  * Similar to "services:", you can include "brooklyn.policies:" or
>    "brooklyn.locations:".
>    If itemType is missing, this helps to infer the type. If it does not
>    agree with itemType, then we add it as the item type and it will
>    fail later.
>  * You can define the item metadata at any level - it could be directly
>    under "brooklyn.catalog" (in which case it applies to all items), or
>    under a specific item (in which case it overrides any more general
>    metadata).
>
>
> An example of a .bom for a single item is shown below:
>
> brooklyn.catalog:
>   id: entity2
>   version: "1.0.0"
>   itemType: entity
>   item:
>     type: org.apache.brooklyn.entity.machine.MachineEntity
>
>
> ---
>
> _*Proposal*_
>
> I suggest we have the following stricter rules. Anything else is 
> deprecated, logging a warning.
>
>  * Always include "itemType".
>  * For entity, policy and location: do not include "services:",
>    "brooklyn.policies:" or "brooklyn.locations:" - i.e. it will expect
>    exactly one type in the item.
>  * For template, always expect "services:" (even if there is just one
>    thing). This is consistent with the YAML required when deploying an
>    application.
>  * Always include "items", even if there is just one item in it.
>    (reasoning: we do not support "service" versus "services", so why
>    support "item").
>
>
> We should change the following (breaking backwards compatibility, 
> because it's really a bug):
>
>  * If the itemType differs from the actual type of the item, then fail.
>
> Aled
>
> p.s. I'm in two minds about "item" versus "items": it is simpler with 
> the single item, and having "item" underneath "items" means it's not 
> quite like the "services" analogy.
>
>
>


Mime
View raw message