Skip to content

Commit

Permalink
improve docs
Browse files Browse the repository at this point in the history
  • Loading branch information
milesstoetzner authored Jun 23, 2023
1 parent 5a52cf1 commit f9af1f6
Show file tree
Hide file tree
Showing 12 changed files with 110 additions and 107 deletions.
22 changes: 16 additions & 6 deletions docs/docs/queries4tosca/getting-started.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,13 @@
# Getting Started

This section will give a quick introduction to Queries4TOSCA. To run the example queries, you need to have a resolved instance of the
["Getting Started" template](../getting-started.md){target=_blank}. If you don't have one, follow the steps:
There is no standardized way to query TOSCA repositories or instance data.
Therefore, we introduce Queries4TOSCA which defined a query language for TOSCA.
This language provides a graph-based query language which includes path expressions, filters, and pattern matching.
This section will give a quick introduction to Queries4TOSCA.

## Preparation

To run the example queries, you need to install OpenTOSCA Vintner and have a resolved instance of the ["Getting Started" template](../getting-started.md){target=_blank}.
First, clone the repository.
--8<-- "clone.md"

Expand All @@ -15,7 +20,9 @@ vintner instances create --instance getting-started --template getting-started
vintner instances resolve --instance getting-started --inputs examples/xopera-getting-started/variability-inputs.example.yaml
```

Queries start with a `FROM` statement, followed by either `templates` or `instances` and the template respectively instance name.
## Example Queries

Queries start with a `FROM` statement, followed by either `templates` or `instances` and the name of the template or the name of the instance, respectively.
Inside a `SELECT` statement, you can enter a path to the data that you want to return.

To get the entire contents of the template, run the following command.
Expand Down Expand Up @@ -107,7 +114,7 @@ You can use an asterisk as a wildcard operator to get all child elements. The fo


You can also specify a predicate in square brackets after any part of the path expression to filter elements.
The following command will return only nodes of type `textfile`, which may be `first` or `second`, depending on how you resolved the template.
The following command will return only nodes of type `textfile`.

=== "Query"
```shell linenums="1"
Expand Down Expand Up @@ -159,8 +166,8 @@ Note the lack of quotation marks - we are using a value from the template for bo
- first: textfile
```

`MATCH` statements are used to match patterns in the topology of a template. You can "draw" the pattern by surrounding nodes
with parentheses and connect them to other nodes via arrows. The following statement will return all nodes that have a requirement fulfilled by `localhost`.
`MATCH` statements are used to match patterns in the topology of a template. You can "draw" the pattern by surrounding nodes with parentheses and connect them to other nodes via arrows.
The following statement will return all nodes that have a requirement fulfilled by `localhost`.

=== "Query"
```shell linenums="1"
Expand All @@ -180,3 +187,6 @@ with parentheses and connect them to other nodes via arrows. The following state
- host:
node: localhost
```

This is just a simple example.
In a more complex scenario, it would be possible, e.g., to dynamically access the public address of a virtual machine which hosts a database to which a specific component connects.
10 changes: 6 additions & 4 deletions docs/docs/queries4tosca/specification.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ Here are some examples.

```text linenums="1"
node_templates.localhost // Selecting a node directly by name
node_templates.localhost.# // Selecting attributes a node
node_templates.localhost.# // Selecting attributes of a node
node_templates.* // Selecting all nodes
GROUP(my-group) // Selecting all nodes in group 'my-group'
POLICY(my-policy) // Selecting all nodes targeted by policy 'my-policy'
Expand Down Expand Up @@ -133,7 +133,7 @@ evaluates to true.

```text linenums="1"
node_templates.*[type='textfile' AND name='first']
node_templates.*[name='frist' OR name='second']
node_templates.*[name='first' OR name='second']
```

### Return Structures
Expand Down Expand Up @@ -201,7 +201,7 @@ in the middle of the arrow.

It is also possible to search for node templates connected over multiple relationships by specifying a
cardinality. This can be accomplished by putting an asterisk at the end of a relationship, followed
optionally by a number or a range. If both are omitted, relationships of any length will be matched.
optionally by a number or a range.

```text linenums="1"
(a)-{*2}->(b) // exactly two hops between a and b
Expand All @@ -211,7 +211,9 @@ optionally by a number or a range. If both are omitted, relationships of any len
(a)-{*}->(b) // any amount of hops
```

## Grammar
## Appendix A "Grammar"

