Notes¶

This document holds a collection of arbitrary notes.

Filesystem¶

Home Directory¶

${vintner_home}/
├─ templates/
├─ instances/
├─ assets/
├─ plugins.yaml

Instance Directory¶

${vintner_home}/
├─ instances/
│  ├─ ${instance-name}/
│  │  ├─ data/
│  │  ├─ service-inputs/
│  │  │  ├─ ${timestamp}.yaml
│  │  ├─ templates/
│  │  │  ├─ ${timestamp}/
│  │  │  │  ├─ service-template.${timestamp}.yaml
│  │  │  │  ├─ variability-inputs.${timestamp}.yaml
│  │  │  │  ├─ variable-service-template.yaml
│  │  │  │  ├─ ...
│  │  ├─ info.yaml
│  │  ├─ ...
│  ├─ ...
├─ ...

Instance Info¶

Keyname	Mandatory	Type	Description
name	true	String	Instance name
state	true	String	Instance state
creation_timestamp	true	Number	ISO milliseconds of creation date
resolved_timestamp	false	Number	ISO milliseconds of latest variablity inputs and variability-resolved service template
template_timestamp	true	Number	ISO milliseconds of latest variable service template
service_inputs_timestamp	false	Number	ISO milliseconds of latest service inputs

Instance State Machine¶

Instance State Machine

Template Config¶

A template might have a config.yaml at root of the following type.

export type Config = {
    dependencies: Dependencies
}

export type Dependencies = TemplateDependency[]
export type TemplateDependency = {
    source: string
    target?: string
}

Workflows¶

Initialize a new Instance¶

vintner instances init

Instance directory is created.
Extracted CSAR (Template) is copied into instance template directory.
Instance info is updated

Resolve the Variability of an Instance¶

vintner instances resolve

Variability inputs are stored in the instance template directory.
Variability in variable service template is resolved based on given variability inputs.
Variability-resolved service template is stored in instance template directory.

Deploy an Instance¶

vintner instances deploy

Deployment inputs are copied to the service inputs directory.
Deployment command is sent to orchestrator. Variability-resolved service template is used.

Continue an Instance Deployment¶

vintner instances continue

Continue deployment command is sent to the orchestrator. Variability-resolve service templated is used. For example, to rerun a failed deployment.

Swap an Instance Template¶

vintner instances swap

New template is copied into (new) instance template directory
Instance info is updated

Update an Instance¶

vintner instances update

Deployment inputs are copied to the service inputs directory.
Instance info is updated.
Update command is sent to orchestrator. Variability-resolved service template is used.

Note, requires to resolve variability first. In contrast to deploying an instance, deployment inputs can be changed and the update command instead of the deploy command is sent to the orchestrator.

Adapt an Instance¶

vintner instances adapt

Sensor data is collected and stored as variability inputs.
Variability is resolved based on the new variability inputs.
Instance is updated based on the new variability-resolved topology template.
Instance info is updated.

In contrast to updating an instance template, adapting an instance regenerates the variability-resolve topology template and does not swap the variable topology template. In contrast to updating an instance, variability inputs change and variability is resolved.

Undeploy an Instance¶

vintner instances undeploy

Undeployment command is sent to orchestrator.

Delete an Instance¶

vintner instances delete

Instance directory is deleted.

Note, this does not undeploy the instance.

Conventions¶

get${data} returns path to the data, e.g., Instance#getServiceInputs.
load${data} returns data loaded from the filesystem, e.g. Instance#loadServiceInputs.
set${data} writes data to filesystem, e.g. Instance#setService.

General Helpful Tools on Linux¶

sudo apt-get update -y && sudo apt-get install sudo unzip tree nano wget jq net-tools curl git stress nmap -y

Put Some Stress on CPU and Memory¶

stress --cpu 18 --vm 36 --vm-bytes 1024M

Reverse SSH Tunnel¶

ssh -N -R 2999:192.168.178.46:3001 pi

Executable File under Windows¶

git update-index --chmod=+x <path to file>

bwCloud Blocked Ports¶

Some ports are blocked when using bwCloud: https://www.bw-cloud.org/de/bwcloud_scope/netzwerk

Naming Convention¶

Types should be named according to the following pattern.

type     = [domain]+.entity[.Name]+
entity   = "nodes" | "relationships" | "capabilities" | "artifacts" | "datatypes" | "groups
         | "policies" | "interfaces"
word     = ("a" ... "z" | "A" ... "Z")[word]
*        = word

Environment¶

All environment variables are prefixed by OPENTOSCA_VINTNER_. When the following environment variables are read, they are tried to be parsed as JSON. If they cannot be parsed, they are treated as string.

OPENTOSCA_VINTNER_VARIABILITY_PRESETS
OPENTOSCA_VINTNER_VARIABILITY_INPUT_${KEY}
OPENTOSCA_VINTNER_DEPLOYMENT_INPUT_${KEY}

These environment variables should be used with caution.

Lines of Code¶

Run the following command, to count the lines of code in the src folder.

1	`cloc src`

The following output has been generated for the commit 3c6d29df6b7fb52b39d46ffe179e6800b60c4398 on September 5th, 2024.

     376 text files.
     339 unique files.                                          
      39 files ignored.

github.com/AlDanial/cloc v 1.98  T=0.12 s (2936.0 files/s, 260917.4 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
TypeScript                     301           3529           2116          23146
YAML                             9             79              0            757
Bourne Shell                    21             77             80            250
EJS                              6             11              0             66
Python                           1              4              0             10
CSV                              1              0              0              1
-------------------------------------------------------------------------------
SUM:                           339           3700           2196          24230
-------------------------------------------------------------------------------

Adding a New Publication¶

Step-by-step guide
Zenodo
Integration tests
Entry in Publications
Git tag
Add used links

Used Links¶

The following links are used in publications.

https://github.com/opentosca/opentosca-vintner
https://github.com/OpenTOSCA/opentosca-vintner/actions/runs/6100939642/job/16556255878
https://vintner.opentosca.org
https://vintner.opentosca.org/variability4tosca/specification
https://vintner.opentosca.org/variability4tosca/guides/artifacts
https://vintner.opentosca.org/variability4tosca/guides/pruning
https://vintner.opentosca.org/variability4tosca/guides/modes

Typical Reasons for UNSAT¶

Technology constraint; can be disabled by technology_constraint: false
Artifact constraint; can be disabled by required_artifact_constraint: false
Required incoming relation constraint; can be disabled by required_incoming_relation_constraint: false
Due to some bug a node type or artifact type is not defined but a corresponding error is not thrown.

Limitations¶

We briefly discuss limitations of our prototypical implementation.

We expect that each relationship templates is used exactly once.
We expect that relationship at requirement assignments is a string.
We expect that names of hosting relations match /^(.*_)?host(_.*)?$/ since we do not implement the TOSCA type system.
We expect that names of connection relations match /^(.*_)?connection(_.*)?$/ since we do not implement the TOSCA type system.
We only support simple consumers, i.e., directly accessed by properties.
We only support simple producers, i.e., directly accessing the property of a node, using Unfurl eval Jinja filter, Unfurl eval intrinsic function, and TOSCA get_property intrinsic function, and assume that if the property is not found that it is either produced by an undefined property with a default value or by an attribute.
We only support Boolean variability inputs in variability input constraints.
We do not support default expressions of variability inputs in variability input constraints.

Last update: December 13, 2024