Merge "refactor and wordsmithed devel guide"
diff --git a/SUMMARY.md b/SUMMARY.md
index 39f399a..dce2483 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -51,10 +51,11 @@
* [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/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" %}