README files: Convert from markdown to RST

Change-Id: I176f583e8adb7ba717932de7c27283f696ded548
Signed-off-by: Alexandru Avadanii <Alexandru.Avadanii@enea.com>

diff --git a/ci/README.rst b/ci/README.rst
index 9f1230d..dc860c0 100644 (file)
--- a/ci/README.rst
+++ b/ci/README.rst
@@ -13,7 +13,10 @@ OPNFV CI pipeline guideline:
 USAGE
 =====
 For usage information of the CI/CD scripts, please run:
 USAGE
 =====
 For usage information of the CI/CD scripts, please run:

-./deploy.sh -h
+
+    .. code-block:: bash
+
+        $ ./deploy.sh -h

 
 Details on the CI/CD deployment framework
 =========================================
 
 Details on the CI/CD deployment framework
 =========================================


@@ -41,8 +44,11 @@ Executing a deployment
 deploy.sh must be executed locally at the target lab/pod/jumpserver
 A configuration structure must be provided - see the section below.
 It is straight forward to execute a deployment task - as an example:
 deploy.sh must be executed locally at the target lab/pod/jumpserver
 A configuration structure must be provided - see the section below.
 It is straight forward to execute a deployment task - as an example:

-$ sudo deploy.sh -b file:///home/jenkins/config \
-  -l lf -p pod2 -s os-nosdn-nofeature-ha
+
+    .. code-block:: bash
+
+        $ sudo deploy.sh -b file:///home/jenkins/config
+                         -l lf -p pod2 -s os-nosdn-nofeature-ha

 
 -b and -i arguments should be expressed in URI style (eg: file://...
 or http://...). The resources can thus be local or remote.
 
 -b and -i arguments should be expressed in URI style (eg: file://...
 or http://...). The resources can thus be local or remote.


@@ -65,30 +71,32 @@ A local stripped version of this configuration structure with virtual
 deployment configurations also exist under build/config/.
 Following configuration directory and file structure should adheare to:
 
 deployment configurations also exist under build/config/.
 Following configuration directory and file structure should adheare to:
 

-TOP
-!
-+---- labs
-       !
-       +---- lab-name-1
-       !        !
-       !        +---- pod-name-1
-       !        !        !
-       !        !        +---- fuel
-       !        !               !
-       !        !               +---- config
-       !        !                       !
-       !        !                       +---- dea-pod-override.yaml
-       !        !                       !
-       !        !                       +---- dha.yaml
-       !        !
-       !        +---- pod-name-2
-       !                 !
-       !
-       +---- lab-name-2
-       !        !
+    .. code-block:: bash
+
+        TOP
+        !
+        +---- labs
+               !
+               +---- lab-name-1
+               !        !
+               !        +---- pod-name-1
+               !        !        !
+               !        !        +---- fuel
+               !        !               !
+               !        !               +---- config
+               !        !                       !
+               !        !                       +---- dea-pod-override.yaml
+               !        !                       !
+               !        !                       +---- dha.yaml
+               !        !
+               !        +---- pod-name-2
+               !                 !
+               !
+               +---- lab-name-2
+               !        !

 
 
 Creating a deployment scenario
 ------------------------------
 
 
 Creating a deployment scenario
 ------------------------------

-Please find deploy/scenario/README for instructions on how to create a new
+Please find `mcp/config/README.rst` for instructions on how to create a new

 deployment scenario.
 deployment scenario.

diff --git a/mcp/config/scenario/README.rst b/mcp/config/scenario/README.rst
index e0f9848..389877a 100644 (file)
--- a/mcp/config/scenario/README.rst
+++ b/mcp/config/scenario/README.rst
@@ -9,6 +9,7 @@ Abstract:
 ---------
 This directory contains configuration files for different OPNFV deployment
 feature scenarios used by Fuel@OPNFV, e.g.:
 ---------
 This directory contains configuration files for different OPNFV deployment
 feature scenarios used by Fuel@OPNFV, e.g.:

+

 - High availability configuration;
 - Type of SDN controller to be deployed;
 - OPNFV collaboration project features to be deployed;
 - High availability configuration;
 - Type of SDN controller to be deployed;
 - OPNFV collaboration project features to be deployed;

diff --git a/mcp/patches/README.rst b/mcp/patches/README.rst
index 81717b9..735b703 100644 (file)
--- a/mcp/patches/README.rst
+++ b/mcp/patches/README.rst
@@ -2,6 +2,7 @@
 .. SPDX-License-Identifier: CC-BY-4.0
 .. (c) 2017 Mirantis Inc., Enea AB and others.
 
 .. SPDX-License-Identifier: CC-BY-4.0
 .. (c) 2017 Mirantis Inc., Enea AB and others.
 

+==========================================

 Fuel@OPNFV submodule fetching and patching
 ==========================================
 
 Fuel@OPNFV submodule fetching and patching
 ==========================================
 


@@ -10,98 +11,135 @@ working with upstream Fuel/MCP components (e.g.: reclass-system-salt-model) in
 developing/applying OPNFV patches (backports, custom fixes etc.).
 
 The scripts should be friendly to the following 2 use-cases:
 developing/applying OPNFV patches (backports, custom fixes etc.).
 
 The scripts should be friendly to the following 2 use-cases:

+

   - development work: easily cloning, binding repos to specific commits,
     remote tracking, patch development etc.;
   - to provide parent build scripts an easy method of tracking upstream
     references and applying OPNFV patches on top;
 
 Also, we need to support at least the following modes of operations:
   - development work: easily cloning, binding repos to specific commits,
     remote tracking, patch development etc.;
   - to provide parent build scripts an easy method of tracking upstream
     references and applying OPNFV patches on top;
 
 Also, we need to support at least the following modes of operations:

+

   - submodule bind - each submodule patches will be based on the commit ID
     saved in the .gitmodules config file;
   - remote tracking - each submodule will sync with the upstream remote
     and patches will be applied on top of <sub_remote>/<sub_branch>/HEAD;
 
 Workflow (development)
   - submodule bind - each submodule patches will be based on the commit ID
     saved in the .gitmodules config file;
   - remote tracking - each submodule will sync with the upstream remote
     and patches will be applied on top of <sub_remote>/<sub_branch>/HEAD;
 
 Workflow (development)

-----------------------
+======================
+

 The standard development workflow should look as follows:
 
 The standard development workflow should look as follows:
 

-1. Decide whether remote tracking should be active or not:
-   NOTE: Setting the following var to any non-empty str enables remote track.
-   NOTE: Leaving unset will enable remote track for anything but stable branch.
+Decide whether remote tracking should be active or not
+------------------------------------------------------
+
+NOTE: Setting the following var to any non-empty str enables remote track.
+
+NOTE: Leaving unset will enable remote track for anything but stable branch.
+
+    .. code-block:: bash
+
+        $ export FUEL_TRACK_REMOTES=""
+
+Initialize git submodules
+-------------------------
+
+All Fuel sub-projects are registered as submodules.
+If remote tracking is active, upstream remote is queried and latest remote
+branch HEAD is fetched. Otherwise, checkout commit IDs from .gitmodules.

 
 

-   $ export FUEL_TRACK_REMOTES=""
+    .. code-block:: bash

 
 

-2. All Fuel sub-projects are registered as submodules. To initialize them, call:
-   If remote tracking is active, upstream remote is queried and latest remote
-   branch HEAD is fetched. Otherwise, checkout commit IDs from .gitmodules.
+        $ make sub

 
 

-   $ make sub
+Apply patches from `patches/<sub-project>/*` to respective submodules
+---------------------------------------------------------------------

 
 

-3. Apply patches from `patches/<sub-project>/*` to respective submodules via:
+This will result in creation of:

 
 

-   $ make patches-import
+- a tag called `${FUEL_MAIN_TAG}-opnfv-root` at the same commit as Fuel@OPNFV
+  upstream reference (bound to git submodule OR tracking remote HEAD);
+- a new branch `opnfv-fuel` which will hold all the OPNFV patches,
+  each patch is applied on this new branch with `git-am`;
+- a tag called `${FUEL_MAIN_TAG}-opnfv` at `opnfv-fuel/HEAD`;

 
 

-   This will result in creation of:
-   - a tag called `${FUEL_MAIN_TAG}-opnfv-root` at the same commit as Fuel@OPNFV
-     upstream reference (bound to git submodule OR tracking remote HEAD);
-   - a new branch `opnfv-fuel` which will hold all the OPNFV patches,
-     each patch is applied on this new branch with `git-am`;
-   - a tag called `${FUEL_MAIN_TAG}-opnfv` at `opnfv-fuel/HEAD`;
+    .. code-block:: bash

 
 

-4. Modify sub-projects for whatever you need.
-   Commit your changes when you want them taken into account in the build.
+        $ make patches-import

 
 

-5. Re-create patches via:
+Modify sub-projects for whatever you need
+-----------------------------------------

 
 

-   $ make patches-export
+Commit your changes when you want them taken into account in the build.

 
 

-   Each commit on `opnfv-fuel` branch of each subproject will be
-   exported to `patches/subproject/` via `git format-patch`.
+Re-create patches
+-----------------

 
 

-   NOTE: Only commit (-f) submodules when you need to bump upstream ref.
-   NOTE: DO NOT commit patched submodules!
+Each commit on `opnfv-fuel` branch of each subproject will be
+exported to `patches/subproject/` via `git format-patch`.

 
 

-6. Clean workbench branches and tags with:
+NOTE: Only commit (-f) submodules when you need to bump upstream ref.

 
 

-   $ make clean
+NOTE: DO NOT commit patched submodules!

 
 

-7. De-initialize submodules and force a clean clone with:
+    .. code-block:: bash

 
 

-   $ make deepclean
+        $ make patches-export
+
+Clean workbench branches and tags
+---------------------------------
+
+    .. code-block:: bash
+
+        $ make clean
+
+De-initialize submodules and force a clean clone
+------------------------------------------------
+
+    .. code-block:: bash
+
+        $ make deepclean

 
 Sub-project maintenance
 
 Sub-project maintenance

------------------------
-1. Adding a new submodule
-   If you need to add another subproject, you can do it with `git submodule`.
-   Make sure that you specify branch (with `-b`), short name (with `--name`):
+=======================
+
+Adding a new submodule
+----------------------
+
+If you need to add another subproject, you can do it with `git submodule`.
+Make sure that you specify branch (with `-b`), short name (with `--name`):
+
+    .. code-block:: bash
+
+        $ git submodule -b master add --name reclass-system-salt-model
+          https://github.com/Mirantis/reclass-system-salt-model
+          relative/path/to/submodule

 
 

-   $ git submodule -b master add --name reclass-system-salt-model \
-     https://github.com/Mirantis/reclass-system-salt-model \
-     relative/path/to/submodule
+Working with remote tracking for upgrading Fuel components
+----------------------------------------------------------

 
 

-2. Working with remote tracking for upgrading Fuel components
-   Enable remote tracking as described above, which at `make sub` will update
-   ALL submodules (e.g. reclass-system-salt-model) to remote branch (set in
-   .gitmodules) HEAD.
+Enable remote tracking as described above, which at `make sub` will update
+ALL submodules (e.g. reclass-system-salt-model) to remote branch (set in
+.gitmodules) HEAD.

 
 

-   * If upstream has NOT already tagged a new version, we can still work on
-     our patches, make sure they apply etc., then check for new upstream
-     changes (and that our patches still apply on top of them) by:
+* If upstream has NOT already tagged a new version, we can still work on
+  our patches, make sure they apply etc., then check for new upstream
+  changes (and that our patches still apply on top of them) by:

 
 

-   $ make deepclean patches-import
+* If upstream has already tagged a new version we want to pick up, checkout
+  the new tag in each submodule:

 
 

-   * If upstream has already tagged a new version we want to pick up, checkout
-     the new tag in each submodule:
+* Once satisfied with the patch and submodule changes, commit them:

 
 

-   $ git submodule foreach 'git checkout <newtag>'
+  - enforce FUEL_TRACK_REMOTES to "yes" if you want to constatly use the
+    latest remote branch HEAD (as soon as upstream pushes a change on that
+    branch, our next build will automatically include it - risk of our
+    patches colliding with new upstream changes);
+  - stage patch changes if any;
+  - if submodule tags have been updated (relevant when remote tracking is
+    disabled, i.e. we have a stable upstream baseline), add submodules;

 
 

-   * Once satisfied with the patch and submodule changes, commit them:
-     - enforce FUEL_TRACK_REMOTES to "yes" if you want to constatly use the
-       latest remote branch HEAD (as soon as upstream pushes a change on that
-       branch, our next build will automatically include it - risk of our
-       patches colliding with new upstream changes);
-     - stage patch changes if any;
-     - if submodule tags have been updated (relevant when remote tracking is
-       disabled, i.e. we have a stable upstream baseline), add submodules:
+        .. code-block:: bash

 
 

-   $ make deepclean sub && git add -f relative/path/to/submodule
+            $ make deepclean patches-import
+            $ git submodule foreach 'git checkout <newtag>'
+            $ make deepclean sub && git add -f relative/path/to/submodule

diff --git a/prototypes/sfc_tacker/README.rst b/prototypes/sfc_tacker/README.rst
index 27574a6..e219abd 100644 (file)
--- a/prototypes/sfc_tacker/README.rst
+++ b/prototypes/sfc_tacker/README.rst
@@ -5,10 +5,11 @@
 README SFC + Tacker
 ===================
 
 README SFC + Tacker
 ===================
 

-     The Enclosed shell script builds, deploys, orchestrates Tacker,
+The Enclosed shell script builds, deploys, orchestrates Tacker,

 an Open NFV Orchestrator with in-built general purpose VNF Manager
 to deploy and operate Virtual Network Functions (VNFs).
 an Open NFV Orchestrator with in-built general purpose VNF Manager
 to deploy and operate Virtual Network Functions (VNFs).

-      The provided deployment tool is experimental, not fault
+
+The provided deployment tool is experimental, not fault

 tolerant but as idempotent as possible. To use the provided shell
 script for provision/deployment, transfer the script to the Openstack
 primary controller node,  where Your deployed OpenDaylight SDN
 tolerant but as idempotent as possible. To use the provided shell
 script for provision/deployment, transfer the script to the Openstack
 primary controller node,  where Your deployed OpenDaylight SDN


@@ -16,20 +17,28 @@ controller runs. The deployment tool (poc.tacker-up.sh), expects that
 Your primary controller reaches all your OPNFV/Fuel cluster nodes and
 has internet connection either directly or via an http proxy, note
 that a working and consistent DNS name resolution is a must.
 Your primary controller reaches all your OPNFV/Fuel cluster nodes and
 has internet connection either directly or via an http proxy, note
 that a working and consistent DNS name resolution is a must.

-        Theory of operation: the deployment tool downloads the source
+
+Theory of operation: the deployment tool downloads the source

 python packages from GitHub and a json rpc library developed by Josh
 Marshall. Besides these sources, downloads software for python/debian
 software release. When building succeeds the script deploys the software
 components to the OPNFV Cluster nodes. Finally orchestrates the deployed
 tacker binaries as an infrastucture/service. The Tacker has two
 components:
 python packages from GitHub and a json rpc library developed by Josh
 Marshall. Besides these sources, downloads software for python/debian
 software release. When building succeeds the script deploys the software
 components to the OPNFV Cluster nodes. Finally orchestrates the deployed
 tacker binaries as an infrastucture/service. The Tacker has two
 components:

-o Tacker server - what interacts with Openstack and OpenDayLight.
-o Tacker client - a command line software talks with the server,
-                  available on all cluster nodes and the access point
-                  to the Tacker service. Note that the tacker
-                  distribution provides a a plugin to the Horizon
-                  OpenStack Gui, but thus Horizon plugin is out of the
-                  scope of this Proof of Concept setup/deployment.
+
+#. Tacker server
+
+   - what interacts with Openstack and OpenDayLight.
+
+#. Tacker client
+
+   - a command line software talks with the server,
+     available on all cluster nodes and the access point
+     to the Tacker service. Note that the tacker
+     distribution provides a a plugin to the Horizon
+     OpenStack Gui, but thus Horizon plugin is out of the
+     scope of this Proof of Concept setup/deployment.
+

 As mentioned, this compilation contains an OpenDayLight SDN controller
 with Service Function Chaining and Group based Policy features enabled.
 
 As mentioned, this compilation contains an OpenDayLight SDN controller
 with Service Function Chaining and Group based Policy features enabled.
 


@@ -37,13 +46,17 @@ To acces for your cluster information ssh to the fuel master (10.20.0.2)
 and issue command: fuel node.
 Here is an output of an example deployment:
 
 and issue command: fuel node.
 Here is an output of an example deployment:
 

-id | status | name             | cluster | ip        | mac               | roles                            | pending_roles | online | group_id
----|--------|------------------|---------|-----------|-------------------|----------------------------------|---------------|--------|---------
-3  | ready  | Untitled (a2:4c) | 1       | 10.20.0.5 | 52:54:00:d3:a2:4c | compute                          |               | True   | 1
-4  | ready  | Untitled (c7:d8) | 1       | 10.20.0.3 | 52:54:00:00:c7:d8 | cinder, controller, opendaylight |               | True   | 1
-1  | ready  | Untitled (cc:51) | 1       | 10.20.0.6 | 52:54:00:1e:cc:51 | compute                          |               | True   | 1
-2  | ready  | Untitled (e6:3e) | 1       | 10.20.0.4 | 52:54:00:0c:e6:3e | compute                          |               | True   | 1
-[root@fuel-sfc-virt ~]#
++--------+------------+------------------+-------------+-----------+-------------------+----------------------------------+-------------------+------------+--------------+
+| **id** | **status** | **name**         | **cluster** | **ip**    | **mac**           | **roles**                        | **pending_roles** | **online** | **group_id** |
++--------+------------+------------------+-------------+-----------+-------------------+----------------------------------+-------------------+------------+--------------+
+|   1    |   ready    | Untitled (cc:51) | 1           | 10.20.0.6 | 52:54:00:1e:cc:51 | compute                          |                   | True       | 1            |
++--------+------------+------------------+-------------+-----------+-------------------+----------------------------------+-------------------+------------+--------------+
+|   2    |   ready    | Untitled (e6:3e) | 1           | 10.20.0.4 | 52:54:00:0c:e6:3e | compute                          |                   | True       | 1            |
++--------+------------+------------------+-------------+-----------+-------------------+----------------------------------+-------------------+------------+--------------+
+|   3    |   ready    | Untitled (a2:4c) | 1           | 10.20.0.5 | 52:54:00:d3:a2:4c | compute                          |                   | True       | 1            |
++--------+------------+------------------+-------------+-----------+-------------------+----------------------------------+-------------------+------------+--------------+
+|   4    |   ready    | Untitled (c7:d8) | 1           | 10.20.0.3 | 52:54:00:00:c7:d8 | cinder, controller, opendaylight |                   | True       | 1            |
++--------+------------+------------------+-------------+-----------+-------------------+----------------------------------+-------------------+------------+--------------+

 
 As You can see in this case the poc.tacker-up.sh script should be
 transferred and run on node having IP address 10.20.0.3
 
 As You can see in this case the poc.tacker-up.sh script should be
 transferred and run on node having IP address 10.20.0.3