⇐ to main site

puccini-csar

Creating CSARs

Create either a tarball (gzip or plain) or a legacy ZIP file (using DEFLATE compression) with create. Examples:

puccini-csar create my/service/files csars/my-service.tar.gz
puccini-csar create my/service/files csars/my-service.tar
puccini-csar create my/service/files csars/my-service.zip
puccini-csar create my/service/files csars/my-service.csar # legacy zip extension

The directory can include subdirectories. Symbolic links will be followed. Hidden files and directories will be included.

For tarballs, if you need a compression algorithm other than gzip it’s easy enough to pipe to external tools: When the target path is not provided it will output a plain tarball to stdout. Example:

puccini-csar create my/service/files | xz --verbose > csars/my-service.tar.xz

If you have a TOSCA.meta file in the source directory then Puccini will parse and validate it. It can be either in the root or in the TOSCA-Metadata subdirectory (but not both).

But it’s not required. If Puccini doesn’t find the file then it will add a TOSCA.meta into the CSAR for you. It will be formatted (or reformatted) to fit in 80 columns by default. Note that it is always added to the CSAR archive first, before other entries. This is an optimization for tarballs (see below). Other file entries are added in alphabetical order to ensure deterministic results.

Note that timestamps in ZIP entries do not have timezone information. Puccini uses UTC, but other tools may interpret them differently. For example, Windows famously treats them as local time when unpacking.

You can explicitly set, add, or override)TOSCA.meta keys from the command line. Example:

puccini-csar create my/service/files csars/my-service.tar.gz \
  --created-by 'My Organization' \
  --entry-definitions definitions/extra1.yaml \
  --entry-definitions definitions/extra2.yaml

If the Entry-Definitions key is not provided, either via a flag or via a preexisting TOSCA.meta file, Puccini will look for a single .yaml or .yml file in the root directory and set the key accordingly.

In any case, create will ensure that Entry-Definitions and all Other-Definitions point to existing files before creating the CSAR. However, it will not validate the TOSCA contents. For that you can separately use puccini-tosca, either before creating the CSAR or on the created CSAR itself.

Add --dry-run to test all these heuristics without actually outputting the CSAR.

Validating Metadata

Validate and examine a CSAR’s TOSCA.meta with meta.

The command accepts either a file path or a URL. In both cases it will ensure that Entry-Definitions and all Other-Definitions exist. As with create, it will not validate the TOSCA contents. Again, for that you can use puccini-tosca on the CSAR.

Examples:

puccini-csar meta csars/my-service.tar.gz
puccini-csar meta https://site.org/csar/my-service.tar.gz
puccini-csar meta https://site.org/csar/my-service.zip
puccini-csar meta https://site.org/csar/my-service.csar

The meta command can output the meta information in a variety of formats. Examples:

puccini-csar meta csars/my-service.tar.gz --format json
puccini-csar meta https://site.org/csar/my-service.tar.gz --output meta.yaml

Note that if you need to use meta with remote CSARs, tarballs have an advantage: The TOSCA.meta entry will be read individually by streaming it, such that other entries will be skipped and ignored. By contrast, ZIP files must be entirely downloaded to the filesystem in order to access even one entry, which can be costly for large CSARs.

Accessing Contents

Because a CSAR is a standard tarball (or ZIP file) your standard tools should work on it. For example, let’s list contents:

tar --list --file csars/my-service.tar.gz
unzip -l csars/my-service.zip

And now let’s extract an artifact to stdout:

tar --extract --to-stdout --file csars/my-service.tar.gz TOSCA.meta
unzip -p csars/my-service.zip TOSCA.meta