RE: Query regarding get_artifact function used in implementation definitions with Tosca Yaml

[Chris Lauwers <lauwers@ubicity.com>]

Hi Dave, comments inline:

 

----- start message -----

 

Dear Tosca community

 

Can you help us to clarify the usage of the get_artifact function in a Tosca Yaml specified as a value for an implementation definition, found in this document:

https://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.3/os/TOSCA-Simple-Profile-YAML-v1.3-os.html

 

Specifically this section:

3.6.16.2.1 Short notation for use with single artifact

The following single-line grammar may be used when only a primary implementation artifact name is needed:

implementation: <primary_artifact_name>

This notation can be used when the primary artifact name uniquely identifies the artifact, either because it refers to a named artifact specified in the artifacts section of a type or template, or because it represents the name of a script in the CSAR file that contains the definition.

This description is somewhat lacking in my opinion and as a result is open for interpretation. My implementation in the Ubicity Orchestrator is based on the following interpretation:

1. What’s really going on here is that this is a concatenation of a number of different “short forms”. The full syntax for operation implementations is as follows:

implementation:

   primary: <primary_artifact_definition>

   dependencies:

     - <list_of_dependent_artifact_definitions>

2. In this syntax, the artifact definition uses the following keywords.

description: <artifact_description>

type: <artifact_type_name>

file: <artifact_file_URI>

repository: <artifact_repository_name>

deploy_path: <file_deployment_path>

version: <artifact _version>

checksum: <artifact_checksum>

checksum_algorithm: <artifact_checksum_algorithm>

properties: <property assignments>

3. There are two short notations that come into play. The first short notation is used when there is a primary artifact only without any dependent artifacts. In that case you can use the following short notation:

implementation:

   <primary_artifact_definition>

4. The second short notation comes into play when the primary artifact only defines the ‘file’ keyword and none of the others. In that case, you can use the following short notation:

implementation: artifact_file_URI

5. When this notation is used, it is possible to overload the “artifact_file_URI” to not refer to a file on disk, but to instead contain the name of an artifact that was previously defined inside the node or relationship type or inside the node template.
6. Whatever the “notation” is, the  “implementation” keyword expects an entire artifact entity as its value, not a string.

When specifying the implementation value (defined as “primary_artifact_name” above), is it valid to use the get_artifact function, such as:

 

== 1 ==

 

      interfaces:

        Vnflcm:

          instantiate:

            implementation: {get_artifact: [SELF, CREATE_ROUTER_SCRIPT]}

. . .

 

      artifacts:

        CREATE_ROUTER_SCRIPT:

          type: tosca.artifacts.Implementation.Python

          description: Generate chassis identifier

          file: ../Files/Scripts/create_router.py

 

The text description does not seem to explicitly forbid the get_artifact usage in this case, but I wanted confirmation as this is a point of slight confusion at the moment.

 

With the explanation above, I think it makes little sense to use the “get_artifact” function for operation implementations:

1. Contrary to what the name suggests, the “get_artifact” function does not actually return an artifact entity. Instead, it returns a string value that contains the path in the file system where the artifact file can be found.
2. Using the “short notation” summary above, the result of using the “get_artifact” function would be that the file location of the referenced artifact would be used as the value for the “file” keyword of the artifact that is used as the operation implementation. However
1. You lose all the other information associated with the artifact that was referenced by “get_artifact” (e.g. the type and the properties).
2. This is a silly level of indirection. It is more clear to reference the named artifact directly (as you do in your option ==2==)
3. There is a broader question of whether the use of intrinsic functions should be allowed as values for the “file” keyword in artifact definitions. I would argue that they shouldn’t since that would allow operators to provide operation implementations at deployment time rather than an design time.

 

OR, must a referenced artifact have only be referenced directly by name, such as:

 

== 2 ==

 

      interfaces:

        Vnflcm:

          instantiate:

            implementation: CREATE_ROUTER_SCRIPT

. . .

 

      artifacts:

        CREATE_ROUTER_SCRIPT:

          type: tosca.artifacts.Implementation.Python

          description: Generate chassis identifier

          file: ../Files/Scripts/create_router.py

 

OR, are both valid?

In my opinion, only option ==2== is valid.

 

I do realise that the actual script name “../Files/Scripts/create_router.py” can be specified for the implementation value such as:

 

== 3 ==

 

      interfaces:

        Vnflcm:

          instantiate:

            implementation: ../Files/Scripts/create_router.py

 

In theory, this is an option as well. However, this brings up the question of how an orchestrator will determine the type of the corresponding artifact (which is required to properly process the artifact). The specification states that an orchestrator can figure this out based on the file name extension, but this is error prone when multiple artifact types use the same extension (e.g. .yaml)

 

But unfortunately, this isn’t an option at the moment.

 

Much thanks for any input.

 

Cheers and have a good day!

 

Dave Webster

Software Engineer

Cisco Systems

 

Chris