provide a little context
Change-Id: I81b1644fc536fe3630354a9f502670f030e89f2c
diff --git a/docs/README.md b/docs/README.md
index aeac2ca..4e24b9c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,23 +1,38 @@
-# XOS TOSCA User Manual
+# TOSCA Interface
-The `xos-tosca` container is responsible to autogenerate the TOSCA interface starting from the `xproto` definition.
+A TOSCA interface is available for configuring and controlling CORD. It is
+auto-generated from the set of [models](xos/README.md) configured
+into the POD manifest, and includes both core and service-specific models.
-<br/>
->In `CORD-4.0` this `TOSCA` engine is released as an `alpha` feature.
+>In `CORD-4.0` this `TOSCA` interface is released as an `alpha` feature.
## What is TOSCA?
-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.
+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.
-You can read more about it on the [OASIS](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=tosca) website.
+CORD extends the TOSCA specification to support custom models for
+services, allow operators to manage them with a simple and well-known
+YAML interface.
-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.
+## Internals
-## Overview
+The `xos-tosca` container autogenerates the TOSCA interface starting
+from the `xproto` definition. When the `xos-tosca` container starts,
+it connects to `xos-core`
+via the `gRPC` API to fetch all the `xproto` definition of the
+onboarded models. This includes both `core` and `service` models.
+Then using the `xos-genx` toolchain, it will generates the
+corresponding TOSCA specifications.
-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` is:
-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];
@@ -25,7 +40,8 @@
}
```
-Will be transformed in a TOSCA spec:
+which is then transformed in the following TOSCA spec:
+
```
tosca_definitions_version: tosca_simple_yaml_1_0
@@ -58,7 +74,15 @@
description: Node
```
-And a `node` can be added to `XOS` using this recipe:
+In TOSCA terminology, the above woule be called a `TOSCA node type`
+(although confusingly, it's defined for the `Node` model in CORD,
+which represents a server).
+
+## Using TOSCA
+
+Once CORD is up and running, a `node` can be added to a POD
+using the TOSCA interface by uploading the following recipe:
+
```
tosca_definitions_version: tosca_simple_yaml_1_0
@@ -75,4 +99,6 @@
type: tosca.nodes.Node
properties:
name: Grateful Vest
-```
\ No newline at end of file
+```
+
+In TOSCA terminology, the above would be called a `TOSCA node template`.