qualisystems / toscana

:sunrise_over_mountains: :wine_glass: TOSCA .Net Analyzer

Toscana

What is Toscana?

Toscana, which stands for TOSCA Net Analyzer, is a .NET library for validating, parsing and analyzing TOSCA YAML format.

What is TOSCA?

TOSCA, which stands for Topology and Orchestration Specification for Cloud Applications, is a language in YAML grammar for describing service templates by means of Topology Templates and towards enablement of interaction with a TOSCA instance model perhaps by external APIs or plans.

To learn learn more about OASIS TOSCA visit OASIS Open Standards channel on YouTube

What is YAML?

YAML, which stands for "YAML Ain't Markup Language", is described as "a human friendly data serialization standard for all programming languages". Like XML, it allows to represent about any kind of data in a portable, platform-independent format. Unlike XML, it is "human friendly", which means that it is easy for a human to read or produce a valid YAML document.

Getting started

Install Toscana nuget package from from Manage Nuget packages

Or from Nuget Package Manager Console:

> install-package Toscana

Usage

There are two main file formats in the TOSCA standard: TOSCA Service Template and TOSCA Cloud Service Archive. The first one is in YML, while the last one is a ZIP file.

TOSCA Service Template

TOSCA YAML file is represented by ToscaServiceTemplate class in Toscana library. Toscana allows parsing a single TOSCA YAML file into an instance of ToscaServiceTemplate class. Even if the file depends on other TOSCA YAML files via imports parsing will succeeds.

Load a TOSCA Service Template file

ToscaServiceTemplate toscaServiceTemplate = ToscaServiceTemplate.Load("service-template.yaml");

Create a new TOSCA Service Template and save it to a file

ToscaServiceTemplate toscaServiceTemplate = new ToscaServiceTemplate
{
    ToscaDefinitionsVersion = "tosca_simple_yaml_1_0"
};
toscaServiceTemplate.NodeTypes.Add("node_type_name", new ToscaNodeType() );
toscaServiceTemplate.Save("service-template.yaml");

TOSCA Cloud Service Archive

TOSCA CSAR file is a ZIP compressed file which contains a set of TOSCA YAML files, drivers and icons, that represent cloud environment. The archive must contain the TOSCA.meta file, whcih points to the TOSCA YAML entry point file. If any of the TOSCA YAML files imports another YAML file that is missing in the archive, loading will fail.

Load a tosca.zip with all the imports included in the archive

ToscaCloudServiceArchive toscaCloudServiceArchive = ToscaCloudServiceArchive.Load("cloud-archive.zip");

Load a tosca.zip when some of the imports reside at alternative location

ToscaCloudServiceArchive toscaCloudServiceArchive = ToscaCloudServiceArchive.Load("cloud-archive.zip", @"c:\cloud-imports\");

Creating Cloud Service Archive

ToscaMetadata toscaMetadata = new ToscaMetadata
{ 
    CsarVersion = new Version(1,0,0), 
    EntryDefinitions = "entry.yaml", 
    ToscaMetaFileVersion = new Version(1,0,0), 
    CreatedBy = "Anonymous" 
};
ToscaServiceTemplate toscaServiceTemplate = new ToscaServiceTemplate
{
    ToscaDefinitionsVersion = "tosca_simple_yaml_1_0"
};
ToscaCloudServiceArchive cloudServiceArchive = new ToscaCloudServiceArchive(toscaMetadata);
cloudServiceArchive.AddToscaServiceTemplate("entry.yaml", toscaServiceTemplate);

Validating Cloud Service Archive

List<ValidationResult> results;
if ( !cloudServiceArchive.TryValidate(out results) )
{
    foreach(ValidationResult validationResult in results)
    {
        Console.WriteLine(validationResult.ErrorMessage);
    }
}

Documentation

Toscana documentation is powered by DocFX Documentation Generation Tool for API Reference and Markdown files based on XML documentation comments.

To build the documentation from command-line:

> docfx .\toscana.docs\docfx.json

To run a web server that hosts Toscana HTML documentation:

> docfx serve .\Toscana.Docs\_site

Powershell Module

Toscana is also available as a Powershell module that allows loading and validating Tosca related files.

Installation

PS>  Import-Module Toscana.PS\bin\Debug\Toscana.PS.dll

Loading Cloud Service Archive

PS>  Get-ToscaCloudServiceArchive Tosca.zip

Loading Cloud Service Archive with imports at alternative path

PS>  Get-ToscaCloudServiceArchive Tosca.zip C:\Imports

Loading Cloud Service Template

PS>  Get-ToscaServiceTemplate tosca.yaml

License

The software is released under Apache License v2.0.

toscana's Issues

Add validations

Since TOSCA Service Templates can import (or substitute in) other Service Templates, TOSCA Orchestrators and tooling will encounter the “tosca_definitions_version” statement for each imported template. In these cases, the following additional requirements apply:

o Imported type definitions with the same Namespace URI, local name and version SHALL be equivalent.
o If different values of the “tosca_definitions_version” are encountered, their corresponding type definitions MUST be uniquely identifiable using their corresponding Namespace URI using a different Namespace prefix.
· Duplicate local names (i.e., within the same Service Template SHALL be considered an error. These include, but are not limited to duplicate names found for the following definitions:
o Repositories (repositories)
o Data Types (data_types)
o Node Types (node_types)
o Relationship Types (relationship_types)
o Capability Types (capability_types)
o Artifact Types (artifact_types)
o Interface Types (interface_types)
· Duplicate Template names within a Service Template’s Topology Template SHALL be considered an error. These include, but are not limited to duplicate names found for the following template types:
o Node Templates (node_templates)
o Relationship Templates (relationship_templates)
o Inputs (inputs)
o Outputs (outputs)
o Groups (groups)
· Duplicate names for the following keynames within Types or Templates SHALL be considered an error. These include, but are not limited to duplicate names found for the following keynames:
o Properties (properties)
o Attributes (attributes)
o Artifacts (artifacts)
o Requirements (requirements)
o Capabilities (capabilities)
o Interfaces (interfaces)

Support custom attributes for sub modules

Add support for relationship_types

Add support for metadata

• File with metadata should be successfully parsed
• Metadata can be specified only once in imports. If a file specifies metadata, then files that it imports cannot specify metadata and vice versa.

As a user I want the parser to parse attribute tags

Move CI to appveyor

Look for artifacts in alternative location as well

As a user I would like to load TOSCA leaf file and its dependencies should be loaded automatically

Acceptance criteria:

Scenario
Load Tosca file, that imports another file with a node_type that derives from a node_type from imported file.

Assertions
Should contain definitions from parent node_type and from Tosca Root Node.
Description on the ToscaSimpleProfile level should be from the leaf file
Metadata should contain definitions from the leaf file