Hi Adam,
w.r.t. ârefiningâ the capability type inside a node template, we will take up that discussion in the TC. In the meantime, it seems that your example can easily be supported as follows:
node_templates:
myServer:
type: tosca.nodes.Compute
capabilities:
endpoint:
properties:
port: 22
protocol: ssh
Chris
From: adam souzis <adam@onecommons.org>
Sent: Wednesday, February 19, 2020 6:05 AM
To: Chris Lauwers <lauwers@ubicity.com>
Cc: tosca-comment@lists.oasis-open.org
Subject: Re: [tosca-comment] Feedback on TOSCA 1.3 spec
Hi Chris,
Responses inline below...
Hi Adam
Thanks again for the very helpful feedback. Some comments inline.
Here are some comments and questions that came up as I was implementing the specification, I hope you find them useful:
# Normative questions and comments:
* Unless I missed something, it appears that tosca identifiers (e.g. template names, property names etc.) are only defined as YAML strings. I assume this is under-specified? Given TOSCA's XML heritage and that namespace prefixes are still used, should they
be constrained to XML's NCName production (XML names without colons)?
I believe that in most (if not all) cases, the context makes it clear where the names are valid. For example, template names are only valid within the
context of a single topology template (and by implication a single service template). Property names are only valid within a specific type definition, etc. The only place where namespace prefixes are supported (and useful) is for the type definitions themselves,
since type definitions can be imported from other templates, which means that name collisions are possible. Do you have examples where the current naming scheme can create problems?
I was referring to the syntax of TOSCA names and identifiers in general -- unless I'm missing something, it appears that a name can be any valid YAML string, including ones containing whitespace, line feeds, non-normalized Unicode sequences,
etc. This makes it harder to build interoperable and secure implementations (think SQL injection attacks). For compatibility with XML you might want to consider constraining as I suggest above. Or maybe they should limited to be more like identifiers in a
programming language or to the syntax of DNS hostnames, as Kubernetes does. On the other hand, maybe it would be useful to allow a more liberal syntax so that any valid URI could be used as an identifier.
* The lists of node states in section 3.4.1 (p74) doesn't include "available" but it is used elsewhere in the spec. For example in the diagram on p.226. (That diagram also show the "delete" operation moving the node state from "configured" to "configured" --
I assume that is an error and it should be "stopped" and "deleted" respectively?). The example in section 7.3.3.1 (p260) also references an "available" state.
Yes, good catch. Clearly the text got out of sync with the diagrams. This needs to be corrected.
That said, this observation points to an issue weâve been working on in Version 2.0: the list of valid node states is defined as part of âTOSCA the languageâ,
but the specific states are modeled after the âStandardâ lifecycle management interface, which is part of âthe TOSCA type systemâ (i.e. the Simple Profile types). There are a number of instances in the specification where assumptions about the Simple Profile
types bleed over into the language itself. This makes it difficult to use TOSCA (the language) without also using the Simple Profile types. Weâre trying to remove such âbleed-overâ and create a cleaner separation between the language and the types. This could
mean that the âstateâ concept might need to be removed from the language, and instead be moved to an attribute of an Interface, for example (which would be defined in the type system, not in the language).
* metadata is allowed on property and attribute definitions but not on parameters (inputs and outputs) or on artifacts. Is this inconsistency an oversite? I have found it necessary to add metadata to input and artifact definitions.
Yes, metadata should be allowed pretty much everywhere (except possibly in property and attribute assignments). Weâll try to eliminate such inconsistencies.
* requirement assignments can specify the capability and relationship types but capability assignments can not. Is this an oversite? I found declaring the type in capability assignment necessary, for example, to specify that the "endpoint" capability of a node
template is a subtype of the generic "endpoint" capability.
Would you mind sharing a specific example? If I understand correctly, what youâre trying to do sounds like an âon-the-flyâ creation of a node sub-type
within a topology template. Iâd like to understand your use case better before commenting on this.
mytypes.capabilities.Endpoint.SSH:
derived_from: tosca.capabilities.Endpoint.Admin
description: Capability to connect to the host via SSH
properties:
protocol:
type: string
value: ssh
port:
type: tosca:PortDef
default: 22
type: tosca.nodes.Compute
endpoint: # declared in tosca.nodes.Compute as a tosca.capabilities.Endpoint.Admin
type: mytypes.capabilities.Endpoint.SSH
If I can't declare the capabiliy's type in the capability assignment, I'd be forced to declare a subtype of tosca.nodes.Compute that overrides tosca.nodes.Compute's "endpoint" and have the template use this new subtype. This is particularly
cumbersome because TOSCA doesn't support multiple inheritance or mixins, so this could lead to a combinatorial explosion of subtypes. More abstractly, TOSCA has a nominal type system and "requirements" and "capabilities" are essentially references to other
nodes -- and I can't think of a practical example of a nominal type system that doesn't allow covariant object references like ths.
* I have had to make other extensions to spec, some of which you may want to consider for a future version of TOSCA -- the list of changes are documented here:
https://www.onecommons.org/unfurl/tosca.html
Thanks, very helpful. By the way, Iâd like to repeat my invitation for you to join the TOSCA TC so we can discuss these during our regular meetings.
* The discussion in 13.4.1 Shell Scripts (p.360) about implementation outputs is confusing because it seems to imply that exporting an environment variable in shell script makes it available to the parent process when in fact doesn't (instead it makes it available
to child processes). To implement something like this the orchestrator would have to wrap or rewrite the shell script (that's what Yorc does) or place other requirements on the script -- for example, Cloudinary requires shell scripts to call a helper child
process to pass outputs back to the orchestrator.
Yes, this is actually more than an âeditorialâ error. Whatâs currently described wonât work
😊 If we want portably artifact processors, we need a common mechanism for shell scripts to return values back to the orchestrator. In my implementation,
I simply use âstdoutâ for this (with some additional shell script magic to make sure to keep log output separate from the actual output values). We should discuss what the best mechanism is for doing this.
OK, it wasn't clear to me that section was intending to specify interoperable shell implementations, I thought it was a non-normative discussion. In that case, my initial thoughts are: 1) for both interoperability and security reasons to
make sure whatever is specified doesn't require that implementations be executed in a shell environment (instead allow implementations where processes can be spawned directly by the orchestrator). 2) mandating the use of "stdout" is inflexible and error prone
(though perhaps there should be a reserved output variable that, if declared, captured that output) 3) Instead the orchestrator could set an environment variable that specified where output variables should be written 4) it would be better for that environment
variable to be set to a file descriptor (or handle on Windows) instead of a file path. (File descriptors being more secure (easier to avoid potential race conditions and information leaks) and more flexible (e.g. doesn't require opening a file, could be to
an IPC pipe, etc.))
* It would be extremely useful if the table of contents for Section 3 Definitions was more detailed -- the core YAML vocabulary is defined there and it's hard to find those definitions currently. (Or maybe there could be a separate table for definitions?)
Good suggestion. Weâll look into this.
* Section 5.3.6.5.1 (p 198) The example looks wrong, it should be:
<some_tosca_entity>:
properties:
my_credential:
user: myusername
token: mypassword
Yes, good catch. The example youâre referencing isnât even valid YAML, let alone valid TOSCA
😊
Weâre in the process of creating a github repo for all the examples in the text, which would allows us to run them through our various validation tools
which would hopefully prevent mistakes like these.
* Section 7.3.1.2: (p. 255) "on_success" should be a list
Yes, thanks.
* Section 13.4.1 Example on p. 360: âtemplate_nameâ, etc. should be inside âmetadata:â
Yes, better tooling will help.
In general, the specification document is quite comprehensive and useful, thank you for all your hard work on this.
Thanks, you are very kind. We know the spec has a long ways to go before its complete and correct. Comments like yours will help us get there.
Chris
|