settingsLogin | Registersettings

[openstack-dev] [tripleo] When to use parameters vs parameter_defaults

0 votes

Hi all,

I wanted to start some discussion re $subject, because it's been apparrent
that we have a lack of clarity on this issue (and have done ever since we
started using parameter_defaults).

Some context:

  • Historically TripleO has provided a fairly comprehensive "top level"
    parameters interface, where many per-role and common options are
    specified, then passed in to the respective ResourceGroups on deployment

https://git.openstack.org/cgit/openstack/tripleo-heat-templates/tree/overcloud-without-mergepy.yaml#n14

The nice thing about this approach is it gives a consistent API to the
operator, e.g the parameters schema for the main overcloud template defines
most of the expected inputs to the deployment.

The main disadvantage is a degree of template bloat, where we wire dozens
of parameters into each ResourceGroup, and from there into whatever nested
templates consume them.

  • When we started adding interfaces (such as all the OS::TripleO::ExtraConfig
    interfaces, there was a need to enable passing arbitrary additional
    values to nested templates, with no way of knowing what they are (e.g to
    enable wiring in third-party pieces we have no knowledge of or which
    require implementation-specific arguments which don't make sense for all
    deployments.

To do this, we made use of the heat parameter_defaults interface, which
(unlike normal parameters) have global scope (visible to all nested stacks,
without explicitly wiring in the values from the parent):

http://docs.openstack.org/developer/heat/template_guide/environment.html#define-defaults-to-parameters

The nice thing about this approach is its flexibility, any arbitrary
values can be provided without affecting the parent templates, and it can
allow for a terser implementation because you only specify the parameter
definition where it's actually used.

The main disadvantage of this approach is it becomes very much harder to
discover an API surface for the operator, e.g the parameters that must be
provided on deployment by any CLI/UI tools etc. This has been partially
addressed by the new-for-liberty nested validation heat feature, but
there's still a bunch of unsolved complexity around how to actually consume
that data and build a coherent consolidated API for user interaction:

https://github.com/openstack/heat-specs/blob/master/specs/liberty/nested-validation.rst

My question is, where do we draw the line on when to use each interface?

My position has always been that we should only use parameter_defaults for
the ExtraConfig interfaces, where we cannot know what reasonable parameters
are. And for all other "core" functionality, we should accept the increased
template verbosity and wire arguments in from overcloud-without-mergepy.

However we've got some patches which fall into a grey area, e.g this SSL
enablement patch:

https://review.openstack.org/#/c/231930/46/overcloud-without-mergepy.yaml

Here we're actually removing some existing (non functional) top-level
parameters, and moving them to parameter_defaults.

I can see the logic behind it, it does make the templates a bit cleaner,
but at the expense of discoverablility of those (probably not
implementation dependent) parameters.

How do people feel about this example, and others like it, where we're
enabling common, but not mandatory functionality?

In particular I'm keen to hear from Mainn and others interested in building
UIs on top of TripleO as to which is best from that perspective, and how
such arguments may be handled relative to the capabilities mapping proposed
here:

https://review.openstack.org/#/c/242439/

Thanks!

Steve


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
asked Nov 10, 2017 in openstack-dev by Steven_Hardy (16,900 points)   2 7 11

23 Responses

0 votes

On 11/16/2015 04:25 PM, Steven Hardy wrote:
Hi all,

I wanted to start some discussion re $subject, because it's been apparrent
that we have a lack of clarity on this issue (and have done ever since we
started using parameter_defaults).

[...]

How do people feel about this example, and others like it, where we're
enabling common, but not mandatory functionality?

At first I was thinking about something as simple as: "don't use
top-level params for resources which the registry doesn't enable by
default".

It seems to be somewhat what we tried to do with the existing pluggable
resources.

Also, not to hijack the thread but I wanted to add another question
related to a similar issue:

Is there a reason to prefer use of parameters: instead of
parameter_defaults: in the environment files?

It looks to me that by defaulting to parameter_defaults: users won't
need to update their environment files in case the parameter is moved
from top-level into a specific nested stack so I'm inclined to prefer
this. Are there reasons not to?
--
Giulio Fidente
GPG KEY: 08D733BA


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Nov 16, 2015 by Giulio_Fidente (3,980 points)   3 3
0 votes

Hi all,

I wanted to start some discussion re $subject, because it's been apparrent
that we have a lack of clarity on this issue (and have done ever since we
started using parameter_defaults).

Some context:

  • Historically TripleO has provided a fairly comprehensive "top level"
    parameters interface, where many per-role and common options are
    specified, then passed in to the respective ResourceGroups on deployment

https://git.openstack.org/cgit/openstack/tripleo-heat-templates/tree/overcloud-without-mergepy.yaml#n14

The nice thing about this approach is it gives a consistent API to the
operator, e.g the parameters schema for the main overcloud template defines
most of the expected inputs to the deployment.

The main disadvantage is a degree of template bloat, where we wire dozens
of parameters into each ResourceGroup, and from there into whatever nested
templates consume them.

  • When we started adding interfaces (such as all the OS::TripleO::ExtraConfig
    interfaces, there was a need to enable passing arbitrary additional
    values to nested templates, with no way of knowing what they are (e.g to
    enable wiring in third-party pieces we have no knowledge of or which
    require implementation-specific arguments which don't make sense for all
    deployments.

To do this, we made use of the heat parameter_defaults interface, which
(unlike normal parameters) have global scope (visible to all nested stacks,
without explicitly wiring in the values from the parent):

http://docs.openstack.org/developer/heat/template_guide/environment.html#define-defaults-to-parameters

The nice thing about this approach is its flexibility, any arbitrary
values can be provided without affecting the parent templates, and it can
allow for a terser implementation because you only specify the parameter
definition where it's actually used.

The main disadvantage of this approach is it becomes very much harder to
discover an API surface for the operator, e.g the parameters that must be
provided on deployment by any CLI/UI tools etc. This has been partially
addressed by the new-for-liberty nested validation heat feature, but
there's still a bunch of unsolved complexity around how to actually consume
that data and build a coherent consolidated API for user interaction:

https://github.com/openstack/heat-specs/blob/master/specs/liberty/nested-validation.rst

My question is, where do we draw the line on when to use each interface?

My position has always been that we should only use parameter_defaults for
the ExtraConfig interfaces, where we cannot know what reasonable parameters
are. And for all other "core" functionality, we should accept the increased
template verbosity and wire arguments in from overcloud-without-mergepy.

However we've got some patches which fall into a grey area, e.g this SSL
enablement patch:

https://review.openstack.org/#/c/231930/46/overcloud-without-mergepy.yaml

Here we're actually removing some existing (non functional) top-level
parameters, and moving them to parameter_defaults.

I can see the logic behind it, it does make the templates a bit cleaner,
but at the expense of discoverablility of those (probably not
implementation dependent) parameters.

How do people feel about this example, and others like it, where we're
enabling common, but not mandatory functionality?

In particular I'm keen to hear from Mainn and others interested in building
UIs on top of TripleO as to which is best from that perspective, and how
such arguments may be handled relative to the capabilities mapping proposed
here:

https://review.openstack.org/#/c/242439/

Thanks!

Steve

(in re-reading this, I realize I'm not providing an answer to how I feel
about the example as I am adding some more thoughts in general;
apologies for that)

I see there being a few issues with the current approach:

  • I'll get this one out of the way first, even though it's not the
    biggest issue. The name 'parameter_defaults' tends to confuse new 3rd
    party integrators since we're not using it as a default per se. I
    understand from Heat's point of view it's defaulting a parameter value,
    but from the user's standpoint, they are setting an actual value to be
    used. Perhaps this can be solved with better docs, and I largely mention
    it because I can see most of what you wrote in here turning into
    documentation, so it'll be good to have it mentioned.

  • Back to the point of your e-mail, there are two ways to view it.

-- If you define too few parameters at the top level, you end up with a
lot of comments like the following inside of nested templates:

ControlPlaneSubnetCidr: # Override this via parameter_defaults

or

To be defined via a local or global environment in parameter_defaults

rhelregactivation_key:
type: string

There are other examples too, but the thing to note is that we've so far
been pretty good about adding those comments. It's not a programmatic
marker, which may be a problem for a UX, but at least the information is
there when someone is reading the templates.

Like Steve mentioned, there has been work in Heat to analyze the larger
context of the parent and nested templates to help make that information
programmatically accessible.

-- If you have too many of the top-level parameters, you end up with
boilerplate code inside the nested templates with parameters that it
doesn't care to use. I couldn't immediately find any examples of that in
THT, though I think there are a few.

More concerning is that the addition of new top-level parameters breaks
backward compatibility. Unless I'm mistaken, if we pass a parameter to a
nested stack, the stack must be defined to take the parameter. There's
no way to have Heat ignore extraneous values.

There's also no versioning scheme, so we can't do something like:

resourcedef:
type: OS::TripleO::ObjectStorage
properties:
KeyName: {get
param: KeyName} # as of version 1.2

Ignore the syntax there; my point is, the top-level (where "top" means
anything with a nested resource) resources act as an API, but you only
get to use the current version.

Since the bulk of our integrations are done through ExtraConfig, for now
we only have to be really careful in changing the parameters to those
resources. At some point, we'll need to start being really careful about
other nested resource interfaces as well if we want to support extension
at those levels

  • One more example, and I'm not at all picking on this one particular
    implementation, but we have:

parameter_defaults:
# Required to fill in:
NeutronBigswitchRestproxyServers:
NeutronBigswitchRestproxyServerAuth:

# Optional:
# NeutronBigswitchRestproxyAutoSyncOnFailure:
# NeutronBigswitchRestproxyConsistencyInterval:

I 100% understand why it's done this way given the current template
constraints. But it's difficult to fashion a UX around this when we
don't actually capture the required/optional nature of these parameters
in a way that's consumable. If we look at the template, they are all
"optional" (in the sense that they are defaulted). But it shows how the
parameter_defaults is a bit more of a workaround than a formal concept
of how to dynamically add parameters.

  • I do like the capabilities map concept. From the beginning I thought
    this was information that Tuskar would carry outside of the templates
    themselves. I don't see a problem with acknowledging the templates don't
    want to carry everything a UI would need and supplying that data
    elsewhere. It's possible that the sorts of extra information I described
    in the last bullet point are carried either in a similar fashion or in a
    comment convention that Tuskar knows how to interpret.


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Nov 16, 2015 by Jay_Dobies (3,120 points)   2 3
0 votes

On Mon, Nov 16, 2015 at 08:15:48PM +0100, Giulio Fidente wrote:
On 11/16/2015 04:25 PM, Steven Hardy wrote:

Hi all,

I wanted to start some discussion re $subject, because it's been apparrent
that we have a lack of clarity on this issue (and have done ever since we
started using parameter_defaults).

[...]

How do people feel about this example, and others like it, where we're
enabling common, but not mandatory functionality?

At first I was thinking about something as simple as: "don't use top-level
params for resources which the registry doesn't enable by default".

It seems to be somewhat what we tried to do with the existing pluggable
resources.

Also, not to hijack the thread but I wanted to add another question related
to a similar issue:

Is there a reason to prefer use of parameters: instead of
parameter_defaults: in the environment files?

It looks to me that by defaulting to parameter_defaults: users won't need to
update their environment files in case the parameter is moved from top-level
into a specific nested stack so I'm inclined to prefer this. Are there
reasons not to?

The main reason is scope - if you use "parameters", you know the data flow
happens via the parent template (e.g overcloud-without-mergepy) and you
never have to worry about naming collisions outside of that template.

But if you use parameter_defaults, all parameters values defined that way
are effectively global, and you then have to be much more careful that you
never shadow a parameter name and get an unexpected value passed in to it.

Here's another example of why we need to decide this btw:

https://review.openstack.org/#/c/229471/

Here, we have some workers parameters, going only into controller.yaml -
this is fine, but the new options are completely invisible to users who
look at the overcloudwithoutmergepy parameters schema as their interface
(in particular I'm thinking of any UI here).

My personal preference is to say:

  1. Any templates which are included in the default environment (e.g
    overcloud-resource-registry-puppet.yaml), must expose their parameters
    via overcloud-without-mergepy.yaml

  2. Any templates which are included in the default environment, but via a
    "noop" implementation may expose their parameters provided they are
    common and not implementation/vendor specific.

  3. Any templates exposing vendor specific interfaces (e.g at least anything
    related to the OS::TripleO::ExtraConfig interfaces) must not expose any
    parameters via the top level template.

How does this sound?

This does mean we suffer some template bloat from (1) and (2), but it makes
the job of any UI or other tool requiring user input much easier, I think?

Steve


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Nov 19, 2015 by Steven_Hardy (16,900 points)   2 7 11
0 votes

On Thu, Nov 19, 2015 at 6:16 PM, Steven Hardy shardy@redhat.com wrote:

On Mon, Nov 16, 2015 at 08:15:48PM +0100, Giulio Fidente wrote:

On 11/16/2015 04:25 PM, Steven Hardy wrote:

Hi all,

I wanted to start some discussion re $subject, because it's been
apparrent
that we have a lack of clarity on this issue (and have done ever since
we
started using parameter_defaults).

[...]

How do people feel about this example, and others like it, where we're
enabling common, but not mandatory functionality?

At first I was thinking about something as simple as: "don't use
top-level
params for resources which the registry doesn't enable by default".

It seems to be somewhat what we tried to do with the existing pluggable
resources.

Also, not to hijack the thread but I wanted to add another question
related
to a similar issue:

Is there a reason to prefer use of parameters: instead of
parameter_defaults: in the environment files?

It looks to me that by defaulting to parameter_defaults: users won't
need to
update their environment files in case the parameter is moved from
top-level
into a specific nested stack so I'm inclined to prefer this. Are there
reasons not to?

The main reason is scope - if you use "parameters", you know the data flow
happens via the parent template (e.g overcloud-without-mergepy) and you
never have to worry about naming collisions outside of that template.

But if you use parameter_defaults, all parameters values defined that way
are effectively global, and you then have to be much more careful that you
never shadow a parameter name and get an unexpected value passed in to it.

Here's another example of why we need to decide this btw:

https://review.openstack.org/#/c/229471/

Here, we have some workers parameters, going only into controller.yaml -
this is fine, but the new options are completely invisible to users who
look at the overcloudwithoutmergepy parameters schema as their interface
(in particular I'm thinking of any UI here).

My personal preference is to say:

  1. Any templates which are included in the default environment (e.g
    overcloud-resource-registry-puppet.yaml), must expose their parameters
    via overcloud-without-mergepy.yaml

  2. Any templates which are included in the default environment, but via a
    "noop" implementation may expose their parameters provided they are
    common and not implementation/vendor specific.

I guess the TLS patch falls into this category. I would say that this needs
to be
documented somewhere though. So if there are parameters that would be
available via parameter defaults, then that should be visible somewhere.
Is there any preferred place to add such a thing?

  1. Any templates exposing vendor specific interfaces (e.g at least anything
    related to the OS::TripleO::ExtraConfig interfaces) must not expose any
    parameters via the top level template.

How does this sound?

This sounds reasonable. Though the same question as above applies.

This does mean we suffer some template bloat from (1) and (2), but it makes
the job of any UI or other tool requiring user input much easier, I think?

Steve


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

--
Juan Antonio Osorio R.
e-mail: jaosorior@gmail.com


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Nov 19, 2015 by Juan_Antonio_Osorio (2,900 points)   1 2
0 votes

On Thu, Nov 19, 2015 at 06:50:35PM +0200, Juan Antonio Osorio wrote:
On Thu, Nov 19, 2015 at 6:16 PM, Steven Hardy shardy@redhat.com wrote:

 On Mon, Nov 16, 2015 at 08:15:48PM +0100, Giulio Fidente wrote:
 > On 11/16/2015 04:25 PM, Steven Hardy wrote:
 > >Hi all,
 > >
 > >I wanted to start some discussion re $subject, because it's been
 apparrent
 > >that we have a lack of clarity on this issue (and have done ever
 since we
 > >started using parameter_defaults).
 >
 > [...]
 >
 > >How do people feel about this example, and others like it, where
 we're
 > >enabling common, but not mandatory functionality?
 >
 > At first I was thinking about something as simple as: "don't use
 top-level
 > params for resources which the registry doesn't enable by default".
 >
 > It seems to be somewhat what we tried to do with the existing
 pluggable
 > resources.
 >
 > Also, not to hijack the thread but I wanted to add another question
 related
 > to a similar issue:
 >
 >A  A Is there a reason to prefer use of parameters: instead of
 > parameter_defaults: in the environment files?
 >
 > It looks to me that by defaulting to parameter_defaults: users won't
 need to
 > update their environment files in case the parameter is moved from
 top-level
 > into a specific nested stack so I'm inclined to prefer this. Are there
 > reasons not to?

 The main reason is scope - if you use "parameters", you know the data
 flow
 happens via the parent template (e.g overcloud-without-mergepy) and you
 never have to worry about naming collisions outside of that template.

 But if you use parameter_defaults, all parameters values defined that
 way
 are effectively global, and you then have to be much more careful that
 you
 never shadow a parameter name and get an unexpected value passed in to
 it.

 Here's another example of why we need to decide this btw:

 https://review.openstack.org/#/c/229471/

 Here, we have some workers parameters, going only into controller.yaml -
 this is fine, but the new options are completely invisible to users who
 look at the overcloud_without_mergepy parameters schema as their
 interface
 (in particular I'm thinking of any UI here).

 My personal preference is to say:

 1. Any templates which are included in the default environment (e.g
 overcloud-resource-registry-puppet.yaml), must expose their parameters
 via overcloud-without-mergepy.yaml

 2. Any templates which are included in the default environment, but via
 a
 "noop" implementation *may* expose their parameters provided they are
 common and not implementation/vendor specific.

A
I guess the TLS patch falls into this category. I would say that this
needs to be
documented somewhere though. So if there are parameters that would be
available via parameter defaults, then that should be visible somewhere.
Is there any preferred place to add such a thing?

So far, we've just been documenting them via example environment files,
such as you have done e.g in environments/enable-tls.yaml

The problem with this is it's not something that's easily discoverable by
any user/UI, the values in the example aren't necessarily exhaustive, and
it's not convenient to have heat validate example environments like this,
because they typically contain dummy values the user must know to modify.

There is work going on to build a schema around these example environments:

But even with that in place, it doesn't provide a convenient interface for
the "common to most deployments" type options most deployers will want to
be exposed to.

 3. Any templates exposing vendor specific interfaces (e.g at least
 anything
 related to the OS::TripleO::*ExtraConfig* interfaces) must not expose
 any
 parameters via the top level template.

 How does this sound?

This sounds reasonable. Though the same question as above applies.

Same as above, example environments is all we have right now.

Steve


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Nov 19, 2015 by Steven_Hardy (16,900 points)   2 7 11
0 votes

My personal preference is to say:

  1. Any templates which are included in the default environment (e.g
    overcloud-resource-registry-puppet.yaml), must expose their parameters
    via overcloud-without-mergepy.yaml

  2. Any templates which are included in the default environment, but via a
    "noop" implementation may expose their parameters provided they are
    common and not implementation/vendor specific.

I think this makes sense. Two combination of these two represent what
TripleO views as the common* API for deploying.

  • "common" in the sense that you may not use all of them every time, but
    they are part of the expected deployments.

I still have concerns with us not treating this strongly enough as a
versioned API, but we can discuss that in a different thread. That's
more of a "when" we change the parameters v. the conventions on "how" we
do it.

  1. Any templates exposing vendor specific interfaces (e.g at least anything
    related to the OS::TripleO::ExtraConfig interfaces) must not expose any
    parameters via the top level template.

How does this sound?

This does mean we suffer some template bloat from (1) and (2), but it makes
the job of any UI or other tool requiring user input much easier, I think?

Steve


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Nov 19, 2015 by Jay_Dobies (3,120 points)   2 3
0 votes

On 11/16/2015 04:25 PM, Steven Hardy wrote:
Hi all,

I wanted to start some discussion re $subject, because it's been apparrent
that we have a lack of clarity on this issue (and have done ever since we
started using parameter_defaults).

Some context:

  • Historically TripleO has provided a fairly comprehensive "top level"
    parameters interface, where many per-role and common options are
    specified, then passed in to the respective ResourceGroups on deployment

https://git.openstack.org/cgit/openstack/tripleo-heat-templates/tree/overcloud-without-mergepy.yaml#n14

The nice thing about this approach is it gives a consistent API to the
operator, e.g the parameters schema for the main overcloud template defines
most of the expected inputs to the deployment.

The main disadvantage is a degree of template bloat, where we wire dozens
of parameters into each ResourceGroup, and from there into whatever nested
templates consume them.

  • When we started adding interfaces (such as all the OS::TripleO::ExtraConfig
    interfaces, there was a need to enable passing arbitrary additional
    values to nested templates, with no way of knowing what they are (e.g to
    enable wiring in third-party pieces we have no knowledge of or which
    require implementation-specific arguments which don't make sense for all
    deployments.

To do this, we made use of the heat parameter_defaults interface, which
(unlike normal parameters) have global scope (visible to all nested stacks,
without explicitly wiring in the values from the parent):

http://docs.openstack.org/developer/heat/template_guide/environment.html#define-defaults-to-parameters

The nice thing about this approach is its flexibility, any arbitrary
values can be provided without affecting the parent templates, and it can
allow for a terser implementation because you only specify the parameter
definition where it's actually used.

The main disadvantage of this approach is it becomes very much harder to
discover an API surface for the operator, e.g the parameters that must be
provided on deployment by any CLI/UI tools etc. This has been partially
addressed by the new-for-liberty nested validation heat feature, but
there's still a bunch of unsolved complexity around how to actually consume
that data and build a coherent consolidated API for user interaction:

https://github.com/openstack/heat-specs/blob/master/specs/liberty/nested-validation.rst

My question is, where do we draw the line on when to use each interface?

My position has always been that we should only use parameter_defaults for
the ExtraConfig interfaces, where we cannot know what reasonable parameters
are. And for all other "core" functionality, we should accept the increased
template verbosity and wire arguments in from overcloud-without-mergepy.

However we've got some patches which fall into a grey area, e.g this SSL
enablement patch:

https://review.openstack.org/#/c/231930/46/overcloud-without-mergepy.yaml

Here we're actually removing some existing (non functional) top-level
parameters, and moving them to parameter_defaults.

I can see the logic behind it, it does make the templates a bit cleaner,
but at the expense of discoverablility of those (probably not
implementation dependent) parameters.

How do people feel about this example, and others like it, where we're
enabling common, but not mandatory functionality?

In particular I'm keen to hear from Mainn and others interested in building
UIs on top of TripleO as to which is best from that perspective, and how
such arguments may be handled relative to the capabilities mapping proposed
here:

https://review.openstack.org/#/c/242439/

Thanks!

Steve


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

I think I'll try to do a bit of a recap to make sure I understand
things. It may shift slightly off the topic of this thread but I think
it is worth it and it will describe what the GUI is able/expecting to
work with.

Template defines parameters and passes them to child templates via
resource properties.
Root template parameter values are set by (in order of precedence):
1. 'parameters' param in 'stack create' api call or 'parameters' section
in environment
2. 'parameter_defaults' section in environment
3. 'default' in parameter definition in template

Non-root template parameter values are set by (in order of precedence):
1. parent resource properties
2. 'parameter_defaults' in environment
3. 'default' in parameter definition in template

The name collisions in parameter_defaults should not be a problem since
the template author should make sure, the parameters names he defines
don't collide with other templates.

The GUI's main goal (same as CLI and tripleo-common) is not to hardcode
anything and use THT (or any other set of files) which user provides as
a source of all information. It prepares deployment in several steps:
1. Plan Creation - uploads THT files and specifies root template.

  1. Environments selection - based on Capabilities map which is provided
    as part of THT (https://review.openstack.org/#/c/242439/) user picks
    which environments he intends to use for deployment.

  2. Parameters setting - Based on 2. tripleo-common runs heat template
    validation and input for GUI is nested parameters json structure. The
    output from GUI (through tripleo-common) is a new 'temporary'
    environment which holds values in 'parameters' section for root template
    parameters and values for nested parameters (without 'value') in
    'parameter_defaults' section.

This means that in GUI we'll provide form inputs for every parameter
from the root template and for the nested parameters which don't have a
'value' attribute.
The inputs will be pre-filled with 'default' value if parameter has one
provided (either from param_defaults or parameter definition).

I'll need to do more thinking about how what I describe here is affected
by what we are trying to solve in $subject...

  1. Deploy - for deployment, all environments are merged: Root
    Environment < Custom Environments < Temporary Environment.

Resource capabilities
I have put some thinking into resource capabilities spec usefulness when
I was creating the Capabilities map. I think it is much more useful to
specify multiple Environments which are mutually exclusive and implement
some functionality's configuration. It seems to be much better to make
the choice on the environment level rather then resourceregistry level,
because the selection of templates possible to use for implementing some
resource changes with the environments selected. So resource
capabilities depend on the Environments selected. So to make really
simple example, if we have a resource, which can be implemented by 2
templates, I'd create 2 environments which defines resource
registry
each with one of the templates available.

What I mean by this is, it is better to let user choose on the
environment level rather than on resource_registry level. Resource
capabilities could be valid in terms of providing validation that
certain template can be used to implement certain resource. Although
this seems not needed as the creator of Environment should make sure he
uses template which is able to implement that resource.

I should probably add this to the resource capabilities spec review.

Jirka


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Nov 20, 2015 by Jiri_Tomasek (2,240 points)   2 3
0 votes

Thinking about this some more makes me wonder if we need a sample config
generator like oslo.config. It would work off something similar to the
capabilities map, where you would say

SSL:
templates:
-puppet/extraconfig/tls/tls-cert-inject.yaml
output:
-environments/enable-ssl.yaml

And the tool would look at that, read all the params from
tls-cert-inject.yaml and generate the sample env file. We'd have to be
able to do a few new things with the params in order for this to work:

-Need to specify whether a param is intended to be set as a top-level
param, parameterdefaults (which we informally do today with the Can be
overridden by parameter
defaults comment), or internal, to define params
that shouldn't be exposed in the sample config and are only intended as
an interface between templates. There wouldn't be any enforcement of
the internal type, but Python relies on convention for its private
members so there's precedent. :-)
-There would have to be some way to pick out only certain params from a
template, since I think there are almost certainly features that are
configured using a subset of say puppet/controller.yaml which obviously
can't just take the params from an entire file. Although maybe this is
an indication that we could/should refactor the templates to move some
of these optional params into their own separate files (at this point I
think I should take a moment to mention that this is somewhat of a brain
dump, so I haven't thought through all of the implications yet and I'm
not sure it all makes sense).

The nice thing about generating these programmatically is we would
formalize the interface of the templates somewhat, and it would be
easier to keep sample envs in sync with the actual implementation.
You'd never have to worry about someone adding a param to a file but
forgetting to update the env (or at least it would be easy to catch and
fix when they did, just run "tox -e genconfig").

I'm not saying this is a simple or short-term solution, but I'm curious
what people think about setting this as a longer-term goal, because as I
think our discussion in Tokyo exposed, we're probably going to have a
bit of an explosion of sample envs soon and we're going to need some way
to keep them sane.

Some more comments inline.

On 11/19/2015 10:16 AM, Steven Hardy wrote:
On Mon, Nov 16, 2015 at 08:15:48PM +0100, Giulio Fidente wrote:

On 11/16/2015 04:25 PM, Steven Hardy wrote:

Hi all,

I wanted to start some discussion re $subject, because it's been apparrent
that we have a lack of clarity on this issue (and have done ever since we
started using parameter_defaults).

[...]

How do people feel about this example, and others like it, where we're
enabling common, but not mandatory functionality?

At first I was thinking about something as simple as: "don't use top-level
params for resources which the registry doesn't enable by default".

It seems to be somewhat what we tried to do with the existing pluggable
resources.

Also, not to hijack the thread but I wanted to add another question related
to a similar issue:

Is there a reason to prefer use of parameters: instead of
parameter_defaults: in the environment files?

It looks to me that by defaulting to parameter_defaults: users won't need to
update their environment files in case the parameter is moved from top-level
into a specific nested stack so I'm inclined to prefer this. Are there
reasons not to?

The main reason is scope - if you use "parameters", you know the data flow
happens via the parent template (e.g overcloud-without-mergepy) and you
never have to worry about naming collisions outside of that template.

But if you use parameter_defaults, all parameters values defined that way
are effectively global, and you then have to be much more careful that you
never shadow a parameter name and get an unexpected value passed in to it.

Here's another example of why we need to decide this btw:

https://review.openstack.org/#/c/229471/

Here, we have some workers parameters, going only into controller.yaml -
this is fine, but the new options are completely invisible to users who
look at the overcloudwithoutmergepy parameters schema as their interface
(in particular I'm thinking of any UI here).

My personal preference is to say:

  1. Any templates which are included in the default environment (e.g
    overcloud-resource-registry-puppet.yaml), must expose their parameters
    via overcloud-without-mergepy.yaml

  2. Any templates which are included in the default environment, but via a
    "noop" implementation may expose their parameters provided they are
    common and not implementation/vendor specific.

This seems like a reasonable approach, although that "may" still leaves
a lot of room for bikeshedding. ;-)

It might be good to say that in this case it is "preferred" to use a
top-level param, but if there's a reason not to then it's acceptable to
use parameter_defaults. An example for the SSL case would be the
certificate path - I specifically do not want that visibly exposed to
the user at this point, so I wouldn't want it added to the top-level
template. I consider that an implementation detail where if you know
what you're doing you can override it, but otherwise you shouldn't touch it.

  1. Any templates exposing vendor specific interfaces (e.g at least anything
    related to the OS::TripleO::ExtraConfig interfaces) must not expose any
    parameters via the top level template.

How does this sound?

This does mean we suffer some template bloat from (1) and (2), but it makes
the job of any UI or other tool requiring user input much easier, I think?

Steve


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Nov 21, 2015 by Ben_Nemec (19,660 points)   2 3 3
0 votes

On Sat, Nov 21, 2015 at 2:05 AM, Ben Nemec openstack@nemebean.com wrote:

Thinking about this some more makes me wonder if we need a sample config
generator like oslo.config. It would work off something similar to the
capabilities map, where you would say

SSL:
templates:
-puppet/extraconfig/tls/tls-cert-inject.yaml
output:
-environments/enable-ssl.yaml

And the tool would look at that, read all the params from
tls-cert-inject.yaml and generate the sample env file. We'd have to be
able to do a few new things with the params in order for this to work:

-Need to specify whether a param is intended to be set as a top-level
param, parameterdefaults (which we informally do today with the Can be
overridden by parameter
defaults comment), or internal, to define params
that shouldn't be exposed in the sample config and are only intended as
an interface between templates. There wouldn't be any enforcement of
the internal type, but Python relies on convention for its private
members so there's precedent. :-)

Perhaps a convention could be done in a similar fashion to how things are
done in
python. Where parameters passed from top-level could be defined as they are
defined
now (with camel-case type of definition) and non-top-parameters could be
defined with
lowercase and underscores (or with an underscore prefix). That could make
things
clearer and allow us to have a more programmatic approach in the future.

-There would have to be some way to pick out only certain params from a
template, since I think there are almost certainly features that are
configured using a subset of say puppet/controller.yaml which obviously
can't just take the params from an entire file. Although maybe this is
an indication that we could/should refactor the templates to move some
of these optional params into their own separate files (at this point I
think I should take a moment to mention that this is somewhat of a brain
dump, so I haven't thought through all of the implications yet and I'm
not sure it all makes sense).

The nice thing about generating these programmatically is we would
formalize the interface of the templates somewhat, and it would be
easier to keep sample envs in sync with the actual implementation.
You'd never have to worry about someone adding a param to a file but
forgetting to update the env (or at least it would be easy to catch and
fix when they did, just run "tox -e genconfig").

I think having such a tool is an excellent idea.

I'm not saying this is a simple or short-term solution, but I'm curious
what people think about setting this as a longer-term goal, because as I
think our discussion in Tokyo exposed, we're probably going to have a
bit of an explosion of sample envs soon and we're going to need some way
to keep them sane.

Some more comments inline.

On 11/19/2015 10:16 AM, Steven Hardy wrote:

On Mon, Nov 16, 2015 at 08:15:48PM +0100, Giulio Fidente wrote:

On 11/16/2015 04:25 PM, Steven Hardy wrote:

Hi all,

I wanted to start some discussion re $subject, because it's been
apparrent
that we have a lack of clarity on this issue (and have done ever since
we
started using parameter_defaults).

[...]

How do people feel about this example, and others like it, where we're
enabling common, but not mandatory functionality?

At first I was thinking about something as simple as: "don't use
top-level
params for resources which the registry doesn't enable by default".

It seems to be somewhat what we tried to do with the existing pluggable
resources.

Also, not to hijack the thread but I wanted to add another question
related
to a similar issue:

Is there a reason to prefer use of parameters: instead of
parameter_defaults: in the environment files?

It looks to me that by defaulting to parameter_defaults: users won't
need to
update their environment files in case the parameter is moved from
top-level
into a specific nested stack so I'm inclined to prefer this. Are there
reasons not to?

The main reason is scope - if you use "parameters", you know the data
flow
happens via the parent template (e.g overcloud-without-mergepy) and you
never have to worry about naming collisions outside of that template.

But if you use parameter_defaults, all parameters values defined that way
are effectively global, and you then have to be much more careful that
you
never shadow a parameter name and get an unexpected value passed in to
it.

Here's another example of why we need to decide this btw:

https://review.openstack.org/#/c/229471/

Here, we have some workers parameters, going only into controller.yaml -
this is fine, but the new options are completely invisible to users who
look at the overcloudwithoutmergepy parameters schema as their
interface
(in particular I'm thinking of any UI here).

My personal preference is to say:

  1. Any templates which are included in the default environment (e.g
    overcloud-resource-registry-puppet.yaml), must expose their parameters
    via overcloud-without-mergepy.yaml

  2. Any templates which are included in the default environment, but via a
    "noop" implementation may expose their parameters provided they are
    common and not implementation/vendor specific.

This seems like a reasonable approach, although that "may" still leaves
a lot of room for bikeshedding. ;-)

It might be good to say that in this case it is "preferred" to use a
top-level param, but if there's a reason not to then it's acceptable to
use parameter_defaults. An example for the SSL case would be the
certificate path - I specifically do not want that visibly exposed to
the user at this point, so I wouldn't want it added to the top-level
template. I consider that an implementation detail where if you know
what you're doing you can override it, but otherwise you shouldn't touch
it.

Well, the cert path, for instance, is not exposed as a top-level parameter
for
that reason, and even a warning comment was added to it. But for the SSL
case in general, my reasoning for using parameter_defaults was added as a
comment in the relevant CR https://review.openstack.org/#/c/231930/

  1. Any templates exposing vendor specific interfaces (e.g at least
    anything
    related to the OS::TripleO::ExtraConfig interfaces) must not expose any
    parameters via the top level template.

How does this sound?

This does mean we suffer some template bloat from (1) and (2), but it
makes
the job of any UI or other tool requiring user input much easier, I
think?

Steve


OpenStack Development Mailing List (not for usage questions)
Unsubscribe:
OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

--
Juan Antonio Osorio R.
e-mail: jaosorior@gmail.com


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Nov 23, 2015 by Juan_Antonio_Osorio (2,900 points)   1 2
0 votes

On 11/20/2015 07:05 PM, Ben Nemec wrote:
Thinking about this some more makes me wonder if we need a sample config
generator like oslo.config. It would work off something similar to the
capabilities map, where you would say

SSL:
templates:
-puppet/extraconfig/tls/tls-cert-inject.yaml
output:
-environments/enable-ssl.yaml

And the tool would look at that, read all the params from
tls-cert-inject.yaml and generate the sample env file. We'd have to be
able to do a few new things with the params in order for this to work:

-Need to specify whether a param is intended to be set as a top-level
param, parameterdefaults (which we informally do today with the Can be
overridden by parameter
defaults comment), or internal, to define params
that shouldn't be exposed in the sample config and are only intended as
an interface between templates. There wouldn't be any enforcement of
the internal type, but Python relies on convention for its private
members so there's precedent. :-)

There is new functionality in Heat that will let you pass in a series of
templates and environments and it will return:

  • The list of top-level parameters, the same way template-validate
    always did
  • A list of all nested parameters, keyed by resource.

Take a look at
https://github.com/openstack/heat-specs/blob/master/specs/liberty/nested-validation.rst
for details and an example.

That's not entirely what you're getting at, I realize that. I'm glad to
see you suggest a convention-based approach because I think that's the
only way we're going to be able to convey some of this information.

I think at the same time we add a mechanism to distinguish between
internal and external parameters, we need to add something to indicate
required v. optional.

With a nested stack, anything that's not part of the top-level parameter
contract is defaulted. The problem is that it loses information on what
is a valid default v. what's simply defaulted to pass validation.

I've been noticing this more and more on the vendor integrations. They
have parameters that are required (such as a username) and others that
are less likely to be changed (I can't think of an example, but I think
everyone can see where I'm going with this).

So I think there are two sorts of things (at least, I'm also thinking
off the top of my head) we'd like this tool/sample file to convey:

  • Parameters a user would want to change, as compared to those used for
    internal data shuffling
  • Information on if the user must supply a value, as compared to
    parameters with an actual default

All that said, I dig this idea of a tool that would generate a skeleton
environment file.

-There would have to be some way to pick out only certain params from a
template, since I think there are almost certainly features that are
configured using a subset of say puppet/controller.yaml which obviously
can't just take the params from an entire file. Although maybe this is
an indication that we could/should refactor the templates to move some
of these optional params into their own separate files (at this point I
think I should take a moment to mention that this is somewhat of a brain
dump, so I haven't thought through all of the implications yet and I'm
not sure it all makes sense).

The nice thing about generating these programmatically is we would
formalize the interface of the templates somewhat, and it would be
easier to keep sample envs in sync with the actual implementation.

You could go so far as to put CI on top of it like we do with the oslo
config stuff, which would be neat.

You'd never have to worry about someone adding a param to a file but
forgetting to update the env (or at least it would be easy to catch and
fix when they did, just run "tox -e genconfig").

I'm not saying this is a simple or short-term solution, but I'm curious
what people think about setting this as a longer-term goal, because as I
think our discussion in Tokyo exposed, we're probably going to have a
bit of an explosion of sample envs soon and we're going to need some way
to keep them sane.

Some more comments inline.

On 11/19/2015 10:16 AM, Steven Hardy wrote:

On Mon, Nov 16, 2015 at 08:15:48PM +0100, Giulio Fidente wrote:

On 11/16/2015 04:25 PM, Steven Hardy wrote:

Hi all,

I wanted to start some discussion re $subject, because it's been apparrent
that we have a lack of clarity on this issue (and have done ever since we
started using parameter_defaults).

[...]

How do people feel about this example, and others like it, where we're
enabling common, but not mandatory functionality?

At first I was thinking about something as simple as: "don't use top-level
params for resources which the registry doesn't enable by default".

It seems to be somewhat what we tried to do with the existing pluggable
resources.

Also, not to hijack the thread but I wanted to add another question related
to a similar issue:

Is there a reason to prefer use of parameters: instead of
parameter_defaults: in the environment files?

It looks to me that by defaulting to parameter_defaults: users won't need to
update their environment files in case the parameter is moved from top-level
into a specific nested stack so I'm inclined to prefer this. Are there
reasons not to?

The main reason is scope - if you use "parameters", you know the data flow
happens via the parent template (e.g overcloud-without-mergepy) and you
never have to worry about naming collisions outside of that template.

But if you use parameter_defaults, all parameters values defined that way
are effectively global, and you then have to be much more careful that you
never shadow a parameter name and get an unexpected value passed in to it.

Here's another example of why we need to decide this btw:

https://review.openstack.org/#/c/229471/

Here, we have some workers parameters, going only into controller.yaml -
this is fine, but the new options are completely invisible to users who
look at the overcloudwithoutmergepy parameters schema as their interface
(in particular I'm thinking of any UI here).

My personal preference is to say:

  1. Any templates which are included in the default environment (e.g
    overcloud-resource-registry-puppet.yaml), must expose their parameters
    via overcloud-without-mergepy.yaml

  2. Any templates which are included in the default environment, but via a
    "noop" implementation may expose their parameters provided they are
    common and not implementation/vendor specific.

This seems like a reasonable approach, although that "may" still leaves
a lot of room for bikeshedding. ;-)

It might be good to say that in this case it is "preferred" to use a
top-level param, but if there's a reason not to then it's acceptable to
use parameter_defaults. An example for the SSL case would be the
certificate path - I specifically do not want that visibly exposed to
the user at this point, so I wouldn't want it added to the top-level
template. I consider that an implementation detail where if you know
what you're doing you can override it, but otherwise you shouldn't touch it.

  1. Any templates exposing vendor specific interfaces (e.g at least anything
    related to the OS::TripleO::ExtraConfig interfaces) must not expose any
    parameters via the top level template.

How does this sound?

This does mean we suffer some template bloat from (1) and (2), but it makes
the job of any UI or other tool requiring user input much easier, I think?

Steve


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Nov 23, 2015 by Jay_Dobies (3,120 points)   2 3
...