[CORD-2585]
Lint check documentation with markdownlint
Change-Id: I763e019d6d7c781b8af74c4e0f12f55d318d9408
diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md
index e69de29..3bef333 100644
--- a/docs/GLOSSARY.md
+++ b/docs/GLOSSARY.md
@@ -0,0 +1,2 @@
+# XOS-TOSCA Glossary
+
diff --git a/docs/README.md b/docs/README.md
index 2d0c6e4..39e033c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,39 +1,36 @@
# TOSCA Interface
-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.
+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.
->In `CORD-4.0` this `TOSCA` interface is released as an `alpha` feature.
+> NOTE: 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. You can read
-more about it on the
+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.
-CORD extends the TOSCA specification to support custom models for
-services, allow operators to manage them with a simple and well-known
-YAML interface.
+CORD extends the TOSCA specification to support custom models for services,
+allow operators to manage them with a simple and well-known YAML interface.
## Internals
-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.
+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.
For example, the `xproto` definition of a compute node in `XOS` is:
-```
+```protobuf
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];
@@ -42,7 +39,7 @@
which is then transformed in the following TOSCA spec:
-```
+```yaml
tosca_definitions_version: tosca_simple_yaml_1_0
node_types:
@@ -62,12 +59,12 @@
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
@@ -83,7 +80,7 @@
Once CORD is up and running, a `node` can be added to a POD
using the TOSCA interface by uploading the following recipe:
-```
+```yaml
tosca_definitions_version: tosca_simple_yaml_1_0
description: Load a compute node in XOS
@@ -106,12 +103,14 @@
### Where to find the generated specs?
On any running CORD POD, the TOSCA apis are accessible as:
-```
+
+```shell
curl http://<head-node-ip>:<head-node-port>/xos-tosca | python -m json.tool
```
And it will return a list of all the recipes with the related url:
-```
+
+```json
{
"image": "/custom_type/image",
"site": "/custom_type/site",
@@ -120,7 +119,8 @@
```
For examples, to site the TOSCA spec of the Site model, you can use the URL:
-```
+
+```shell
curl http://<head-node-ip>:<head-node-port>/xos-tosca/custom_type/site
```
@@ -128,12 +128,14 @@
The `xos-tosca` container exposes two endpoint:
-```
+```shell
POST http://<head-node-ip>:<head-node-port>/xos-tosca/run
POST http://<head-node-ip>:<head-node-port>/xos-tosca/delete
```
To load a recipe via `curl` you can use this command:
-```
+
+```shell
curl -H "xos-username: xosadmin@opencord.org" -H "xos-password: <xos-password>" -X POST --data-binary @<path/to/file> http://<head-node-ip>:<head-node-port>/xos-tosca//run
```
+
diff --git a/docs/devel.md b/docs/devel.md
index 4a7f752..7586f3c 100644
--- a/docs/devel.md
+++ b/docs/devel.md
@@ -1,21 +1,26 @@
# 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 pip_requirements.txt`
-- an entry in the `/etc/hosts` file that point `xos-core.opencord.org` to you local environment
-### Run the xos-tosca process
+* 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
+ pip_requirements.txt`
+* 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
+## Sample call
To send an example request to `xos-tosca`:
+
```bash
curl -X POST --data-binary @test.yaml 127.0.0.1:9200
```