Moving files away from the root in appropriate directories
Change-Id: I33d09337338a11bfd794cc472b7bb9650f9c5d83
diff --git a/README.md b/README.md
index 89d8d76..4a05cbd 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,16 @@
# Installation Guide
-This guide describes how to install CORD on a physical POD. It identifies a set of [prerequisites](prereqs/README.md), and then walks through the steps involved in bringing up the [Platform](platform.md). Once the Platform is installed, you are ready to bring up one of the available Profiles:
+This guide describes how to install CORD on a physical POD. It identifies a set of [prerequisites](prereqs/README.md), and then walks through the steps involved in bringing up the [Platform](installation/platform.md). Once the Platform is installed, you are ready to bring up one of the available Profiles:
* [SEBA](./profiles/seba/install.md)
* [M-CORD](./profiles/mcord/install.md)
-Alternatively if you just want to quickly bring up SEBA, try the [SEBA Quick Start](./seba_quickstart.md).
+Alternatively if you just want to quickly bring up SEBA, try the [SEBA Quick Start](quickstart/seba_quickstart.md).
-This installation procedure requires management-network connectivity to the Internet. If your installation does not have such connectivity, or you are behind a restrictive firewall, consider [Offline Install](./offline-install.md).
+This installation procedure requires management-network connectivity to the Internet. If your installation does not have such connectivity, or you are behind a restrictive firewall, consider [Offline Install](installation/offline-install.md).
If you do not have the [prerequisite hardware](./prereqs/hardware.md) needed for a POD, consider running a complete system entirely emulated in software using [SEBA-in-a-Box](./profiles/seba/siab-overview.md).
-If you prefer a gentle walkthrough of the process of bringing up a subset of the CORD platform running on your laptop (e.g., to get an introduction to all the moving parts in CORD) then jumping to the [ExampleService Quick Start](example_service_quickstart.md) page is also an option.
+If you prefer a gentle walkthrough of the process of bringing up a subset of the CORD platform running on your laptop (e.g., to get an introduction to all the moving parts in CORD) then jumping to the [ExampleService Quick Start](quickstart/example_service_quickstart.md) page is also an option.
Finally, if you want to get a broader lay-of-the-land, you might step back and read the [Overview](overview.md).
diff --git a/SUMMARY.md b/SUMMARY.md
index 405ecb3..956a495 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -2,11 +2,11 @@
* [Overview](overview.md)
* [Navigating CORD](navigate.md)
-* [Quick Start](quickstart.md)
- * [SEBA Quick Start](seba_quickstart.md)
- * [ExampleService Quick Start](example_service_quickstart.md)
- * [MacOS](macos.md)
- * [Linux](linux.md)
+* [Quick Start](quickstart/quickstart.md)
+ * [SEBA Quick Start](quickstart/seba_quickstart.md)
+ * [ExampleService Quick Start](quickstart/example_service_quickstart.md)
+ * [MacOS](quickstart/macos.md)
+ * [Linux](quickstart/linux.md)
## Guides
@@ -19,11 +19,10 @@
* [Single Node](prereqs/k8s-single-node.md)
* [Multi-Node](prereqs/k8s-multi-node.md)
* [Helm](prereqs/helm.md)
- * [Fabric Software Setup](fabric-setup.md)
- * [Install Platform](platform.md)
- * [Install Profile](profiles.md)
- * [Offline Install](offline-install.md)
- * [Attach Container to a NIC](operating_cord/veth_intf.md)
+ * [Fabric Software Setup](installation/fabric-setup.md)
+ * [Install Platform](installation/platform.md)
+ * [Install Profile](installation/profiles.md)
+ * [Offline Install](installation/offline-install.md)
* [Operations Guide](operating_cord/operating_cord.md)
* [General Info](operating_cord/general.md)
* [GUI](operating_cord/gui.md)
@@ -50,7 +49,7 @@
* [Data Sources](xos-gui/architecture/data-sources.md)
* [Tests](xos-gui/developer/tests.md)
* [Unit Tests](xos/dev/unittest.md)
- * [Versions and Releases](versioning.md)
+ * [Versions and Releases](developer/versioning.md)
* [Testing Guide](cord-tester/README.md)
* [Test Setup](cord-tester/qa_testsetup.md)
* [Test Environment](cord-tester/qa_testenv.md)
@@ -66,6 +65,7 @@
* [Install AT&T workflow](profiles/seba/workflows/att-install.md)
* [EdgeCore OLT Setup (OpenOLT driver)](openolt/README.md)
* [BETA: Celestica / Microsemi Setup](profiles/seba/celestica-olt-setup.md)
+ * [Attach Container to a NIC](profiles/seba/veth_intf.md)
* [SEBA-in-a-Box Overview](profiles/seba/siab-overview.md)
* [SEBA-in-a-Box](profiles/seba/siab.md)
* [SEBA-in-a-Box with Fabric Switch](profiles/seba/siab-with-fabric-switch.md)
diff --git a/book.json b/book.json
index 47ff947..2f0702d 100644
--- a/book.json
+++ b/book.json
@@ -2,7 +2,8 @@
"title": "CORD Guide",
"root": ".",
"structure": {
- "summary": "SUMMARY.md"
+ "summary": "SUMMARY.md",
+ "glossary": "terminology.md"
},
"styles": {
"website": "styles/website.css"
diff --git a/versioning.md b/developer/versioning.md
similarity index 100%
rename from versioning.md
rename to developer/versioning.md
diff --git a/developer/workflows.md b/developer/workflows.md
index 99b39f1..ba1fb7a 100644
--- a/developer/workflows.md
+++ b/developer/workflows.md
@@ -35,7 +35,7 @@
[these instructions](../profiles/seba/install.md). Alternatively, if
you are working on a new profile or a new service that is not part of
any existing profile, you can install just the
-[CORD Platform](../platform.md).
+[CORD Platform](../installation/platform.md).
## Making and Deploying Changes
@@ -94,6 +94,6 @@
The way we recommend doing this is via a private docker registry.
You can find more information about what a docker registry is in the
-[offline installation section](../offline-install.md).
+[offline installation section](../installation/offline-install.md).
{% include "/partials/push-images-to-registry.md" %}
diff --git a/fabric-setup.md b/installation/fabric-setup.md
similarity index 98%
rename from fabric-setup.md
rename to installation/fabric-setup.md
index 7c480b8..72a2a88 100644
--- a/fabric-setup.md
+++ b/installation/fabric-setup.md
@@ -7,7 +7,7 @@
## Supported Switches
-The list of supported hardware can be found in the [hardware requirements page](prereqs/hardware.md).
+The list of supported hardware can be found in the [hardware requirements page](../prereqs/hardware.md).
## Operating System
diff --git a/offline-install.md b/installation/offline-install.md
similarity index 100%
rename from offline-install.md
rename to installation/offline-install.md
diff --git a/platform.md b/installation/platform.md
similarity index 87%
rename from platform.md
rename to installation/platform.md
index a417b25..d8666fc 100644
--- a/platform.md
+++ b/installation/platform.md
@@ -5,7 +5,7 @@
## CORD Platform as a Whole
-{% include "partials/helm/add-cord-repo.md" %}
+{% include "../partials/helm/add-cord-repo.md" %}
Then, to install the CORD Platform you can use the corresponding chart:
@@ -36,13 +36,13 @@
Alternatively, you may want to install the individual components separately.
The following are the individual components included in the *cord-platform* chart:
-- [ONOS](./charts/onos.md#onos-manages-fabric--voltha)
-- [XOS](./charts/xos-core.md)
-- [Kafka](./charts/kafka.md)
+- [ONOS](../charts/onos.md#onos-manages-fabric--voltha)
+- [XOS](../charts/xos-core.md)
+- [Kafka](../charts/kafka.md)
Optionally, you may also want to install logging and monitoring infrastructure components:
-- [Logging-Monitoring](./charts/logging-monitoring.md)
+- [Logging-Monitoring](../charts/logging-monitoring.md)
## Verify your installation and next steps
diff --git a/profiles.md b/installation/profiles.md
similarity index 65%
rename from profiles.md
rename to installation/profiles.md
index 16e47a9..79fe05f 100644
--- a/profiles.md
+++ b/installation/profiles.md
@@ -1,4 +1,4 @@
# Install Profile
Once the [platform](platform.md) is installed, you are ready to bring up one
-of the available [profiles](profiles/intro.md).
+of the available [profiles](../profiles/intro.md).
diff --git a/prereqs/helm.md b/prereqs/helm.md
index c75080f..8c6269d 100644
--- a/prereqs/helm.md
+++ b/prereqs/helm.md
@@ -43,5 +43,5 @@
Once you are done, you are ready to deploy CORD components using their
helm charts! Start by brining up the
-[CORD Platform](../platform.md). For more detailed information, see
+[CORD Platform](../installation/platform.md). For more detailed information, see
the [Helm Reference](../charts/helm.md).
diff --git a/profiles/rcord/celestica-olt-setup.md b/profiles/rcord/celestica-olt-setup.md
index cab0435..37b3c18 100644
--- a/profiles/rcord/celestica-olt-setup.md
+++ b/profiles/rcord/celestica-olt-setup.md
@@ -63,6 +63,6 @@
Of course, also the OLT NNI port needs to be connected as well to the same fabric switch.
If both the OLT and the server running Voltha are connected to the same fabric switch, a path needs to be provisioned between the two. This can be achieved -for example- in the CORD fabric using Trellis, through the configuration of a VLAN cross-connect or a pseudo-wire.
-Further more, the Voltha vcore container (called voltha in the Kubernetes based deployment) should be connected to the data plane port, connected to the OLT, which is a quite trivial but manual operation. The steps to connect containers and server ports can be found in the [veth interface configuration guide](../../operating_cord/veth_intf.md).
+Further more, the Voltha vcore container (called voltha in the Kubernetes based deployment) should be connected to the data plane port, connected to the OLT, which is a quite trivial but manual operation. The steps to connect containers and server ports can be found in the [veth interface configuration guide](../../profiles/seba/veth_intf.md).
> **NOTE:** the Celestica OLT is known to work *only* with the top-down R-CORD configuration workflow.
diff --git a/profiles/seba/celestica-olt-setup.md b/profiles/seba/celestica-olt-setup.md
index cab0435..37b3c18 100644
--- a/profiles/seba/celestica-olt-setup.md
+++ b/profiles/seba/celestica-olt-setup.md
@@ -63,6 +63,6 @@
Of course, also the OLT NNI port needs to be connected as well to the same fabric switch.
If both the OLT and the server running Voltha are connected to the same fabric switch, a path needs to be provisioned between the two. This can be achieved -for example- in the CORD fabric using Trellis, through the configuration of a VLAN cross-connect or a pseudo-wire.
-Further more, the Voltha vcore container (called voltha in the Kubernetes based deployment) should be connected to the data plane port, connected to the OLT, which is a quite trivial but manual operation. The steps to connect containers and server ports can be found in the [veth interface configuration guide](../../operating_cord/veth_intf.md).
+Further more, the Voltha vcore container (called voltha in the Kubernetes based deployment) should be connected to the data plane port, connected to the OLT, which is a quite trivial but manual operation. The steps to connect containers and server ports can be found in the [veth interface configuration guide](../../profiles/seba/veth_intf.md).
> **NOTE:** the Celestica OLT is known to work *only* with the top-down R-CORD configuration workflow.
diff --git a/profiles/seba/install.md b/profiles/seba/install.md
index 9a6573c..8b18206 100644
--- a/profiles/seba/install.md
+++ b/profiles/seba/install.md
@@ -6,7 +6,7 @@
## Installing SEBA
-In order to run SEBA you need to have the [CORD Platform](../../platform.md) installed.
+In order to run SEBA you need to have the [CORD Platform](../../installation/platform.md) installed.
Specifically, wait for the three EtcdCluster CustomResourceDefinitions to
appear in Kubernetes:
diff --git a/profiles/seba/operate/k8s-helm-ops.md b/profiles/seba/operate/k8s-helm-ops.md
index 0df4056..61d778d 100644
--- a/profiles/seba/operate/k8s-helm-ops.md
+++ b/profiles/seba/operate/k8s-helm-ops.md
@@ -102,7 +102,7 @@
```
For more informations on how to create a webserver containing the ONOS Apps
-and deploy it on the POD you can look at the [Offline Install](../../../offline-install.md#install-a-local-web-server-using-helm-optional)
+and deploy it on the POD you can look at the [Offline Install](../../../installation/offline-install.md#install-a-local-web-server-using-helm-optional)
#### Change ONOS apps at runtime
diff --git a/profiles/seba/siab-with-fabric-switch.md b/profiles/seba/siab-with-fabric-switch.md
index c90ca24..9305456 100644
--- a/profiles/seba/siab-with-fabric-switch.md
+++ b/profiles/seba/siab-with-fabric-switch.md
@@ -10,7 +10,7 @@
1. Perform all install procedures described in the [SEBA-in-a-Box installation instructions](siab.md) except sections **Install Mininet** and **Load TOSCA into NEM**.
-1. Fabric switch bringup. To bring up the fabric switch, follow the procedure [here](../../fabric-setup.md) and verify the fabric switch is discovered by onos (`ssh -p 30115 onos@K8S_NODE_IP devices`).
+1. Fabric switch bringup. To bring up the fabric switch, follow the procedure [here](../../installation/fabric-setup.md) and verify the fabric switch is discovered by onos (`ssh -p 30115 onos@K8S_NODE_IP devices`).
1. Enable EAPOL on linux-bridge `pon0` and add the physical interface on the k8node, running PONSIM-OLT to `pon1` bridge.
diff --git a/operating_cord/veth_intf.md b/profiles/seba/veth_intf.md
similarity index 100%
rename from operating_cord/veth_intf.md
rename to profiles/seba/veth_intf.md
diff --git a/quickstart.md b/quickstart.md
deleted file mode 100644
index 61d2b07..0000000
--- a/quickstart.md
+++ /dev/null
@@ -1,9 +0,0 @@
-# Quick Start
-
-If you prefer to understand the installation process in more depth, including the full range of deployment options, you should start with the [Installation Guide](README.md) instead.
-
-There are two Quick Starts available.
-
-* If you've met the hardware prerequisites and quickly want to get SEBA installed, use the [SEBA Quick Start](./seba_quickstart.md). If you don't have the hardware, try [SEBA-in-a-Box](./profiles/seba/siab-overview.md).
-
-* The other quick start helps you quickly understand the internal workings of the CORD platform - for example, how xproto, TOSCA and Helm all interact for a [simple example service](./example_service_quickstart.md).
diff --git a/example_service_quickstart.md b/quickstart/example_service_quickstart.md
similarity index 61%
rename from example_service_quickstart.md
rename to quickstart/example_service_quickstart.md
index 51f6376..c272937 100644
--- a/example_service_quickstart.md
+++ b/quickstart/example_service_quickstart.md
@@ -1,8 +1,8 @@
# ExampleService Quick Start
-This section walks you through an example installation sequence on two different Unix-based platforms. This is just a surface introduction to CORD. If you prefer to understand the installation process in more depth, including the full range of deployment options, you should start with the [Installation Guide](README.md) instead.
+This section walks you through an example installation sequence on two different Unix-based platforms. This is just a surface introduction to CORD. If you prefer to understand the installation process in more depth, including the full range of deployment options, you should start with the [Installation Guide](../README.md) instead.
-This Quick Start describes how to install a subset of the CORD platform, plus a `SimpleExampleService`, on a single machine. Once you complete these steps, you might be interested in jumping ahead to the [SimpleExampleService Tutorial](simpleexampleservice/simple-example-service.md) to learn more about the make-up of a CORD service. Another option would be to explore CORD's [operational interfaces](operating_cord/general.md).
+This Quick Start describes how to install a subset of the CORD platform, plus a `SimpleExampleService`, on a single machine. Once you complete these steps, you might be interested in jumping ahead to the [SimpleExampleService Tutorial](../simpleexampleservice/simple-example-service.md) to learn more about the make-up of a CORD service. Another option would be to explore CORD's [operational interfaces](../operating_cord/general.md).
* [MacOS](macos.md)
* [Linux](linux.md)
diff --git a/linux.md b/quickstart/linux.md
similarity index 95%
rename from linux.md
rename to quickstart/linux.md
index 0c03bd9..3898dce 100644
--- a/linux.md
+++ b/quickstart/linux.md
@@ -219,6 +219,6 @@
This completes our example walk-through. At this point, you can do one
of the following:
-* Explore other [installation options](README.md).
-* Take a tour of the [operational interfaces](operating_cord/general.md).
-* Drill down on the internals of [SimpleExampleService](simpleexampleservice/simple-example-service.md).
+* Explore other [installation options](../README.md).
+* Take a tour of the [operational interfaces](../operating_cord/general.md).
+* Drill down on the internals of [SimpleExampleService](../simpleexampleservice/simple-example-service.md).
diff --git a/macos.md b/quickstart/macos.md
similarity index 97%
rename from macos.md
rename to quickstart/macos.md
index bed88df..d72bfef 100644
--- a/macos.md
+++ b/quickstart/macos.md
@@ -212,7 +212,7 @@
## Next Steps
-* Explore other [installation options](README.md).
-* Take a tour of the [operational interfaces](operating_cord/general.md).
+* Explore other [installation options](../README.md).
+* Take a tour of the [operational interfaces](../operating_cord/general.md).
* Learn more about using [XOS](https://guide.xosproject.org).
* Drill down on the internals of [SimpleExampleService](https://guide.xosproject.org/simpleexampleservice/simple-example-service.html).
diff --git a/quickstart/quickstart.md b/quickstart/quickstart.md
new file mode 100644
index 0000000..d2a7453
--- /dev/null
+++ b/quickstart/quickstart.md
@@ -0,0 +1,9 @@
+# Quick Start
+
+If you prefer to understand the installation process in more depth, including the full range of deployment options, you should start with the [Installation Guide](../README.md) instead.
+
+There are two Quick Starts available.
+
+* If you've met the hardware prerequisites and quickly want to get SEBA installed, use the [SEBA Quick Start](seba_quickstart.md). If you don't have the hardware, try [SEBA-in-a-Box](../profiles/seba/siab-overview.md).
+
+* The other quick start helps you quickly understand the internal workings of the CORD platform - for example, how xproto, TOSCA and Helm all interact for a [simple example service](example_service_quickstart.md).
diff --git a/seba_quickstart.md b/quickstart/seba_quickstart.md
similarity index 92%
rename from seba_quickstart.md
rename to quickstart/seba_quickstart.md
index 3f955f5..10a9cc7 100644
--- a/seba_quickstart.md
+++ b/quickstart/seba_quickstart.md
@@ -2,7 +2,7 @@
This section provides instructions to quickly bring up SEBA.
->**Note:** This Quick start assumes that [prerequisite](prereqs/README.md) hardware and software (up to Kubernetes and Helm) have already been installed.
+>**Note:** This Quick start assumes that [prerequisite](../prereqs/README.md) hardware and software (up to Kubernetes and Helm) have already been installed.
## Install components as a whole
@@ -79,4 +79,4 @@
>**Note:** The tosca-loader pods may periodically transition into *error* state. This is expected. They will retry and eventually get to the desired state.
>**Note:** Depending on the profile you're installing, you may need to check also different namespaces (for example, check the voltha namespace if you're installing SEBA with `kubectl get pods -n voltha`)
-Your POD is now installed and ready for use. To learn how to operate your POD continue to the [SEBA configuration section](./profiles/seba/configuration.md).
+Your POD is now installed and ready for use. To learn how to operate your POD continue to the [SEBA configuration section](../profiles/seba/configuration.md).
diff --git a/terminology.md b/terminology.md
index 73074cd..19bf523 100644
--- a/terminology.md
+++ b/terminology.md
@@ -1,28 +1,35 @@
-# Terminology
+# GLOSSARY
-This guide uses the following terminology.
+## CORD POD
-**CORD POD**: A single physical deployment of CORD.
+A single physical deployment of CORD.
-**Development (Dev) machine**: This is the machine used to download, build and deploy CORD onto a POD.
+## Development (Dev) machine
+
+This is the machine used to download, build and deploy CORD onto a POD.
Sometimes it is a dedicated server, and sometimes the developer's laptop. In
principle, it can be any machine that satisfies the hardware and software
requirements.
-**Development (Dev) VM**: Bootstrapping the CORD installation requires a lot of software to be installed and some non-trivial configurations to be applied. All this should happen on the dev machine. To help users with the process, CORD provides an easy way to create a VM on the dev machine with all the required software and configurations in place.
+## Development (Dev) VM
-**Compute Node(s)**
-: A server in a POD that run VMs or containers associated with one or more
- tenant services. This terminology is borrowed from OpenStack.
+Bootstrapping the CORD installation requires a lot of software to be installed and some non-trivial configurations to be applied. All this should happen on the dev machine. To help users with the process, CORD provides an easy way to create a VM on the dev machine with all the required software and configurations in place.
-**Head Node**
-: A compute node of the POD that also runs management services. This includes
- for example XOS (the orchestrator), two instances of ONOS (the SDN controller,
- one to control the underlay fabric and one to control the overlay), MAAS and
- all the services needed to automatically install and configure the rest of
- the POD devices.
+## Compute Node(s)
-**Fabric Switch**
-: A switch in a POD that interconnects other switches and servers inside the
- POD.
+A server in a POD that run VMs or containers associated with one or more
+tenant services. This terminology is borrowed from OpenStack.
+
+## Head Node
+
+A compute node of the POD that also runs management services. This includes
+for example XOS (the orchestrator), two instances of ONOS (the SDN controller,
+one to control the underlay fabric and one to control the overlay), MAAS and
+all the services needed to automatically install and configure the rest of
+the POD devices.
+
+## Fabric Switch
+
+A switch in a POD that interconnects other switches and servers inside the
+POD.