[CORD-1795] Document the new TOSCA engine
Change-Id: Ibaf94f9e680ecb780e76d971b5cad26405de106b
diff --git a/.gitignore b/.gitignore
index 900c131..3117408 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,4 +10,5 @@
coverage.xml
# hack
-xos
\ No newline at end of file
+xos
+_book
diff --git a/docs/README.md b/docs/README.md
index 018227d..aeac2ca 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,23 +1,78 @@
# XOS TOSCA User Manual
-## Development
+The `xos-tosca` container is responsible to autogenerate the TOSCA interface starting from the `xproto` definition.
-You'll need to have:
-- an XOS configuration running in the frontend vm
-- source the xos virtual env (from `xos` root: `source scripts/setup_venv.sh`)
-- install `xos-tosca` specific dependencies: `pip install -r requirements`
+<br/>
+>In `CORD-4.0` this `TOSCA` engine is released as an `alpha` feature.
-### Run the xos-tosca process
+## What is TOSCA?
-You can run this either from an IDE or:
-```bash
-python scr/main.py
+Topology and Orchestration Specification for Cloud Applications (TOSCA), is an OASIS standard language to describe a topology of cloud based web services, their components, relationships, and the processes that manage them. The TOSCA standard includes specifications to describe processes that create or modify web services.
+
+You can read more about it on the [OASIS](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=tosca) website.
+
+In XOS we are extending the TOSCA specification to support our custom models and let you manage them with a simple and well known YAML interface.
+
+## Overview
+
+When the `xos-tosca` container starts, it will connect to `xos-core` via the `gRPC` APIs to fetch all the `xproto` definition of the onboarded models, this include both `core` and `service` models. Then using the `xos-genx` toolchain it will generate TOSCA specification for them.
+
+For example, the `xproto` definition of a compute node in `XOS`:
+```
+message Node::node_policy (XOSBase) {
+ required string name = 1 [max_length = 200, content_type = "stripped", blank = False, help_text = "Name of the Node", null = False, db_index = False];
+ required manytoone site_deployment->SiteDeployment:nodes = 2 [db_index = True, null = False, blank = False];
+}
```
-### Sample call
+Will be transformed in a TOSCA spec:
+```
+tosca_definitions_version: tosca_simple_yaml_1_0
-To send an example request to `xos-tosca`:
-```bash
-curl -X POST --data-binary @test.yaml 127.0.0.1:9200
+node_types:
+
+ tosca.nodes.Node:
+ derived_from: tosca.nodes.Root
+ description: "An XOS Node"
+ capabilities:
+ node:
+ type: tosca.capabilities.xos.Node
+ properties:
+ must-exist:
+ type: boolean
+ default: false
+ description: Allow to reference existing models in TOSCA recipes
+ name:
+ type: string
+ required: false
+ description: "Name of the Node"
+
+
+ tosca.relationships.BelongsToOne:
+ derived_from: tosca.relationships.Root
+ valid_target_types: [ tosca.capabilities.xos.SiteDeployment ]
+
+
+ tosca.capabilities.xos.Node:
+ derived_from: tosca.capabilities.Root
+ description: Node
```
+And a `node` can be added to `XOS` using this recipe:
+```
+tosca_definitions_version: tosca_simple_yaml_1_0
+
+description: Load a compute node in XOS
+
+imports:
+ - custom_types/node.yaml
+
+topology_template:
+ node_templates:
+
+ # A compute node
+ GratefulVest:
+ type: tosca.nodes.Node
+ properties:
+ name: Grateful Vest
+```
\ No newline at end of file
diff --git a/docs/devel.md b/docs/devel.md
new file mode 100644
index 0000000..33c5f93
--- /dev/null
+++ b/docs/devel.md
@@ -0,0 +1,22 @@
+# Development
+
+To run a development environment locally, you'll need to have:
+- an XOS configuration running in the frontend vm
+- source the xos virtual env (from `xos` root: `source scripts/setup_venv.sh`)
+- install `xos-tosca` specific dependencies: `pip install -r requirements`
+- an entry in the `/etc/hosts` file that point `xos-core.opencord.org` to you local environment
+
+### Run the xos-tosca process
+
+You can run this either from an IDE or:
+```bash
+python scr/main.py
+```
+
+### Sample call
+
+To send an example request to `xos-tosca`:
+```bash
+curl -X POST --data-binary @test.yaml 127.0.0.1:9200
+```
+