This appendix contains the complete [Ohm](https://ohmjs.org){target=_blank} grammar of Queries4TOSCA.

```text linenums="1"
Query {
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/sofdcar/profile.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ title: Profile
This document specifies the TOSCA Software-Defined Car (SofDCar) profile.
This profile includes normative TOSCA types for the domain of software-defined cars.
Standardizing such normative TOSCA types improves interoperability.
For example, an ECU supplier can model and distribute the deployment and management of his ECUs using these types.
For example, an ECU supplier can model and distribute the deployment and management of their ECUs using these types.
Various OEMs can then import provided models and integrate them into their cars.
The specification is under active development and is not backwards compatible with any previous versions.

Expand Down
8 changes: 4 additions & 4 deletions docs/docs/sofdcar/tosca-sofdcar-profile-non-normative.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ We specify the following node types.

#### sofdcar.nodes.Python.Application

Non-normative python application running on an HPC. This application required a python runtime.
Non-normative python application running on an HPC. This application requires a python runtime.


```yaml linenums="1"
Expand Down Expand Up @@ -36,13 +36,13 @@ sofdcar.nodes.Python.Runtime:
relationship: tosca.relationships.HostedOn
```
#### sofdcar.nodes.RaspberryPi
#### sofdcar.nodes.RaspberryPi.Hardware
The hardware of an Raspberry Pi serving as a HPC hardware. This Raspberry Pi is able to host HPC software. Furthermore, the Raspberry Pi is able to directly host python applications without explicit python runtime since a python runtime is already installed on the Raspberry Pi.
The hardware of an Raspberry Pi serving as a HPC hardware. This Raspberry Pi is able to host HPC software. Furthermore, the Raspberry Pi is able to directly host python applications without explicit python runtime since a python runtime is already installed on the Raspberry Pi.
```yaml linenums="1"
sofdcar.nodes.RaspberryPi:
sofdcar.nodes.RaspberryPi.Hardware:
derived_from: sofdcar.nodes.HPC.Hardware
capabilities:
host:
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/sofdcar/tosca-sofdcar-profile-non-normative.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ node_types:
sofdcar.nodes.Python.Application:
description: >
Non-normative python application running on an HPC.
This application required a python runtime.
This application requires a python runtime.
derived_from: sofdcar.nodes.HPC.Software
requirements:
- host:
Expand Down
8 changes: 4 additions & 4 deletions docs/docs/sofdcar/tosca-sofdcar-profile.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ sofdcar.capabilities.Host.ECU.Software:
#### sofdcar.capabilities.OperatingSystem.RealTime
The capability to provide an OS with real time
The capability to provide a real-time operating system.
```yaml linenums="1"
sofdcar.capabilities.OperatingSystem.RealTime:
Expand Down Expand Up @@ -382,7 +382,7 @@ The node all other accelerators are derived from.
```yaml linenums="1"
sofdcar.nodes.Accelerator:
derived_from: sofdcar.nodes.Root
derived_from: sofdcar.nodes.Actuator
```
#### sofdcar.nodes.Brake
Expand All @@ -391,7 +391,7 @@ The node all other brakes are derived from.
```yaml linenums="1"
sofdcar.nodes.Brake:
derived_from: sofdcar.nodes.Root
derived_from: sofdcar.nodes.Actuator
```
#### sofdcar.nodes.Steering
Expand All @@ -400,7 +400,7 @@ The node all other steerings are derived from.
```yaml linenums="1"
sofdcar.nodes.Steering:
derived_from: sofdcar.nodes.Root
derived_from: sofdcar.nodes.Actuator
```
#### sofdcar.nodes.Sensor
Expand Down
8 changes: 4 additions & 4 deletions docs/docs/sofdcar/tosca-sofdcar-profile.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ capability_types:
derived_from: tosca.capabilities.Container

sofdcar.capabilities.OperatingSystem.RealTime:
description: The capability to provide an OS with real time
description: The capability to provide a real-time operating system.
derived_from: tosca.capabilities.OperatingSystem
properties:
time_guarantee:
Expand Down Expand Up @@ -254,15 +254,15 @@ node_types:

sofdcar.nodes.Accelerator:
description: The node all other accelerators are derived from.
derived_from: sofdcar.nodes.Root
derived_from: sofdcar.nodes.Actuator

sofdcar.nodes.Brake:
description: The node all other brakes are derived from.
derived_from: sofdcar.nodes.Root
derived_from: sofdcar.nodes.Actuator

sofdcar.nodes.Steering:
description: The node all other steerings are derived from.
derived_from: sofdcar.nodes.Root
derived_from: sofdcar.nodes.Actuator

sofdcar.nodes.Sensor:
description: The node all other sensors are derived from.
Expand Down
11 changes: 4 additions & 7 deletions docs/docs/variability4tosca/guides/artifacts/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,19 +28,15 @@ curl -fsSL https://vintner.opentosca.org/install.sh | sudo bash -
vintner setup init
```

## Orchestrator

We currently support xOpera and Unfurl.
Since both can only be installed on Linux, we implemented a WSL integration for both.
In our case, we run on a Linux machine and use Unfurl.
Next, we configure Unfurl as the orchestrator that should be used for the deployment.
For more information see [Orchestrators](../../../orchestrators.md){target=_blank}.

```shell linenums="1"
vintner orchestrators init unfurl
vintner orchestrators enable --orchestrator unfurl
```

## Import
## Import the Template

!!! Warning "TODO"
- figures for vst
Expand Down Expand Up @@ -107,7 +103,8 @@ Afterward, you can undeploy the application.
vintner instances undeploy --instance artifacts
```

You can also optionally remove the instance and cleanup your filesystem (this will also removes other instances from the filesystem).
You can also optionally remove the instance or cleanup your filesystem.
Note, cleaning up the filesystem removes any vintner data including, e.g., all imported templates and created instances.

```shell linenums="1"
# (optional) Delete instance
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,7 @@ curl -fsSL https://vintner.opentosca.org/install.sh | sudo bash -
vintner setup init
```

## Orchestrator

We currently support xOpera and Unfurl.
Since both can only be installed on Linux, we implemented a WSL integration for both.
In our case, we run on a Linux machine and use xOpera.
Next, we need to configure xOpera as the orchestrator that should be used for the deployment.
For more information see [Orchestrators](../../../orchestrators.md){target=_blank}.

```shell linenums="1"
Expand Down
6 changes: 1 addition & 5 deletions docs/docs/variability4tosca/guides/pruning/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,7 @@ curl -fsSL https://vintner.opentosca.org/install.sh | sudo bash -
vintner setup init
```

## Orchestrator

We currently support xOpera and Unfurl.
Since both can only be installed on Linux, we implemented a WSL integration for both.
In our case, we run on a Linux machine and use xOpera.
Next, we need to configure xOpera as the orchestrator that should be used for the deployment.
For more information see [Orchestrators](../../../orchestrators.md){target=_blank}.

```shell linenums="1"
Expand Down
28 changes: 14 additions & 14 deletions docs/docs/variability4tosca/motivation/index.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,19 @@
# Motivation

In the following, we provide a detailed step-by-step tutorial to deploy the development variant of the motivating scenario.
The motivating scenario is a simple composite application that consists a web component and database.
In the following, we provide a detailed step-by-step tutorial to deploy the development variant of the motivating scenario, as presented in Figure 1.
The motivating scenario is a simple composite application that consists of a web component and a database.
This application can be deployed in different variants.
During development the application should be deployed on a single virtual machine whereas during production an elastic deployment is required and, therefore, the application is deployed on GCP.
During development the application should be deployed on a single virtual machine.
However, for the productive operation, an elastic deployment is required and, therefore, the application is deployed on Google Cloud Platform (GCP).

<figure markdown>
![Motivating Scenario](motivation.png){width="700"}
<figcaption>Figure 1: Motivating Scenario</figcaption>
<figcaption>Figure 1: The TOSCA models of our motivating scenario. The development variant on the left and the production variant on the right.</figcaption>
</figure>

## Requirements

You to fulfill the following requirements to follow this walkthrough.
You need to fulfill the following requirements to follow this step-by-step tutorial.

- Access to an OpenStack instance
- A machine having Ubuntu22.04 LTS installed
Expand All @@ -31,21 +32,19 @@ curl -fsSL https://vintner.opentosca.org/install.sh | sudo bash -
vintner setup init
```

We currently support xOpera and Unfurl.
Since both can only be installed on Linux, we implemented a WSL integration for both.
In our case, we run on a Linux machine and use xOpera.
Next, we need to configure xOpera as the orchestrator that should be used for the deployment.
For more information see [Orchestrators](../../orchestrators.md){target=_blank}.

```shell linenums="1"
vintner orchestrators init xopera
vintner orchestrators enable --orchestrator xopera
```

## Import
## Import the Template

<figure markdown>
![Motivating Scenario](variable-service-template.png){width="700"}
<figcaption>Figure 2: Variable Service Template</figcaption>
<figcaption>Figure 2: The Variability4TOSCA service template (variable service template) of our motivating scenario.</figcaption>
</figure>

First, we clone the repository.
Expand All @@ -63,7 +62,7 @@ vintner instances create --instance motivation --template motivation
```

We can optionally inspect the variable service template.
This template contains all possible elements having conditions assigned.
This template contains all possible elements having conditions assigned, as presented in Figure 2.
For example, the virtual machine hosted on OpenStack has a condition assigned that checks if the development variant has been chosen.

```shell linenums="1"
Expand All @@ -76,15 +75,15 @@ vintner templates inspect --template motivation

We intend to deploy the development variant of the application.
Therefore, we need to resolve the variability by providing respective variability inputs.
In our case, we can use an already predefined variability preset.
In our case, we can use already predefined variability inputs by using a variability preset.

```shell linenums="1"
# Resolve variability
vintner instances resolve --instance motivation --presets dev
```

You can optionally inspect the generated service template.
This template contains only the nodes required for the development variant.
This template contains only the nodes required for the development variant, as presented on the left in Figure 1.

```shell linenums="1"
# (optional) Inspect service template
Expand Down Expand Up @@ -114,7 +113,8 @@ Afterward, you can undeploy the application.
vintner instances undeploy --instance motivation
```

You can also optionally remove the instance and cleanup your filesystem (this will also removes other instances from the filesystem).
You can also optionally remove the instance or cleanup your filesystem.
Note, cleaning up the filesystem removes any vintner data including, e.g., all imported templates and created instances.

```shell linenums="1"
# (optional) Delete instance
Expand Down
Loading

0 comments on commit f9af1f6

Please sign in to comment.