Merge "Adding top-down provisioning to the R-CORD guide"
diff --git a/SUMMARY.md b/SUMMARY.md
index 3437415..dce2483 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -41,19 +41,21 @@
* [Fabric](fabric/README.md)
* [vRouter](vrouter/README.md)
* [Modeling Guide](xos/README.md)
- * [XOS Support for Models](xos/dev/xproto.md)
+ * [XOS Modeling Framework](xos/dev/xproto.md)
* [Core Models](xos/core_models.md)
* [Security Policies](xos/security_policies.md)
* [Writing Synchronizers](xos/dev/synchronizers.md)
* [Design Guidelines](xos/dev/sync_arch.md)
* [Implementation Details](xos/dev/sync_impl.md)
+ * [Synchronizer Reference](xos/dev/sync_reference.md)
* [Development Guide](developer/developer.md)
* [Getting the Source Code](developer/getting_the_code.md)
* [Developer Workflows](developer/workflows.md)
- * [Building Docker Images](developer/imagebuilder.md)
- * [Kubernetes Service](kubernetes-service/kubernetes-service.md)
- * [OpenStack Service](openstack/openstack-service.md)
- * [VTN and Service Composition](xos/xos_vtn.md)
+ * [Building Docker Images](developer/imagebuilder.md)
+ * [Platform Services](developer/platform.md)
+ * [Kubernetes](kubernetes-service/kubernetes-service.md)
+ * [OpenStack](openstack/openstack-service.md)
+ * [VTN and Service Composition](xos/xos_vtn.md)
* [GUI Development](xos-gui/developer/README.md)
* [Quickstart](xos-gui/developer/quickstart.md)
* [Service Graph](xos-gui/developer/service_graph.md)
diff --git a/charts/helm.md b/charts/helm.md
index 5592cc7..542b0a1 100644
--- a/charts/helm.md
+++ b/charts/helm.md
@@ -1,4 +1,4 @@
-# Helm Reference Guide
+# Helm Reference
For information on how to install `helm` please refer to [Installing helm](../prereqs/helm.md)
@@ -8,9 +8,57 @@
## CORD Helm Charts
+All helm charts used to install CORD can be found in the `helm-chart`
+repository. Most of the top-level directories in that repository
+(e.g., `onos`, `voltha`, `xos-core`) correspond to components of
+CORD that can be installed independently. For example, it is possible
+to bring up `onos` without `voltha`, and vice versa. You can also
+bring up XOS by itself (`xos-core`) or XOS with its GUI (`xos-core`
+and `xos-gui`). This can be useful if you want to work on just the
+CORD data models, without any backend components.
+
+The `xos-services` and `xos-profile` directories contain helm
+charts for individual services and profiles (a mesh of services),
+respectively. While it is possible to use Helm to bring up an
+individual service, typically collections of related services are
+installed as a unit; we call this unit a *profile.* Looking in the
+`xos-profiles` directory, `rcord-lite` is an example profile. It
+corresponds to R-CORD, and inspecting its `requirements.yaml`
+file shows that it, in turn, depends on the `volt` and `vrouter`
+services, among several others.
+
+Some of the profiles bring up sub-systems that other profiles then
+build upon. For example, `base-openstack` brings up three platform
+related services (`onos-service`, `openstack`, and `vtn-service`),
+which effectively provisions CORD to support OpenStack-based VNFs.
+Once the services in the `base-openstack` profile are running, it
+is then possible to bring up the `mcord` profile, which corresponds
+to ~10 other services. It is also possible to bring up an individual
+service by executing its helm chart; for example
+`xos-services/exampleservice`.
+
+Similarly, the `base-kubernetes` profile brings up Kubernetes in
+support of container-based VNFs. This corresponds to the
+`kubernetes-service`, not to be confused with CORD's use of
+Kubernetes to deploy the CORD control plane. Once this profile is
+running, it is possible to bring up an example VNF in a container
+by executing its helm chart; for example
+`xos-services/simpleexampleservice`.
+
+> **Note:** The `base-kubernetes` configuration does not yet
+> incorporate VTN. Doing so is work-in-progress.
+
+Finally, note that the `templates` sub-directory in both the
+`xos-services` and `xos-profiles` directories includes one or
+more TOSCA-related files. These play a role in configuring the
+service graph and provisioning the individual services contained
+in that service graph. This happens once the helm charts have
+done their job, and is technically a post-install operation, as
+discussed in the [Operations Guide](../operating_cord/operating_cord.md).
+
### Download the helm-charts Repository
-You can get the CORD helm-chars by cloning the `helm-charts` repository:
+You can get the CORD helm charts by cloning the `helm-charts` repository:
```shell
git clone https://gerrit.opencord.org/helm-charts
diff --git a/developer/developer.md b/developer/developer.md
index d66f3cb..fef811f 100644
--- a/developer/developer.md
+++ b/developer/developer.md
@@ -1 +1,11 @@
-# Development Guide
\ No newline at end of file
+# Development Guide
+
+This guide describes workflows and best practices for developers. If
+you are a service developer, you will need to consult this guide and
+the companion [Modeling Guide](../xos/README.md) that describes how
+define models and synchronizers for services being onboarded into
+CORD. If you are a platform developer, you will find information about
+the platform services typically integrated into CORD (e.g.,
+Kubernetes, OpenStack, VTN). Service developers may be interested in
+what's under the covers, but they should not need to understand these
+internals to develop individual services.
diff --git a/developer/getting_the_code.md b/developer/getting_the_code.md
index 4c3d308..4c0ddaa 100644
--- a/developer/getting_the_code.md
+++ b/developer/getting_the_code.md
@@ -2,14 +2,13 @@
## Install repo
-[repo](https://code.google.com/archive/p/git-repo/) is a tool from Google that
-works with Gerrit and allows us to manage the multiple git repos that make up
-the CORD code base.
+We use the [repo](https://code.google.com/archive/p/git-repo/) tool
+from Google, which works with Gerrit, to manage the multiple git repos
+that make up the CORD code base.
-If you don't already have `repo` installed, this may be possible with your
-system package manager, or using the [instructions on the android source
-site](https://source.android.com/source/downloading#installing-repo), or by
-using the following commands which download/verify/install it:
+If you don't already have `repo` installed, you may be able to install
+it with your system package manager, or you can follow these
+[instructions from the android source site](https://source.android.com/source/downloading#installing-repo):
```sh
curl -o /tmp/repo 'https://gerrit.opencord.org/gitweb?p=repo.git;a=blob_plain;f=repo;hb=refs/heads/stable'
@@ -18,20 +17,20 @@
sudo chmod a+x /usr/local/bin/repo
```
-> NOTE: As mentioned above, you may want to install *repo* using the official
+> **Note:** As mentioned above, you may want to install *repo* using the official
> repository instead. We forked the original repository and host a copy of the
> file to make repo downloadable also by organizations that don't have access
> to Google servers.
-## Download CORD repositories
+## Download CORD Repositories
The `cord` repositories are usually checked out to `~/cord` in most of our
examples and deployments:
{% include "/partials/repo-download.md" %}
-> NOTE: `-b` specifies the branch name. Development work goes on in `master`,
-> and there are also specific stable branches such as `cord-4.0` that can be
+> **Note:** `-b` specifies the branch name. Development work goes on in `master`,
+> and there are also specific stable branches such as `cord-6.0` that can be
> used.
When this is complete, a listing (`ls`) inside this directory should yield
@@ -43,7 +42,7 @@
build docs incubator orchestration test
```
-## Download patchsets
+## Download Patchsets
Once you've downloaded a CORD source tree, you can download patchsets from
Gerrit with the following command:
@@ -52,10 +51,9 @@
repo download orchestration/xos 1234/3
```
-Which downloads a patch for the `xos` git repo, patchset number `1234` and
-version `3`.
+which downloads patchset number `1234` and version `3` for the `xos` git repo.
-## Contributing code to CORD
+## Contributing Code to CORD
We use [Gerrit](https://gerrit.opencord.org) to manage the CORD code base. For
more information see [Working with
@@ -65,14 +63,14 @@
project, see [Contributing to
CORD](https://wiki.opencord.org/display/CORD/Contributing+to+CORD).
-## Downloading testing and QA repositories
+## Testing and QA Repositories
-Whie not useful for deploying a CORD POD, the repo manifest files and the
-infrastructure code used to configure our test and QA systems, including
-Jenkins jobs created with [Jenkins Job
+While not part of the standard process for deploying a CORD POD, the
+repo manifest files and the infrastructure code used to configure our
+test and QA systems, including Jenkins jobs created with [Jenkins Job
Builder](https://docs.openstack.org/infra/jenkins-job-builder/) can be
-downloaded with repo. The `ci-management` repo uses git submodules, so those
-need to be checked out as well:
+also be downloaded with repo. The `ci-management` repo uses git
+submodules, so those need to be checked out as well:
```shell
mkdir cordqa
diff --git a/developer/imagebuilder.md b/developer/imagebuilder.md
index 06693dd..c59a821 100644
--- a/developer/imagebuilder.md
+++ b/developer/imagebuilder.md
@@ -2,18 +2,18 @@
The current CORD implementation consists of many interrelated Docker images.
Making sure that the images used in a deployment are consistent with the source
-tree on disk is a challenge and required a tool, `imagebuilder`, to be
+tree on disk is a challenge and required a tool, called `imagebuilder`, to be
developed to perform image rebuilds in a consistent and efficient manner.
Imagebuilder is currently used to build the XOS, ONOS, and the `mavenrepo`
(source of ONOS Apps used in CORD) images, and pull down other required images.
-While imagebuilder will pull down required images from DockerHub and build/tag
+While `imagebuilder` will pull down required images from DockerHub and build/tag
images, it does not push those images or delete obsolete ones. These tasks are
-left to other software (Ansible, Jenkins) which should take in imagebuilder's
-YAML output and take the appropriate actions.
+left to other software (Ansible, Jenkins) which should take in
+YAML output from `imagebuilder` and take the appropriate actions.
-## Obtaining and rebuilding images
+## Obtaining and Rebuilding Images
For the normal build process, you won't need to manually download images as the
`docker-images` make target that runs imagebuilder will automatically be run as
@@ -22,11 +22,11 @@
If you do need to rebuild images, there is a `make clean-images` target that
will force imagebuilder to be run again and images to be moved into place.
-## Adding a new Docker image to CORD
+## Adding a new Docker Image to CORD
There are several cases where an Image would need to be added to CORD.
-### Adding an image developed outside of CORD
+### Adding an Image Developed Outside of CORD
There are cases where a 3rd party image developed outside of CORD may be
needed. This is the case with ONOS, Redis, and a few other pieces of software
@@ -41,7 +41,7 @@
These images will be retagged with a `candidate` tag after being pulled.
-### Adding a synchronizer image
+### Adding a Synchronizer Image
Adding a synchronizer image is usually as simple as adding it to the
`buildable_images` list in the `automation-tools/developer/docker_images.yml`
@@ -52,7 +52,7 @@
list it in `build/docker_images.yml`, so it can build the synchronizer image
locally.
-### Adding other CORD images
+### Adding Other CORD images
If you want imagebuilder to build an image from a Dockerfile somewhere in the
CORD source tree, you need to add it to the `buildable_images` list in the
@@ -65,7 +65,7 @@
## Debugging imagebuilder
-If you get a different error or think that imagebuilder isn't working
+If you get a different error or think that `imagebuilder` isn't working
correctly, please rerun it with the `-vv` ("very verbose") option, read through
the output carefully, and then post about the issue on the mailing list or
Slack.
@@ -82,9 +82,9 @@
Run `imagebuilder.py -h` for a list of other supported arguments.
-## How Imagebuilder works
+## How Imagebuilder Works
-The imagebuilder program performs the following steps when run:
+The `imagebuilder` program performs the following steps when run:
1. Reads the [repo manifest file](https://github.com/opencord/manifest/blob/master/default.xml)
(checked out as `.repo/manifest`) to get a list of the CORD git repositories.
@@ -130,7 +130,7 @@
repos of parent images to determine whether an image is correctly built from
the checked out source tree.
-## Image labels
+## Image Labels
Imagebuilder uses a Docker label scheme to determine whether an image needs to
be rebuilt, which is added to the image when it is built. Docker images used
@@ -209,7 +209,7 @@
Labels on a built image can be seen by running `docker inspect <image name or id>`
-## Automating image builds
+## Automating Image Builds
There is a [Jenkinsfile.imagebuilder](https://github.com/opencord/cord/blob/{{
book.branch }}/Jenkinsfile.imagebuilder) that can be run in a Jenkins
diff --git a/developer/platform.md b/developer/platform.md
new file mode 100644
index 0000000..677f4ac
--- /dev/null
+++ b/developer/platform.md
@@ -0,0 +1,8 @@
+# Platform Services
+
+In CORD, everything is a service, including the "platform" that provides
+the substrate on top of which other services run. This includes infrastructure
+services like Kubernetes and OpenStack, SDN controllers like ONOS, and
+overlay services like VTN. This section includes information about how these
+platform-level services are integrated into CORD, and the role they plan in
+supporting other services.
diff --git a/developer/workflows.md b/developer/workflows.md
index 9a8a99e..3480ee8 100644
--- a/developer/workflows.md
+++ b/developer/workflows.md
@@ -1,32 +1,30 @@
# Developer Workflows
-This document is intended to describe the workflow to develop the control plane
-of CORD.
+This section describes a typical workflow for developing the CORD
+control plane. This workflow does not include any data plane
+elements (e.g., the underlying switching fabric or access devices).
-## Setting up a local development environment
+## Setting Up a Local Development Environment
-The first thing you’ll need to work on the control plane of CORD, known as XOS,
-is to setup a local Kubernetes environment.
-The suggested way to achieve that is to use Minikube on your laptop,
-and this guide assume that it will be the environment going forward.
-
-You can follow this guide to get started with Minikube:
+It is straightforward to set up a local Kubernetes environment on your laptop.
+The recommended way to do this is to use Minikube. This guide assumes
+you have done that. See the
+[Single-Node](../prereqs/k8s-single-node.md) case in the
+Installation Guide for more information, or you can go directly
+to the documentation for Minikube:
<https://kubernetes.io/docs/getting-started-guides/minikube/#installation>
-> Note: If you are going to do development on Minikube you may want to increase
-> it’s memory from the default 512MB, you can do that using this command to
+> **Note:** If you are going to do development on Minikube you may want to increase
+> its memory from the default 512MB. You can do this using this command to
> start Minikube: `minikube start --cpus 2 --memory 4096`
-Once Minikube is up and running on your laptop you can proceed with
-the following steps to bring XOS up.
+In addition to Minikube running on your laptop, you will also need to
+install Helm: <https://docs.helm.sh/using_helm/#installing-helm>.
-Once Minikube is installed you’ll need to install Helm:
-<https://docs.helm.sh/using_helm/#installing-helm>
-
-At this point you should be able to deploy the core components of XOS
-and the services required by R-CORD from images published on dockerhub.
-
-> NOTE: You can replace the `xos-profile` with the one you need to work on.
+Once both Helm and Minikube are installed, you can deploy the
+core components of XOS, along with the services that make
+up, for example, the R-CORD profile. This uses images published
+on DockerHub:
```shell
cd ~/cord/build/helm-charts
@@ -35,30 +33,31 @@
helm install xos-profiles/rcord-lite -n rcord-lite
```
-### Deply a single instance of kafka
+> **Note:** You can replace the `rcord-lite` profile with the one you want to work on.
-Some profiles require a `kafka` message bus to properly working.
+### Deploy a Single Instance of Kafka
+
+Some profiles require a `kafka` message bus to work properly.
If you need to deploy it for development purposes, a single instance
-deployment will be enough.
-
-You can install it by using:
+deployment will be enough. You can do so as follows:
```shell
helm repo add incubator http://storage.googleapis.com/kubernetes-charts-incubator
install --name cord-kafka incubator/kafka -f examples/kafka-single.yaml
```
-## Making changes and deploy them
+## Making and Deploying Changes
-You can follow this guide to [get the CORD source code](getting_the_code.md).
+Assuming you have
+[downloaded the CORD source code](getting_the_code.md) and the entire
+source tree for CORD is under `~/cord`, you can edit and re-deploy the
+code as follows.
-We assume that now you have the entire CORD tree under `~/cord`
-
-> Note: to develop a single synchronizer you may not need the full CORD source,
+> **Note:** To develop a single synchronizer you may not need the full CORD source,
> but this assume that you have a good knowledge of the system and you know
> what you’re doing.
-As first you’ll need to point Docker to the one provided by Minikube
+First you will need to point Docker to the one provided by Minikube
(_note that you don’t need to have docker installed,
as it comes with the Minikube installation_).
@@ -66,21 +65,21 @@
eval $(minikube docker-env)
```
-Then you’ll need to build the XOS containers from source:
+You will then need to build the containers from source:
```shell
cd ~/cord/automation-tools/developer
python imagebuilder.py -f ../../helm-charts/examples/filter-images.yaml -x
```
-At this point the images containing your changes will be available
+At this point, the images containing your changes will be available
in the Docker environment used by Minikube.
-> Note: in some cases you can rebuild a single docker image to make the process
+> **Note:** In some cases you can rebuild a single docker image to make the process
> faster, but this assume that you have a good knowledge of the system and you
> know what you’re doing.
-All that is left is to teardown and redeploy the containers.
+All that is left is to teardown and re-deploy the containers.
```shell
helm del --purge xos-core
@@ -90,20 +89,22 @@
helm install xos-profiles/rcord-lite -n rcord-lite -f examples/image-tag-candidate.yaml -f examples/imagePullPolicy-IfNotPresent.yaml
```
-In some cases is possible to use the helm upgrade command,
-but if you made changes to the models we suggest to redeploy everything
+In some cases it is possible to use the `helm` upgrade command,
+but if you made changes to the XOS models we suggest you redeploy
+everything.
-> Note: if your changes are only in the synchronizer steps, after rebuilding
+> **Note:** if your changes are only in the synchronizer steps, after rebuilding
> the containers, you can just delete the corresponding POD and kubernetes will
-> restart it with the new image
+> restart it with the new image.
-## Pushing changes to a remote registry
+## Pushing Changes to a Remote Registry
-If you have a remote POD you want to test your changes on, you need to push your
-docker images on a registry that can be accessed from the POD itself.
+If you have a remote POD that you want to test your changes on, you
+need to push your docker images to a registry that can be accessed
+from the POD.
-The way we suggest to do this is via a private docker-registry,
-you can find more informations about what a
+The way we recommend doing this is via a private docker-registry.
+You can find more informations about what a
docker-registry is [here](../prereqs/docker-registry.md).
{% include "/partials/push-images-to-registry.md" %}
diff --git a/prereqs/k8s-single-node.md b/prereqs/k8s-single-node.md
index b9b4cc2..ad08a06 100644
--- a/prereqs/k8s-single-node.md
+++ b/prereqs/k8s-single-node.md
@@ -5,26 +5,17 @@
There are two popular single-node versions of Kubernetes.
-* **Minikube**
+* **Minikube** (recommended)
* Documentation: <https://kubernetes.io/docs/getting-started-guides/minikube/>
+ * Installation on a Linux machine (either physical or a VM on your laptop or in the cloud): <https://github.com/kubernetes/minikube#linux-continuous-integration-without-vm-support (Must have Docker installed <https://docs.docker.com/install/>)
+ * Installation directly on your Windows or MacOS System: <https://kubernetes.io/docs/getting-started-guides/minikube/#installation>
* Minimum requirements:
* One machine, either a physical machine or a VM. It could also be your own PC! It installs natively also on macOS.
* **Mikrok8s**
* Documentation: <https://microk8s.io/>
* One machine, Linux based, either physical machine or virtual. It could also be your own PC!
-We recommend Minikube, which is easy to set up and use. The following
-comments on two considerations:
-
-* If you want to install Minikube on a Linux machine (either a
- physical machine or a VM on your laptop or in the cloud), you will
- need to follow the instructions at <https://github.com/kubernetes/minikube#linux-continuous-integration-without-vm-support>.
-
-* If you want to run Minikube directly on your Windows or MacOS
- system, you will need to follow the instructions at
- <https://kubernetes.io/docs/getting-started-guides/minikube/#installation>.
-
## Done?
-Once you are done, you are ready to install Kubctl and Helm, so return to
+Once you are done, you are ready to install Kubctl and Helm, so return to
[here](kubernetes.md#get-your-kubeconfig-file) in the installation guide.
diff --git a/prereqs/kubernetes.md b/prereqs/kubernetes.md
index c259de9..7a3e3d0 100644
--- a/prereqs/kubernetes.md
+++ b/prereqs/kubernetes.md
@@ -10,7 +10,7 @@
## Install Kubernetes
-The following sections offer pointers and scripts to install your favorite
+The following sections, [Single Node Cluster](k8s-single-node.md) and [Multi Node Cluster](k8s-multi-node.md), offer pointers and scripts to install your favorite
version of Kubernetes. Start there, then come back here and follow the
steps in the following three subsections.
diff --git a/prereqs/networking.md b/prereqs/networking.md
index e72f549..01c032b 100644
--- a/prereqs/networking.md
+++ b/prereqs/networking.md
@@ -23,7 +23,7 @@
## Dataplane Network
The dataplane network carries the users' traffic, connecting subscribers to the
-Intetnet (which is the whole purpose of CORD). The following is a diagram of a
+Internet (which is the whole purpose of CORD). The following is a diagram of a
reference dataplane network for CORD.
diff --git a/prereqs/openstack-helm.md b/prereqs/openstack-helm.md
index 5c80bb8..1d9f651 100644
--- a/prereqs/openstack-helm.md
+++ b/prereqs/openstack-helm.md
@@ -119,6 +119,18 @@
export OSH_EXTRA_HELM_ARGS_NEUTRON="-f /tmp/neutron-cord.yaml"
```
+It is also necessary to make a small change to `openstack-helm`'s
+[openvswitch](https://github.com/openstack/openstack-helm/tree/master/openvswitch) chart: the `/usr/sbin/ovsdb-server` must be executed with
+the `--remote=ptcp:6641` option to listen for the connection from VTN.
+After the `openstack-helm` repository is checked out during the
+[install process](#install-process-for-openstack-helm),
+run the following command:
+
+```bash
+cd openstack-helm/openvswitch/templates/bin
+sed -i 's/--remote=db:Open_vSwitch,Open_vSwitch,manager_options/--remote=db:Open_vSwitch,Open_vSwitch,manager_options --remote=ptcp:6641/' _openvswitch-db-server.sh.tpl
+```
+
## Install Process for openstack-helm
Please see the `openstack-helm` documentation for instructions on how to
diff --git a/profiles/mcord/install.md b/profiles/mcord/install.md
index 6a93a23..89bbb76 100644
--- a/profiles/mcord/install.md
+++ b/profiles/mcord/install.md
@@ -1,5 +1,22 @@
# M-CORD
+## Quick Start
+
+A convenience script is provided that will install M-CORD on a single
+node, suitable for evaluation or testing. Requirements:
+
+- An Ubuntu 16.04 node with at least 64GB of RAM and 32 virtual CPUs
+- User invoking the script has passwordless `sudo` capability
+- Hostname is resolvable in DNS, e.g., `dig +short $( hostname )` returns an IP address
+
+```bash
+git clone https://gerrit.opencord.org/automation-tools
+automation-tools/mcord/mcord-in-a-box.sh
+```
+
+This script takes about an hour to complete. If you run it, you can skip
+directly to [Validating the Installation](#validating-the-installation) below.
+
## Prerequisites
M-CORD requires OpenStack to run VNFs. The OpenStack installation
diff --git a/profiles/rcord/install.md b/profiles/rcord/install.md
index cd3a9f3..0231ae1 100644
--- a/profiles/rcord/install.md
+++ b/profiles/rcord/install.md
@@ -24,7 +24,7 @@
## Install the RCORD-Lite Helm Chart
```shell
-helm dep update xos-profile/rcord-lite
+helm dep update xos-profiles/rcord-lite
helm install -n rcord-lite xos-profiles/rcord-lite
```