Merge "Refactor voltha helm chart docs"
diff --git a/charts/onos.md b/charts/onos.md
index ad5f788..4b13e72 100644
--- a/charts/onos.md
+++ b/charts/onos.md
@@ -1,55 +1,50 @@
-# ONOS Helm chart
+# Deploy ONOS
-This chart can be used to deploy an ONOS container.
-Traditionally it is used to deploy three different ONOSes in the system,
-depending by what is required.
+The same chart can be used to deploy different flavors of ONOS, depending on the configuration applied (configurations available in the configs folder).
-## ONOS-Fabric
+* **onos-fabric**: a specific version of ONOS used to control the Trellis fabric
+* **onos-voltha**: a specific version of ONOS used to control VOLTHA
+* **onos-vtn**: a speciic version of ONOS used to control VTN
+* **no configuration applied**: if no configurations are applied, a generic ONOS instance will be installed
-`helm install -n onos-fabric -f configs/onos-fabric.yaml onos`
+## onos-fabric
-Ports exposed:
+```shell
+helm install -n onos-fabric -f configs/onos-fabric.yaml onos
+```
-- ovsdb: 31640
-- OpenFlow: 31653
-- SSH: 31101
-- UI: 31181
+**Nodeports exposed**
-## ONOS-VOLHTA
+* ovsdb: 31640
+* OpenFlow: 31653
+* SSH: 31101
+* REST/UI: 31181
+
+## onos-voltha
> NOTE: This requires [VOLTHA](voltha.md) to be installed
-`helm install -n onos-voltha -f configs/onos-voltha.yaml onos`
-
-Ports exposed:
-
-- SSH: 30115
-- UI: 30120
-
-## ONOS-VTN
-
-`helm install -n onos-cord -f configs/onos-cord.yaml onos`
-
-## Overridable values
-
-This is a sample `values.yaml` that can be used to override values
-through the `-f` option:
-
-```yaml
-imagePullPolicy: Always
-onosImage: 'onosproject/onos:1.13.1'
-
-services:
- openflowServiceType: NodePort
- ovsdbServiceType: NodePort
- sshServiceType: NodePort
- uiServiceType: NodePort
- ovsdb:
- nodePort: 31640
- openflow:
- nodePort: 31653
- ssh:
- nodePort: 31101
- ui:
- nodePort: 31181
+```shell
+helm install -n onos-voltha -f configs/onos-voltha.yaml onos
```
+
+**Nodeports exposed**
+
+* SSH: 30115
+* REST/UI: 30120
+
+## onos-vtn
+
+```shell
+helm install -n onos-cord -f configs/onos-cord.yaml onos
+```
+
+The configuration doesn't expose any nodeport.
+
+## Generic ONOS
+
+```shell
+helm install -n onos onos
+```
+
+The configuration doesn't expose any nodeport.
diff --git a/mdl_relaxed.rb b/mdl_relaxed.rb
index 9448317..92e3fe8 100644
--- a/mdl_relaxed.rb
+++ b/mdl_relaxed.rb
@@ -46,3 +46,5 @@
# Exclude rule: Fenced code blocks should be surrounded by blank lines
exclude_rule 'MD031'
+# Exclude rule: Emphasis used instead of a header
+exclude_rule 'MD036'
diff --git a/prereqs/kubernetes.md b/prereqs/kubernetes.md
index d9d8666..05c680e 100644
--- a/prereqs/kubernetes.md
+++ b/prereqs/kubernetes.md
@@ -2,29 +2,42 @@
A generic CORD installation can run on any version of Kubernetes (>=1.9) and Helm.
-Internet is full of different releases of Kubernetes, as of resources that can help to get you going.
-If on one side it may sound confusing, the good news is that you’re not alone!
+Internet is full of different releases of Kubernetes, as of resources that can help to get you going. If on one side it may sound confusing, the good news is that you’re not alone!
-Pointing you to a specific version of Kubernetes wouldn’t probably make much sense, since each Kubernetes version may be specific to different deployment needs.
-Anyway, we think it’s good to point you to some well known releases, that can be used for different types of deployments.
+Pointing you to a specific version of Kubernetes wouldn’t probably make much sense, since each Kubernetes version may be specific to different deployment needs. Anyway, we think it’s good to point you to some well known releases, that can be used for different types of deployments.
+
+**New to Kubernetes?** Tutorials are a good place to start. More at <https://kubernetes.io/docs/tutorials/>.
Following paragraphs provide guidelines, pointers and automated scripts to let you quickly install both Kubernetes and Helm.
-Whatever version of Kubernetes you’ve installed, a client tool called “kubectl” is usually needed to interact with your Kubernetes installation. To install kubectl on your development machine, follow this guide: <https://kubernetes.io/docs/tasks/tools/install-kubectl/>.
+## Step by step installation
-Once Kubernetes is installed, you should have a KubeConfig configuration file containing all details of your deployment (address of the machine(s), credentials, ...). The file can be used to access your Kubernetes deployment from either Kubectl or Helm. Here is how:
+### Install Kubernetes
+First, choose what version of Kubernetes you'd like to run. In the following sections of the guide we offer pointers and scripts to get your favorite version of Kubernetes installed. Start from there. Then, come back here and continue over the next paragraphs, below.
+
+### Get your KUBECONFIG file
+
+Once Kubernetes is installed, you should have a KUBECONFIG configuration file containing all the details of your deployment (address of the machine(s), credentials, ...). The file can be used to access your Kubernetes deployment from any client able to communicate with the Kubernetes installation. To manage the pod, export a KUBECONFIG variable containing the path to the configuration file:
+
+```shell
export KUBECONFIG=/path/to/your/kubeconfig/file
+```
-You can also permanently export this environment variable, so you don’t have to export it each time you open a new window in your terminal. More info on this topic can be found here: <https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/>.
+You can also permanently export this environment variable, so you don’t have to export it every time you open a new window in your terminal. More info on this topic at <https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/>.
-To test if the installation and the configuration steps were successful, type:
+### Install kubectl
+
+You've installed Kubernetes. Now it's time to install the CLI tools to interact with it. *kubectl* is the basic tool you need. It can be installed on any device able to reach the Kubernetes just installed (i.e. the development laptop, another server, the same machine where Kubernetes is installed). To install kubectl, follow this guide: <https://kubernetes.io/docs/tasks/tools/install-kubectl/>.
+
+To test the kubectl installation run:
```shell
kubectl get pods
```
-Kubernetes should reply to your request, and don’t output any error.
+Kubernetes should reply to the request showing the pods already deployed. If you've just installed Kubernetes, likely you won't see any pod, yet. That's fine, as long as you don't see errors.
-More on Kubernetes and Kubectl commands can be found on the official Kubernetes website, <https://kubernetes.io/docs/tutorials/>.
+### Install helm
+CORD uses a tool called helm to deploy containers on Kubernetes. As such, helm needs to be installed before being able to deploy CORD containers. More info on helm and how to install it can be found [here](helm.md).