section 1 (#5)

* initial toc * fixed index for readthedocs * added mkdocs for forcing the toc structure * fixed indentation * fixed node operation error in mkdocs compilation * restructured the repository * added missing index page in mkdocs.yml * fixed linter issues * enabled readthedocs build in the ci process * fixing few linting issues and applying comments * added new rules to the md linting added python 2.7 to the ci-build * include section 1 * minor fixes * fix code print * try to fix index * fix index * fix levels and code * fix code * increase indent * fixes * fix syntax * disable md41 * apply @taliaga review * clean old toc
martel-innovate · Nov 9, 2018 · 9174662 · 9174662
1 parent aac51b1
commit 9174662
Show file tree

Hide file tree

Showing 23 changed files with 196 additions and 77 deletions.
diff --git a/.markdownlintrc b/.markdownlintrc
@@ -13,5 +13,9 @@
   "commands-show-output": false,
   "no-trailing-punctuation": {
     "punctuation": ".,;:!"
-  }
+  },
+  "MD002": false,
+  "MD041": false,
+  "MD042": false,
+  "MD013": false
 }
diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@ offering free resources to [FIWARE](https://www.fiware.org) developers.
 
 Documentation is tagged according to FIWARE Lab release plan.
 
-## Contributions
+## Contributions
 
 Contributions to the documentation are welcome in the form of pull requests.
 

diff --git a/docs/1.essentials/1.introduction.md b/docs/1.essentials/1.introduction.md
@@ -0,0 +1,7 @@
+# Essential things to know before joining FIWARE Lab 
+
+As a new node of the FIWARE Lab federation, you will increase the capacity of our
+current facilities and provide the FIWARE services to the users. In the same way,
+the FIWARE Lab node will take the benefits of the knowledge that the FIWARE community
+has acquired in the management of this environment. In this guide, you can
+find the main steps to join the FIWARE Lab federation. 
diff --git a/docs/1.essentials/2.requirements.md b/docs/1.essentials/2.requirements.md
@@ -0,0 +1,42 @@
+## Requirements
+
+The hardware requirements are associated with the number of end-users
+(community users) that can be maintained in the node. The minimum number
+of those customers have to be 20. Based on this, the hardware and
+networks requirements are specified in the following sections.
+
+### Hardware Requirements
+
+The hardware requirements are associated with the number of end-users
+(community users) is the following:
+
+-   Up to 10 vCores per end-user.
+
+-   Up to 20 Gb RAM per end-user.
+
+-   Up to 150 Gb Hard Drive per end-user.
+
+-   At least 22 Gb for images management.
+
+### Network Requirements
+
+The connectivity capacity will be used for two aims: connect to the
+backbone of the FIWARE Lab to support node management operations, and
+provide connectivity to deployed services for end-users. You have also
+to provide a pool of public IPs that can be used during the OpenStack
+deployment (in order to expose the public API) and at a later time by
+the FIWARE Lab end-users.
+
+Networking requirements:
+
+-   1 Gbps connectivity for the backbone;
+
+-   100 Mbps Internet connectivity for end-users;
+
+-   Firewall to ensure security;
+
+-   At least 1 public IPv4 available for each end-user (20 public IPs
+    for 20 community users) plus public IPs for the different
+    OpenStack services.
+
+-   IPv6 support is desirable although not required.
diff --git a/docs/1.essentials/3.steps_join.md b/docs/1.essentials/3.steps_join.md
@@ -0,0 +1,40 @@
+## Steps to become a New FIWARE Lab node
+
+In order to actually become a new FIWARE Lab node, several activities
+are required from both the Node and FIWARE Lab admins. The first is the
+signature of a Letter of Intent in order to communicate to the node
+these steps, the SLA levels that they have to fulfil and the FIWARE Lab
+user data ownership and legislation to be applied in terms of Data
+Protection. Additionally, it is explained that the non-fulfilment of the
+SLA will produce a disconnection of the node from the FIWARE Lab. The
+Annex D: Letter of intent to become a new FIWARE Lab node contains the
+template of this Letter of Intent.
+
+The table below describes, step by step, the whole procedure as it is at
+the time of writing this document.
+
+Some steps may change in the near future due to the R6.4 of FIWARE
+Keyrock that includes the migration from Keyrock to Keystone and the
+Federation of OpenStack Keystone instances, therefore in short time all
+the nodes can use their own OpenStack Keystone instance and create users
+on the FIWARE Lab node.
+
+| **TASK** | **TASK DESCRIPTION** | **TASK OWNER** |
+| --- | --- | --- |
+| 00 | Sign the Letter to become a FIWARE Lab | Node Admin |
+| 01 | Provide contacts information. | Node Admin |
+| 02 | Insert the new node within the agenda of the weekly meetings. | FIWARE Lab Admins
+| 03 | Join the weekly meetings. | Node Admin |
+| 04 | Join the <fiware-lab-federation-nodes@lists.fiware.org> mail list. | Node Admin + FIWARE Lab Admins |
+| 05 | Insert the new node in Jira for help-desk, sprint and FLUA management. | FIWARE Lab Admins |
+| 06 | Sign in for Jira account: <https://jira.fiware.org> | Node Admin |
+| 07 | Sign in for a FIWARE Lab account: <https://cloud.lab.fiware.org> | Node Admin
+| 08 | Webinar to explain how to use the main tools and methodology, such as Jira, Sprints, Help tickets, FLUAs. | Node Admin + FIWARE Lab Admins |
+| 09 | Create sprint activities | FIWARE Lab Admins |
+| 10 | Install the local OpenStack node | Node Admin |
+| 11 | Federate the node | Node Admin |
+| 12 | Update the federation data within the corresponding workitem created for the federation process | Node Admin |
+| 13 | Install and configure the monitoring system | Node Admin + FIWARE Lab Admins |
+| 14 | Configure the Sanity Check | Node Admins + FIWARE Lab Admins |
+| 15 | Insert the new node within Infographic, Health Status and Sanity Check | Node Admins + FIWARE Lab Admins |
+| 16 | Synchronize GE image list | FIWARE Lab Admins |
diff --git a/docs/1.essentials/4.steps_leave.md b/docs/1.essentials/4.steps_leave.md
@@ -0,0 +1,27 @@
+## Steps to discontinue a FIWARE Lab node
+
+In order to discontinue the operation of a running FIWARE Lab node there
+are several activities and obligations to be respected. The most
+important, which is the base of the FIWARE philosophy, is taking care of
+the migration of users toward a persistent node, in order to
+avoid service outage.
+
+The table below describes all steps, as they are now at the time of
+writing this document.
+
+Some steps may change in the near future due to the R6.4 of FIWARE
+Keyrock that includes the migration from Keyrock to Keystone and the
+Federation of OpenStack Keystone instances, therefore in short time all
+the nodes can use their own OpenStack Keystone instance and create use
+on the FIWARE Lab node.
+
+| **TASK** | **TASK DESCRIPTION** | **TASK OWNER** |
+| --- | --- | --- |
+| 01 | Inform the FIWARE Lab management about your decision at least 1 month before the shutdown | Node Admin |
+| 02 | Inform all FIWARE Lab users about the shutdown via the FIWARE Lab notification tool | FIWARE Lab Admins |
+| 03 | Take care of the migration of all active users toward a persistent node | Node Admin + FIWARE Lab Admins |
+| 04 | Disconnect the node from centralized Keystone | Node Admin + FIWARE Lab Admins |
+| 05 | Delete the node from the list of available nodes in JIRA, FLUA, Sanity Check, Infographic, Health Status | FIWARE Lab Admins |
+| 06 | Delete from the [*fiware-lab-federation-nodes@lists.fiware.org*](mailto:fiware-lab-federation-nodes@lists.fiware.org) mail list | FIWARE Lab Admins |
+| 07 | Delete the node from the weekly meeting agenda/minute | FIWARE Lab Admins |
+| 08 | Ask the node to send a final report/lessons learnt | FIWARE Lab Admins + Node Admin|
diff --git a/docs/1.essentials/5.steps_status.md b/docs/1.essentials/5.steps_status.md
@@ -0,0 +1,63 @@
+## Steps to show the current status of your FIWARE Lab node
+
+The table below represents the template used to check the current status
+of a node.
+
+| []()|[]() |
+| --- | --- | 
+| **OpenStack Version** | []() |
+| **Monitoring Version** | []() |
+| **Infographic Status** | []() |
+| **Health Check Status** | []() |
+| **Federation Status** | []() |
+
+In order to retrieve all those information it is necessary to perform the
+following operation:
+
+- HOW TO CHECK THE NODE NAME
+
+    ```
+    $ ssh login into one controller node
+    $ grep region_name /etc/nova/nova.conf
+    ```
+
+- HOW TO CHECK THE OPENSTACK VERSION
+
+    ```
+    $ ssh login into one controller node
+    $ nova-api --version
+    (e.g. 2015.1.1)
+    ```
+
+    Take note of 2015.1.1 and go to
+    [*https://wiki.openstack.org/wiki/Release\_Naming*](https://wiki.openstack.org/wiki/Release_Naming)
+    to see the corresponding OpenStack release (in this example Kilo).
+
+- HOW TO CHECK THE MONITORING VERSION
+
+    ```
+    $ ssh login into one controller node
+    $ search the fiware-check-monitoring.sh script
+    $ run fiware-check-monitoring.sh -v
+    ```
+
+    Check the text “FIWARE Lab Monitoring System release xxxx”
+
+- HOW TO CHECK THE INFOGRAPHIC STATUS
+
+    Go to [*http://infographic.lab.fiware.org*](http://infographic.lab.fiware.org)
+
+    Check the status of the node
+
+- HOW TO CHECK THE HEALTH CHECK STATUS
+
+    Go to [*https://fi-health.lab.fiware.org*](https://fi-health.lab.fiware.org)
+    and check the Sanity Check status.
+
+    Go to [*http://status.lab.fiware.org*](http://status.lab.fiware.org)
+    and check the historical performance of the node and available resources.
+
+- HOW TO CHECK THE FEDERATION STATUS
+
+    Go to [*http://backlog.fiware.org/lab/backlog*](http://backlog.fiware.org/lab/backlog)
+    and check the closing date of the corresponding workitem.
diff --git a/docs/faq.md b/docs/faq.md
diff --git a/docs/future.md b/docs/future.md
diff --git a/docs/index.md b/docs/index.md
@@ -5,20 +5,8 @@ and connect it to the FIWARE Lab.
 
 ## Table of Contents
 
-1. [Introduction](introduction.md)
-1. [Setting-up a node](node-set-up)
-    1. [Requirements](node-set-up/requirements.md)
-    1. [Installation](node-set-up/installation.md)
-1. [Connecting a node](node-connection)
-    1. [Connecting your node to FIWARE Lab](node-connection/fiware-lab.md)
-    1. [Registering your node in FI-Health](node-connection/fi-health.md)
-    1. [Registering your node in the Infographic](node-connection/infographic.md)
-1. [Disconnecting a node](node-disconnection)
-    1. [Disconnecting your node to FIWARE Lab](node-disconnection/fiware-lab.md)
-    1. [Deregistering your node in FI-Health](node-disconnection/fi-health.md)
-    1. [Deregistering your node in the Infographic](node-disconnection/infographic.md)
-1. [Operating a node](node-operation)
-1. [Planned future evolutions](future.md)
-1. [Additional documentation](references.md)
-1. [F.A.Q.](faq.md)
-1. [ToDos](todos.md)
+1. [Essential things to know before joining FIWARE Lab](1.essentials/1.introduction.md)
+    - [Requirements](1.essentials/2.requirements.md)
+    - [Steps to become a New FIWARE Lab node](1.essentials/3.steps_join.md)
+    - [Steps to discontinue a FIWARE Lab node](1.essentials/4.steps_leave.md)
+    - [Steps to show the current status of your FIWARE Lab node](1.essentials/5.steps_status.md)
diff --git a/docs/introduction.md b/docs/introduction.md
diff --git a/docs/node-connection/fi-health.md b/docs/node-connection/fi-health.md
diff --git a/docs/node-connection/fiware-lab.md b/docs/node-connection/fiware-lab.md
diff --git a/docs/node-connection/infographic.md b/docs/node-connection/infographic.md
diff --git a/docs/node-disconnection/fi-health.md b/docs/node-disconnection/fi-health.md
diff --git a/docs/node-disconnection/fiware-lab.md b/docs/node-disconnection/fiware-lab.md
diff --git a/docs/node-disconnection/infographic.md b/docs/node-disconnection/infographic.md
diff --git a/docs/node-operation/index.md b/docs/node-operation/index.md
diff --git a/docs/node-set-up/installation.md b/docs/node-set-up/installation.md
diff --git a/docs/node-set-up/requirements.md b/docs/node-set-up/requirements.md
diff --git a/docs/references.md b/docs/references.md
diff --git a/docs/todos.md b/docs/todos.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -6,23 +6,12 @@ docs_dir: 'docs'
 theme: readthedocs
 pages:
     - Home: 'index.md'
-    - Introduction: 'introduction.md'
-    - Setting-up a node:
-        - 'Requirements': 'node-set-up/requirements.md'
-        - 'Installation': 'node-set-up/installation.md'
-    - Connecting a node:
-        - 'Connecting your Node to FIWARE Lab': 'node-connection/fiware-lab.md'
-        - 'Registering your Node in FI-Health': 'node-connection/fi-health.md'
-        - 'Registering your Node in the Infographic': 'node-connection/infographic.md'
-    - Disconnecting a node:
-        - 'De-Registering your Node to FIWARE Lab': 'node-disconnection/fiware-lab.md'
-        - 'De-Registering your Node in FI-Health': 'node-disconnection/fi-health.md'
-        - 'De-Registering your Node in the Infographic': 'node-disconnection/infographic.md'
-    - 'Operating a node': 'node-operation/index.md'
-    - 'Planned future evolutions': 'future.md'
-    - 'Additional Documentation': 'references.md'
-    - 'F.A.Q.': 'faq.md'
-    - 'ToDos': 'todos.md'
+    - 'Essential things to know before joining FIWARE Lab':
+      - 'Introduction': '1.essentials/1.introduction.md'
+      - 'Requirements': '1.essentials/2.requirements.md'
+      - 'Steps to become a New FIWARE Lab node': '1.essentials/3.steps_join.md'
+      - 'Steps to discontinue a FIWARE Lab node': '1.essentials/4.steps_leave.md'
+      - 'Steps to show the current status of your FIWARE Lab node': '1.essentials/5.steps_status.md'
 
 markdown_extensions: [toc,fenced_code]
 extra_css: ["https://fiware.org/style/fiware_readthedocs.css"]