brooklyn-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mike Zaccardo <mike.zacca...@cloudsoftcorp.com>
Subject Re: [PROPOSAL] catalog YAML format consistency
Date Tue, 28 Jun 2016 18:18:52 GMT
+1 for agreeing upon a standard syntax, especially because consulting
existing blueprints is one of the best references when developing a new one.

Alex's staged plan also makes sense to me.

On Mon, Jun 27, 2016 at 8:28 AM Andrew Kennedy <
andrew.kennedy@cloudsoftcorp.com> wrote:

> +1
>
> I agree that we need to maintain consistency in our YAML and BOM files, but
> not just at the level of Brooklyn item and entity syntax. There should also
> be a consistent structural format to the files. For example, when
> specifying configuration, we allow items both inside the `brooklyn.config`
> map, and outside it. For short examples, missing out `brooklyn.config` is
> acceptable, but in general we should use it. There should also be
> consistency in ordering the parts of an entity or catalog entry definition,
> as well as the formatting of maps, lists and strings.
>
> The following is a suggested style guide, for discussion.
>
> - https://gist.github.com/grkvlt/62ee0ddeea2f4503f82ad25c2f9b31fd
>
> The normative statements are listed here, and the document linked above
> contains a conforming YAML fragment showing how they are interpreted.
>
> 1. Blueprints MUST place all configuration inside a `brooklyn.config` map,
> and MUST use the fully qualified configuration key name
> 2. Lists MUST be indented properly, to allow IDE folding to work properly
> 3. Keywords MUST be formatted as `lowerCamel` tokens
> 4. Sensor, configuration key and section names MUST be formatted as
> `lower-hyphen.dot-separated` tokens
> 5. The preamble for a catalog entry SHOULD contain the following keys,
> which MUST appear in this order: version, id, name, description, iconUrl,
> origin, license, licenseUrl, publish
> 6. Entities SHOULD contain the following sections, which MUST appear in
> this order: brooklyn.parameters, brooklyn.config, brooklyn.initializers,
> brooklyn.enrichers, brooklyn.policies, brooklyn.children
> 7. Catalog items SHOULD contain the following keys, which MUST appear in
> this order: id, name, description, itemType, item
> 8. Entities and entity specifications SHOULD contain the following keys,
> which MUST appear in this order: type, id, name, description, services
> 9. Names MUST be quoted strings
> 10. The description value MUST use the multi-line string syntax
> 11. Parameters SHOULD use the following keys, which MUST appear in this
> order: name, label, description, type, default, constraints
>
> Andrew.
>
>
> On Mon, 20 Jun 2016 at 18:08 Aled Sage <aled.sage@gmail.com> wrote:
>
> > Thanks all,
> >
> > Alex's suggestion makes a lot of sense. So we should:
> >
> >  1. agree short-term preferred syntax
> >  2. update our docs and examples to *always* use that
> >  3. discuss improvements for a more powerful syntax, and the longer term
> >     bigger long-term overhaul.
> >
> > It should be trivial to warn someone if they have not included the
> > "itemType", so I think we should do that short-term.
> >
> > ---
> > Any more opinions for the preferred syntax?
> >
> > Aled
> >
> >
> > On 20/06/2016 14:44, Geoff Macartney wrote:
> > > +1 for the proposal, and for staging it.
> > >
> > > I actually quite like the suggestion of making items/item entirely
> > consistent (by requiring both).   If I have
> > >
> > > 1 brooklyn.catalog:
> > > 2   version: "2.0.0-SNAPSHOT"
> > > 3
> > > 4   item:
> > > 5     type: server
> > > 6     id: testy
> > > 7     name: Testy McServer
> > >
> > > and decide for some reason that I need a second item (maybe move one
> > here from another file), I can’t just add it below line 7.  Instead I
> have
> > to go editing lines 3-7 to add “items:” and change the indentation.
> > Sticking to items+item consistently will make this sort of refactoring
> less
> > tedious.  Just a thought.
> > >
> > > Geoff
> > >
> > >
> > >
> > >
> > > ————————————————————
> > > Gnu PGP key - http://is.gd/TTTTuI
> > >
> > >
> > >> On 20 Jun 2016, at 14:17, Svetoslav Neykov <
> > svetoslav.neykov@cloudsoftcorp.com> wrote:
> > >>
> > >> +1 for the proposal.
> > >>
> > >> I find the current item-items functionality logical. "item" is used in
> > leaf items, "items" is used in non-leaf items. Forcing a non-leaf root
> just
> > so we always have "items" is overhead.
> > >>
> > >> Svet.
> > >>
> > >>
> > >>> On 20.06.2016 г., at 15:47, Aled Sage <aled.sage@gmail.com>
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.
> > >>>
> > >>>
> > >
> >
> > --
>
> Andrew Kennedy ; Founder clocker.io project ; @grkvlt ; Cloudsoft
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message