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
rhel_reg_activation_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:
resource_def:
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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
