The default format for output is YAML, but you can use JSON or XML instead with
that Clout in JSON may lose some type information (e.g. JSON doesn’t distinguish between an integer
and a float). XML output uses a bespoke structure for maps and lists.
For YAML you can add the additional
--strict/-y switch to output a stricter YAML, which adds
scalar type tags (such as
!!timestamp) and outputs all strings in double quotes
> notations. This is useful if you are consuming the YAML output with a
non-compliant or buggy parser.
Another YAML-specific switch is
--timestamps. By default Puccini will allow the YAML “!!timestamp”
type in its output. This type was included in YAML 1.1 but made optional in YAML 1.2. Most YAML
parsers should support it, but in case your YAML 1.2 parser doesn’t you can disable this feature by
setting this switch to false, in which case a canonical ISO-8601 (RFC-3339) string will be output
--pretty switch (enabled by default) attempts a more human-readable output, with indentation
and color highlighting in terminals. Disable this switch for a more compact output.
pucini-tosca supports “quirks”, via the
--quirk/-x switch, which are variations on the default
grammar rules. The reason this is required is unfortunate: the low quality of the TOSCA spec,
riddled as it is with gaps, inconsistencies, and errors, means that there’s too much room for
varying interpretations of the spec as well as missing functionality. Puccini aims to adhere as
closely as possible to the spec, literally and in spirit, but also must be pragmatic. Quirks allow
Puccini to smooth incompatibilities with other tools and work around a few TOSCA pain points.
Example of use:
puccini-tosca compile weird.yaml -x data_types.string.permissive
The list of supported quirks is maintained here.
Errors and Debugging
If TOSCA compilation or parsing fails it will emit a colorful problem report to stderr and exit with
code 1. You can use the
--quiet/-q to avoid output if all you want to do is check for success.
Logs are written to stderr (with colors) by default. Use
--log/-l to output to a file (without
--verbose/-v to add log verbosity. This can be used twice for maximum verbosity:
A simple trick for if you just want to see the logs on the console: just redirect stdout to
/dev/null (stderr will still be present):
puccini-tosca compile service.yaml -vv > /dev/null
The most common command is
compile. The optional input is a filesystem path or URL to a TOSCA
service template YAML file or a CSAR file. If no input is provided will attempt to read YAML
from stdin. By default the compiled Clout will be output to stdout, but you can use the
--output/-o switch to specify a file (or direct to a file in the shell via
puccini-tosca compile service.yaml --output clout.yaml
puccini-tosca compile service.yaml > clout.yaml
If your TOSCA service template YAML imports other units, and these imported paths are relative,
then Puccini will assume that they are relative to the base URL of the main service template file.
This allows you to move your files around, and even host them at a URL, without changing the file
contents. This works as expected even within a CSAR file because Puccini uses
zip: URLs to locate
files within it.
Also useful (or necessary) is the
--input/-i switch, which lets you set the inputs for the TOSCA
topology template. You may specify this switch multiple times for as many inputs as necessary.
The format is
value is YAML-encoded. For example, to set an integer:
To set a string:
To set a complex data type:
You can also load all inputs from YAML context located at a path or URL using the
--input/-i switch is processed after, so it can be used override values in the YAML
By default, the compiler will resolve the topology, which attempts to satisfy requirements with
capabilities and create relationships (Clout edges) between node templates. This can be disabled
puccini-tosca compile --resolve=false service.yaml
cat clout.yaml | puccini-clout scriptlet exec tosca.resolve
Read more about resolution here.
TOSCA functions and constraints are embedded in the Clout (as stubs) and are intended to be executed when necessary. Thus they not called during compilation, unless they are needed for topology resolution. If you want to call all of them and see the evaluated results, pipe the Clout through puccini-clout and execute the embedded tosca.coerce scriptlet:
cat clout.yaml | puccini-clout scriptlet exec tosca.coerce
Values can be re-coerced later according to changing attributes and other external factors.
As a convenience,
compile can call tosca.coerce for you via the
puccini-tosca compile --coerce service.yaml
Note that doing so means you do not get the original compiled output.
If you need more diagnostics for TOSCA parsing use the
parse command. It works similarly to
compile but does not emit Clout. Instead, it provides you various switches for examining the
internal workings of Puccini’s TOSCA parser.
--stop/-s to specify a phase (1-5) at which you wish the parser to stop.
This could be useful if you’re getting too many problems in your report and wish to minimize them to
a more manageable list. Note that
-s 0 will skip the TOSCA parser entirely and just check that the
YAML input is readable.
--dump/-d is used to dump the internal data of phases. You may specify multiple phases to dump
using “,”, e.g.
-d 2,3,4. Per phase you will see:
- Phase 1: Read. The hierarchy of imported units starting at the service template URL.
- Phase 2: Namespaces. All names per type. Each imported unit has its own namespace.
- Phase 3: Hierarchies. Tree of all types by fully qualified name. Each imported unit has its own type hierarchy.
- Phase 4: Inheritance. A tree of all inheritance tasks and their dependencies by path.
- Phase 5: Rendering. Dumps the rendered entities.
More useful, perhaps, would be the
--filter/-tswitch (see below).
--filter/-t switch can be used to filter for specific parsed entities. Each entity is given a
path that more-or-less follows JSON. For example, a path can be:
The switch will search for all paths that contains your string, e.g.
-t properties. You can even
include one or more “*” wildcards, e.g.