Merge "Troubleshooting page for failing pings."
diff --git a/SUMMARY.md b/SUMMARY.md
index 6c31ff3..99f6b55 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -110,7 +110,6 @@
* [Base OpenStack](charts/base-openstack.md)
* [OpenStack](prereqs/openstack-helm.md)
* [VTN Setup](prereqs/vtn-setup.md)
- * [R-CORD](charts/rcord.md)
* [M-CORD](charts/mcord.md)
* [XOSSH](charts/xossh.md)
* [Logging and Monitoring](charts/logging-monitoring.md)
@@ -119,4 +118,3 @@
* [PONNET](charts/ponnet.md)
* [PONSIM v2](charts/ponsimv2.md)
* [PONSIM Pod](charts/ponsim-pod.md)
-
diff --git a/charts/base-kubernetes.md b/charts/base-kubernetes.md
index efe12f9..b1baf59 100644
--- a/charts/base-kubernetes.md
+++ b/charts/base-kubernetes.md
@@ -2,9 +2,10 @@
This chart contains all the XOS services that interacts with Kubernetes.
-You can install it using:
+{% include "../partials/helm/add-cord-repo.md" %}
-```bash
-helm dep update xos-profiles/base-kubernetes
-helm install -n base-kubernetes xos-profiles/base-kubernetes/
-```
\ No newline at end of file
+You can then install it using:
+
+```shell
+helm install -n base-kubernetes cord/base-kubernetes
+```
diff --git a/charts/base-openstack.md b/charts/base-openstack.md
index b48eb96..b8e4d27 100644
--- a/charts/base-openstack.md
+++ b/charts/base-openstack.md
@@ -14,13 +14,12 @@
## Single-Node Configuration
-Here is an example of deploying the `xos-profiles/base-openstack` chart
-on a single-node OpenStack server set up by the
-`automation-tools/openstack-helm/openstack-helm-dev-setup.sh` script:
+Here is an example of deploying the *base-openstack* chart on a single-node OpenStack server set up by the *automation-tools/openstack-helm/openstack-helm-dev-setup.sh* script:
-```bash
-helm dep update xos-profiles/base-openstack
-helm install -n base-openstack xos-profiles/base-openstack \
+{% include "../partials/helm/add-cord-repo.md" %}
+
+```shell
+helm install -n base-openstack cord/base-openstack \
--set computeNodes.master.name=`hostname` \
--set vtn-service.sshUser=`whoami`
```
diff --git a/charts/bbsim.md b/charts/bbsim.md
index 74b75fa..07c6c69 100644
--- a/charts/bbsim.md
+++ b/charts/bbsim.md
@@ -1,10 +1,13 @@
# BBSim Helm Chart
This chart let you install the broadband simulator.
-Note that this chart depends on [kafka](kafka.md)
+
+>**Note:** this chart depends on [kafka](kafka.md).
+
+{% include "../partials/helm/add-cord-repo.md" %}
```shell
-helm install -n bbsim bbsim
+helm install -n bbsim cord/bbsim
```
## Set a different number of ONUs
@@ -12,7 +15,7 @@
You can configure the number of ONUs through a parameter in the installation:
```shell
-helm install -n bbsim bbsim --set onus_per_pon_port={number_of_onus}
+helm install -n bbsim cord/bbsim --set onus_per_pon_port={number_of_onus}
```
## Set a different mode
@@ -23,14 +26,14 @@
You can change the behaviour via:
```shell
-helm install -n bbsim bbsim --set emulation_mode="{both|aaa|default}"
+helm install -n bbsim cord/bbsim --set emulation_mode="{both|aaa|default}"
```
Where:
-- `both` stands for authentication and DHCP
-- `aaa` stands for authentication only
-- `default` will just activate the devices
+- *both* stands for authentication and DHCP
+- *aaa* stands for authentication only
+- *default* will just activate the devices
## Start BBSim without Kafka
@@ -41,7 +44,7 @@
with:
```shell
-helm install -n bbsim bbsim --set kafka_broker=""
+helm install -n bbsim cord/bbsim --set kafka_broker=""
```
## Provision the BBSim OLT in NEM
diff --git a/charts/kafka.md b/charts/kafka.md
index 26d4645..30d43ea 100644
--- a/charts/kafka.md
+++ b/charts/kafka.md
@@ -1,14 +1,14 @@
# Kafka Helm chart
-The `kafka` helm chart is not maintained by CORD,
-but it is available online at: <https://github.com/kubernetes/charts/tree/master/incubator/kafka>
+The *kafka* helm chart is not maintained by CORD, but it is available online at: <https://github.com/kubernetes/charts/tree/master/incubator/kafka>
-To install kafka using the `cord-kafka` name, run the following commands:
+To install kafka using the *cord-kafka* name, run the following commands:
```shell
helm repo add incubator http://storage.googleapis.com/kubernetes-charts-incubator
helm install -f examples/kafka-single.yaml --version 0.8.8 -n cord-kafka incubator/kafka
```
+
> NOTE: Historically there were two kafka busses deployed (another one named
> `voltha-kafka`) but these have been consolidated.
@@ -35,22 +35,24 @@
A few examples:
- List available topics:
- ```shell
- kafkacat -b cord-kafka -L
- ```
+
+```shell
+kafkacat -b cord-kafka -L
+```
- Listen for events on a particular topic:
- ```shell
- kafkacat -b cord-kafka -C -t <kafka-topic>
- ```
+
+```shell
+kafkacat -b cord-kafka -C -t <kafka-topic>
+```
- Some example topics to listen on:
- ```shell
- kafkacat -b cord-kafka -C -t xos.log.core
- kafkacat -b cord-kafka -C -t xos.gui_events
- kafkacat -b cord-kafka -C -t voltha.events
- kafkacat -b cord-kafka -C -t onu.events
- kafkacat -b cord-kafka -C -t authentication.events
- kafkacat -b cord-kafka -C -t dhcp.events
- ```
+```shell
+kafkacat -b cord-kafka -C -t xos.log.core
+kafkacat -b cord-kafka -C -t xos.gui_events
+kafkacat -b cord-kafka -C -t voltha.events
+kafkacat -b cord-kafka -C -t onu.events
+kafkacat -b cord-kafka -C -t authentication.events
+kafkacat -b cord-kafka -C -t dhcp.events
+```
diff --git a/charts/logging-monitoring.md b/charts/logging-monitoring.md
index 01dcfcb..a051500 100644
--- a/charts/logging-monitoring.md
+++ b/charts/logging-monitoring.md
@@ -7,12 +7,14 @@
functionality, `nem-monitoring` and `logging`. Both of these charts depend on
having [kafka](kafka.md) instances running in order to pass messages.
+## Add the cord repository
-## `nem-monitoring` charts
+{% include "../partials/helm/add-cord-repo.md" %}
+
+## nem-monitoring charts
```shell
-helm dep update nem-monitoring
-helm install -n nem-monitoring nem-monitoring
+helm install -n nem-monitoring cord/nem-monitoring
```
> NOTE: In order to display `voltha` kpis you need to have `voltha`
@@ -22,18 +24,17 @@
This chart exposes two dashboards:
-- [Grafana](http://docs.grafana.org/) on port `31300`
-- [Prometheus](https://prometheus.io/docs/) on port `31301`
+- [Grafana](http://docs.grafana.org/) on port *31300*
+- [Prometheus](https://prometheus.io/docs/) on port *31301*
-## `logging` charts
+## logging charts
```shell
-helm dep up logging
-helm install -n logging logging
+helm install -n logging cord/logging
```
For smaller developer/test environments without persistent storage, please use
-the `examples/logging-single.yaml` file to run the logging chart, which doesn't
+the *examples/logging-single.yaml* file to run the logging chart, which doesn't
create PVC's.
### Logging Dashboard
diff --git a/charts/mcord.md b/charts/mcord.md
index b7e6730..cec9fa6 100644
--- a/charts/mcord.md
+++ b/charts/mcord.md
@@ -1,12 +1,12 @@
# Deploy M-CORD Profile
-To deploy the M-CORD profile, run the following:
+{% include "../partials/helm/add-cord-repo.md" %}
+
+Then, to deploy the M-CORD profile, run the following:
```shell
-helm dep update xos-profiles/mcord
-helm install -n mcord xos-profiles/mcord --set proxySshUser=ubuntu
+helm install -n mcord cord/mcord --set proxySshUser=ubuntu
```
-The value of `proxySshUser` should be set to the user account corresponding
-to the public key added to the node when
-[prepping the nodes for VTN](../prereqs/vtn-setup.md).
+The value of *proxySshUser* should be set to the user account corresponding
+to the public key added to the node when [prepping the nodes for VTN](../prereqs/vtn-setup.md).
diff --git a/charts/onos.md b/charts/onos.md
index a398039..7d7c27c 100644
--- a/charts/onos.md
+++ b/charts/onos.md
@@ -1,9 +1,11 @@
-# Deploy ONOS
+# ONOS
-To install ONOS run:
+{% include "../partials/helm/add-cord-repo.md" %}
+
+Then, to install ONOS run:
```shell
-helm install -n onos
+helm install -n cord/onos
```
**Nodeports exposed**
@@ -26,7 +28,7 @@
## ONOS logging
-### `onos-log-agent` Sidecar container
+### onos-log-agent sidecar container
By default, the onos helm chart will run a sidecar container to ship logs using
[Filebeat](https://www.elastic.co/guide/en/beats/filebeat/current/index.html)
@@ -38,11 +40,15 @@
specify which container you want to interact with. For example, to view the
ONOS logs via kubectl, you would use:
- kubectl logs onos-7bbc9555bf-2754p -c onos
+```shell
+kubectl logs onos-7bbc9555bf-2754p -c onos
+```
and to view the filebeat logs:
- kubectl logs onos-7bbc9555bf-2754p -c onos-log-agent
+```shell
+kubectl logs onos-7bbc9555bf-2754p -c onos-log-agent
+```
If this the sidecar isn't required, it can be disabled when installing the
chart by passing `--set log_agent.enabled=false` or by using a values file.
@@ -63,4 +69,4 @@
```shell
helm install -n onos -f configs/onos-debug.yaml onos
-```
\ No newline at end of file
+```
diff --git a/charts/ponnet.md b/charts/ponnet.md
index 1c2831e..b40f402 100644
--- a/charts/ponnet.md
+++ b/charts/ponnet.md
@@ -6,13 +6,12 @@
RG and components upstream of the PONSIM OLT. Note that the bridges
are not actually created until [PONSIM](ponsimv2.md) is installed.
-You can install the chart using:
+{% include "../partials/helm/add-cord-repo.md" %}
+
+You can then install the chart using:
```bash
-helm install -n ponnet ponnet
+helm install -n ponnet cord/ponnet
```
-The chart modifies the underlying Kubernetes setup by installing the `bridge`
-CNI and adding configuration files to create the two bridges. Kubernetes must
-be configured with CNI enabled. Note that this chart does not seem to work
-on `minikube`.
+The chart modifies the underlying Kubernetes setup by installing the *bridge* CNI and adding configuration files to create the two bridges. Kubernetes must be configured with CNI enabled. Note that this chart does not seem to work on *minikube*.
diff --git a/charts/ponsim-pod.md b/charts/ponsim-pod.md
index b84fea3..a8329f8 100644
--- a/charts/ponsim-pod.md
+++ b/charts/ponsim-pod.md
@@ -1,10 +1,11 @@
# PONSIM Pod
-This chart just loads TOSCA for adding a PONSIM OLT and Mininet
-AGG Switch to XOS. It is used by [SiaB](../profiles/seba/siab.md).
+This chart just loads TOSCA for adding a PONSIM OLT and Mininet AGG Switch to XOS. It is used by [SiaB](../profiles/seba/siab.md).
-You can install it using:
+{% include "../partials/helm/add-cord-repo.md" %}
-```bash
-helm install -n ponsim-pod xos-profiles/ponsim-pod/
+You can then install it using:
+
+```shell
+helm install -n ponsim-pod cord/ponsim-pod
```
diff --git a/charts/ponsimv2.md b/charts/ponsimv2.md
index a50c74d..599740e 100644
--- a/charts/ponsimv2.md
+++ b/charts/ponsimv2.md
@@ -1,16 +1,18 @@
# PONSIM v2 Helm Chart
-The `ponsimv2` chart deploys the PON Simulator (PONSIM) containers
-(a virtual OLT, ONU, and RG) in the context of VOLTHA.
+The `ponsimv2` chart deploys the PON Simulator (PONSIM) containers (a virtual OLT, ONU, and RG) in the context of VOLTHA.
This chart is used by [SiaB](../profiles/seba/siab.md).
-More details about PONSIM can be found in
-[its README](https://github.com/opencord/voltha/blob/master/ponsim/v2/README.md).
+More details about PONSIM can be found in [its README](https://github.com/opencord/voltha/blob/master/ponsim/v2/README.md).
You must install the [PONNET](ponnet.md) chart before installing this one.
-At that point you can install PONSIM using:
+At that point you can install PONSIM.
-```bash
-helm install -n ponsimv2 ponsimv2
+{% include "../partials/helm/add-cord-repo.md" %}
+
+Then, install ponsim doing:
+
+```shell
+helm install -n ponsimv2 cord/ponsimv2
```
After a successful install you will see containers like these running in the
diff --git a/charts/rcord.md b/charts/rcord.md
deleted file mode 100644
index 789d8a7..0000000
--- a/charts/rcord.md
+++ /dev/null
@@ -1,2 +0,0 @@
-# R-CORD
-
diff --git a/charts/seba-services.md b/charts/seba-services.md
index 3145bdc..a28dc97 100644
--- a/charts/seba-services.md
+++ b/charts/seba-services.md
@@ -2,9 +2,10 @@
This chart contains all the XOS services needed to install SEBA.
-You can install it using:
+{% include "../partials/helm/add-cord-repo.md" %}
-```bash
-helm dep update xos-profiles/seba-services
-helm install -n seba-service xos-profiles/seba-services/
-```
\ No newline at end of file
+You can then install it using:
+
+```shell
+helm install -n seba-service cord/seba-services
+```
diff --git a/charts/storage.md b/charts/storage.md
index 7f8fb11..cca25fc 100644
--- a/charts/storage.md
+++ b/charts/storage.md
@@ -174,7 +174,6 @@
into the `rook-ceph-system` namespace:
```shell
-cd helm-charts/storage
helm repo add rook-beta https://charts.rook.io/beta
helm dep update rook-operator
helm install --namespace rook-ceph-system -n rook-operator rook-operator
@@ -338,8 +337,10 @@
First, configure your nodes to deploy the [local-directory](#local-directory)
chart, then run:
+{% include "../partials/helm/add-cord-repo.md" %}
+
```shell
-helm install -f examples/xos-db-local-dir.yaml -n xos-core xos-core
+helm install -f examples/xos-db-local-dir.yaml -n xos-core cord/xos-core
```
### Example: XOS Database on a Ceph RBD volume
@@ -352,7 +353,7 @@
then load the XOS core charts with:
```shell
-helm install -f examples/xos-db-ceph-rbd.yaml -n xos-core xos-core
+helm install -f examples/xos-db-ceph-rbd.yaml -n xos-core cord/xos-core
```
### Example: Docker Registry on CephFS shared filesystem
diff --git a/charts/voltha.md b/charts/voltha.md
index 05e748c..2e0cc65 100644
--- a/charts/voltha.md
+++ b/charts/voltha.md
@@ -1,18 +1,8 @@
# Deploy VOLTHA
-VOLTHA depends on having a [kafka message bus](kafka.md) deployed with a name
-of `cord-kafka`, so deploy that with helm before deploying the voltha chart.
-
-
## First Time Installation
-Download the helm charts `incubator` repository:
-
-```shell
-helm repo add incubator https://kubernetes-charts-incubator.storage.googleapis.com/
-```
-
-Install the etcd-operator helm chart. This chart provides a convenient way of creating and managing etcd clusters. When voltha installs it will attempt to use etcd-operator to create its etcd cluster. Once installed etcd-operator can be left running.
+Install the etcd-operator helm chart first. This chart provides a convenient way of creating and managing etcd clusters. When VOLTHA installs it will attempt to use etcd-operator to create its etcd cluster. Once installed etcd-operator can be left running.
```shell
helm install -n etcd-operator stable/etcd-operator --version 0.8.0
@@ -24,21 +14,15 @@
kubectl get crd | grep etcd
```
+{% include "../partials/helm/add-cord-repo.md" %}
-
-Update dependencies within the voltha chart:
+Then, install the VOLTHA helm chart. This will create the VOLTHA pods and will create the etcd-cluster pods.
```shell
-helm dep up voltha
+helm install -n voltha cord/voltha
```
-Install the voltha helm chart. This will create the voltha pods and additionally create the etcd-cluster pods
-
-```shell
-helm install -n voltha voltha
-```
-
-Allow enough time for the 3 etcd-cluster pods to start before using the voltha pods.
+Allow enough time for the 3 etcd-cluster pods to start before using the VOLTHA pods.
## Standard Uninstall
@@ -49,7 +33,7 @@
## Standard Install
```shell
-helm install -n voltha voltha
+helm install -n voltha cord/voltha
```
## Nodeports Exposed
@@ -70,25 +54,23 @@
ssh voltha@<pod-ip> -p 30110
```
-The default VOLTHA password is `admin`.
+The default VOLTHA password is *admin*.
## Building and using development images
-In some cases you want to build custom images to try out development code.
-The suggested way to do that is:
+In some cases you may want to build custom images to try out development code. In order to do that, from the CORD repository, do:
```shell
-cd ~/cord/incubator/voltha
+cd incubator/voltha
REPOSITORY=voltha/ TAG=dev VOLTHA_BUILD=docker make build
cd ~/cord/automation-tools/developer
bash tag_and_push.sh -t dev -r 192.168.99.100:30500
```
-_This set of commands will build the VOLTHA containers and push them to a local
-[docker registry](../partials/push-images-to-registry.md) using a TAG called *dev*.
+This set of commands builds the VOLTHA containers and pushes them to a local
+[docker registry](../partials/push-images-to-registry.md) using a tag called *dev*.
-Once the images are pushed to a docker registry on the POD,
-you can use a values file like the following one:
+Once the images are pushed to a docker registry on the POD, you can create a values file like the following one, to override the default chart values, so use your images:
```yaml
# voltha-values.yaml
@@ -120,8 +102,8 @@
```
-and you can install VOLTHA using:
+Then, install VOLTHA using:
```shell
-helm install -n voltha voltha -f voltha-values.yaml
+helm install -n voltha -f voltha-values.yaml cord/voltha
```
diff --git a/charts/xos-core.md b/charts/xos-core.md
index 3d31434..487b23a 100644
--- a/charts/xos-core.md
+++ b/charts/xos-core.md
@@ -2,9 +2,10 @@
To deploy the XOS core and affiliated containers, run the following:
+{% include "../partials/helm/add-cord-repo.md" %}
+
```shell
-helm dep update xos-core
-helm install -n xos-core xos-core
+helm install -n xos-core cord/xos-core
```
**Nodeports exposed**
@@ -14,11 +15,10 @@
## Customizing security information
-We strongly recommend you to override the default values of `xosAdminUser` and
-`xosAdminPassword` with custom values.
+We strongly recommend you to override the default values of *xosAdminUser* and
+*xosAdminPassword* with custom values.
-You can do it using a [`values.yaml`](https://docs.helm.sh/chart_template_guide/#values-files)
-file like this one:
+You can do it using a [`values.yaml`](https://docs.helm.sh/chart_template_guide/#values-files) file like this one:
```yaml
# custom-security.yaml
@@ -29,14 +29,17 @@
and add it to the install command:
```shell
-helm install -n xos-core xos-core -f custom-security.yaml
+helm install -f custom-security.yaml -n xos-core cord/xos-core
```
or you can override the values from the CLI
```shell
-helm install -n xos-core xos-core --set xosAdminUser=MyUser --set xosAdminPassword=MySuperSecurePassword
+helm install -n xos-core cord/xos-core \
+ --set xosAdminUser=MyUser \
+ --set xosAdminPassword=MySuperSecurePassword
```
+
> **Important!**
> If you override security values in the `xos-core` chart, you'll need to pass
> these values, either via a file or cli arguments, to all the xos related charts
diff --git a/charts/xossh.md b/charts/xossh.md
index 675a23e..65d6b56 100644
--- a/charts/xossh.md
+++ b/charts/xossh.md
@@ -1,7 +1,9 @@
# Deploy XOSSH
-To deploy the XOS-Shell, run the following:
+{% include "../partials/helm/add-cord-repo.md" %}
+
+Then, to deploy the XOS-Shell run the following:
```shell
-helm install xos-tools/xossh -n xossh
+helm install -n xossh cord/xossh
```
diff --git a/images/diag_overview.png b/images/diag_overview.png
new file mode 100644
index 0000000..9a059c8
--- /dev/null
+++ b/images/diag_overview.png
Binary files differ
diff --git a/navigate.md b/navigate.md
index f307986..56cb057 100644
--- a/navigate.md
+++ b/navigate.md
@@ -12,7 +12,7 @@
* **Kubernetes:** All elements of the CORD control plane run in
Kubernetes containers. CORD assumes a Kubernetes foundation,
- but does not prescribe how Kubernetes (or the underlying hardware)
+ but does not prescribe how Kubernetes or the underlying hardware
are installed.
* **Platform:** The Platform layer consists of ONOS, XOS,
@@ -20,7 +20,7 @@
all running on a Kubernetes foundation. The platform is common
to all Profiles.
-* **Profile:** Each unique CORD configuration corresponds to a
+* **Profile:** Each unique CORD configuration is defined by a
Profile. It consists of a set of services (e.g., access services,
VNFs, other cloud services), including both abstract services
on-boarded into XOS and SDN control apps running on ONOS.
@@ -29,10 +29,12 @@
* **Workflow:** A Profile includes one or more workflows, each of
which defines the business logic and state machine for one of the
- access technologies. A workflow customizes a Profile for the target
- deployment environment; it is not a layer, per se. SEBA's
- [AT&T Workflow](profiles/seba/workflows/att-install.md) is an example.
-
+ access technologies contained in the Profile. A workflow customizes
+ a Profile for the target deployment environment; it is not a
+ software layer, per se. SEBA's
+ [AT&T Workflow](profiles/seba/workflows/att-install.md)
+ is an example.
+
The diagram also shows a hardware bill-of-materials, which must be
defined for a given POD.
diff --git a/operating_cord/diag.md b/operating_cord/diag.md
index 6f45f4c..5e717d0 100644
--- a/operating_cord/diag.md
+++ b/operating_cord/diag.md
@@ -1,5 +1,25 @@
# Monitoring and Logging
CORD is usually configured with monitoring and logging capabilities,
-built around Prometheus and ELK Stack, respectively. Both work on
-events/logs posted to Kafka and display results on a Kibana dashboard.
+built around Prometheus and ELK Stack, respectively. Both consume
+events/metrics/logs posted to Kafka. The data they collect can be
+viewed on their respective dashboards:
+
+* **Metrics:** Collected by [Prometheus](https://prometheus.io/)
+ and viewable using [Grafana](http://docs.grafana.org/) at port 31300.
+
+* **Logs:** Collected by [Elk Stack](https://www.elastic.co/elk-stack)
+ and viewable using
+ [Kibana](https://www.elastic.co/guide/en/kibana/current/index.html)
+ at port 30601.
+
+The following figure give a high-level overview of the monitoring and
+logging system.
+
+
+
+The monitoring and logging pipelines both share a Kafka bus, with
+event topics assigned accordingly (e.g., `component.kpis.*` and
+`component.log.*`). Components also post other events to Kafka,
+but their topics are currently ad hoc and rapidly evolving.
+Rationalizing the event schema is on the near-term roadmap.
diff --git a/partials/helm/add-cord-repo.md b/partials/helm/add-cord-repo.md
new file mode 100644
index 0000000..386498f
--- /dev/null
+++ b/partials/helm/add-cord-repo.md
@@ -0,0 +1,6 @@
+If you haven't done it yet, add the CORD repository to the list of your local repositories and update the repo index:
+
+```shell
+helm repo add cord https://gerrit.opencord.org
+helm repo update
+```
