Reorganizing docs
- Adding quickstart examples for the different workflows
- Adding an environemnt overview
- Adding workflow definition
- Adding operation guide
Change-Id: I474dd1a2ea6e916512041f80f2ca3039718ab219
diff --git a/overview/pod_physical.rst b/overview/pod_physical.rst
index 8a35abe..91be3a6 100644
--- a/overview/pod_physical.rst
+++ b/overview/pod_physical.rst
@@ -3,10 +3,7 @@
Deploy a physical VOLTHA POD
============================
-Quickstart
-----------
-
-The quickstart assumes you POD is already correctly cabled, if not you can
+This document assumes you POD is already correctly cabled, if not you can
refer to :ref:`lab_setup`
Requires:
@@ -21,262 +18,39 @@
.. code:: bash
- DEPLOY_K8S=no WITH_RADIUS=y CONFIG_SADIS=y ./voltha up
+ DEPLOY_K8S=no WITH_RADIUS=y CONFIG_SADIS=y SADIS_CFG="my-sadis-cfg.json" ./voltha up
+
+*``my-sadis-cfg.json`` is a reference to your own ``sadis`` configuration.
+This is needed to specify the appropriate values for your devices and subsribers*
If you already have a ``radius`` server that you want to use, change the flag to ``WITH_RADIUS=n``
and `configure ONOS accordingly <https://github.com/opencord/aaa>`_.
-For more information please check `kind-voltha page <kind-voltha/README.md>`_.
+For more information please check :doc:`kind-voltha page <../kind-voltha/README>`.
-TLDR;
------
+After the deployment please refer to :ref:`operate` .
-Below are the complete steps to install a physical cluster. It assumes
-``kubectl`` and ``helm`` commands are already available.
+HA Cluster
+----------
-Configure Helm
---------------
+To deploy ONOS in a multi instance environment for redundancy, High avaliablity and scale, you can add
+`NUM_OF_ONOS=3 NUM_OF_ATOMIX=3` to any of the workflow command. You can pick the number of instances onf ONOS
+and ATOMIX independently. As a good suggestion is 3 or 5.
-Helm provide a capability to install and manage Kubernetes applications.
-VOLTHA’s default deployment mechanism utilized Helm. Before Helm can be
-used to deploy VOLTHA it must be initialized and the repositories that
-container the artifacts required to deploy VOLTHA must be added to Helm.
+If you are planning to support a big number of ONU we suggest to horizontally scale
+the ``openonu-adapater``, you can do so by setting the ``NUM_OF_OPENONU`` variable.
+Generally speaking a single ``openonu-adapter`` instance can support up to 200 ONU devices.
+
+As an example for the ATT workflow:
.. code:: bash
- helm repo add incubator https://kubernetes-charts-incubator.storage.googleapis.com
- helm repo add stable https://kubernetes-charts.storage.googleapis.com
- helm repo add onf https://charts.opencord.org
- helm repo update
+ WITH_RADIUS=y CONFIG_SADIS=y SADIS_CFG="my-sadis-cfg.json" NUM_OF_ONOS=3 NUM_OF_ATOMIX=3 NUM_OF_OPENONU=8 ./voltha up
-.. _installation_steps:
+Configuration for in-band OLT control
+-------------------------------------
-Install EtcdOperator
---------------------
-
-ETCD Operator is a utility that allows applications to create and manage
-ETCD key/value clusters as Kubernetes resources. VOLTHA utilizes this
-utility to create its key/value store. *NOTE: it is not required that
-VOLTHA create its own datastore as VOLTHA can utilize an existing
-datastore, but for this example VOLTHA will creates its own datastore*
-
-.. code:: bash
-
- helm install -f $TYPE-values.yaml --namespace voltha --name etcd-operator stable/etcd-operator
-
-Wait for operator pods
-~~~~~~~~~~~~~~~~~~~~~~
-
-Before continuing, the Kubernetes pods associated with ETCD Operator must
-be in the ``Running`` state.
-
-.. code:: bash
-
- kubectl get -n voltha pod
-
-Once all the pods are in the ``Running`` state the output, for a
-**full** deployment should be similar to the output below. For a
-**minimal** deployment there will only be a single pod, the
-``etcd-operator-etcd-operator-etcd-operator`` pod.
-
-.. code:: bash
-
- NAME READY STATUS RESTARTS AGE
- etcd-operator-etcd-operator-etcd-backup-operator-7897665cfq75w2 1/1 Running 0 2m
- etcd-operator-etcd-operator-etcd-operator-7d579799f7-bjdnj 1/1 Running 0 2m
- etcd-operator-etcd-operator-etcd-restore-operator-7d77d878wwcn7 1/1 Running 0 2m
-
-It is not just VOLTHA
----------------------
-
-To demonstrate the capability of VOLTHA other *partner* applications are
-required, such as ONOS. The following sections describe how to install
-and configure these *partner* applications.
-
-*NOTE: It is important to start ONOS before VOLTHA as if they are started in
-the reverse order the ``ofagent`` sometimes does not connect to the SDN
-controller*\ `VOL-1764 <https://jira.opencord.org/browse/VOL-1764>`__.
-
-ONOS (OpenFlow Controller)
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-VOLTHA exposes an OLT and its connected ONUs as an OpenFlow switch. To control
-that virtual OpenFlow switch an OpenFlow controller is required. For most
-VOLTHA deployments that controller is ONOS, with a set of ONOS applications
-installed. To install ONOS use the following Helm command:
-
-.. code:: bash
-
- helm install -f $TYPE-values.yaml --name onos onf/onos
-
-Exposing ONOS Services
-^^^^^^^^^^^^^^^^^^^^^^
-
-.. code:: bash
-
- screen -dmS onos-ui kubectl port-forward service/onos-ui 8181:8181
- screen -dmS onos-ssh kubectl port-forward service/onos-ssh 8101:8101
-
-Configuring ONOS Applications
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Configuration files have been provided to configure aspects of the ONOS
-deployment. The following curl commands push those configurations to the
-ONOS instance. It is possible (likely) that ONOS won’t be immediately
-ready to accept REST requests, so the first ``curl`` command may need
-retried until ONOS is ready to accept REST connections.
-
-.. code:: bash
-
- curl --fail -sSL --user karaf:karaf \
- -X POST -H Content-Type:application/json \
- http://127.0.0.1:8181/onos/v1/network/configuration/apps/org.opencord.kafka \
- --data @onos-files/onos-kafka.json
- curl --fail -sSL --user karaf:karaf \
- -X POST -H Content-Type:application/json \
- http://127.0.0.1:8181/onos/v1/network/configuration/apps/org.opencord.dhcpl2relay \
- --data @onos-files/onos-dhcpl2relay.json
- curl --fail -sSL --user karaf:karaf \
- -X POST -H Content-Type:application/json \
- http://127.0.0.1:8181/onos/v1/configuration/org.opencord.olt.impl.Olt \
- --data @onos-files/olt-onos-olt-settings.json
- curl --fail -sSL --user karaf:karaf \
- -X POST -H Content-Type:application/json \
- http://127.0.0.1:8181/onos/v1/configuration/org.onosproject.net.flow.impl.FlowRuleManager \
- --data @onos-files/olt-onos-enableExtraneousRules.json
-
-SADIS Configuration
-^^^^^^^^^^^^^^^^^^^
-
-The ONOS applications leverage the *Subscriber and Device Information
-Store (SADIS)* when processing EAPOL and DHCP packets from VOLTHA
-controlled devices. In order for VOLTHA to function properly, SADIS
-entries must be configured into ONOS.
-
-The repository contains two example SADIS configuration that can be used
-with ONOS depending if you using VOLTHA with *tech profile* support
-(``onos-files/onos-sadis-no-tp.json``) or without *tech profile* support
-(``onos-files/onos-sadis-tp.json``). Either of these configurations can
-be pushed to ONOS using the following command:
-
-.. code:: bash
-
- curl --fail -sSL --user karaf:karaf \
- -X POST -H Content-Type:application/json \
- http://127.0.0.1:8181/onos/v1/network/configuration/apps/org.opencord.sadis \
- --data @<selected SADIS configuration file>
-
-Install VOLTHA Core
--------------------
-
-VOLTHA has two main *parts*: core and adapters. The **core** provides
-the main logic for the VOLTHA application and the **adapters** contain
-logic to adapter vendor neutral operations to vendor specific devices.
-
-Before any adapters can be deployed the VOLTHA core must be installed
-and in the ``Running`` state. The following Helm command installs the
-core components of VOLTHA based on the desired deployment type.
-
-.. code:: bash
-
- helm install -f $TYPE-values.yaml --set use_go=true --set defaults.log_level=WARN \
- --namespace voltha --name voltha onf/voltha
-
-During the install of the core VOLTHA components some containers may
-"crash" or restart. This is normal as there are dependencies, such as
-the read/write cores cannot start until the ETCD cluster is established
-and so they crash until the ETCD cluster is operational. Eventually all
-the containers should be in a ``Running`` state as queried by the
-command:
-
-.. code:: bash
-
- kubectl get -n voltha pod
-
-The output should be similar to the following with a different number of
-``etcd-operator`` and ``voltha-etcd-cluster`` pods depending on the
-deployment type.
-
-.. code:: bash
-
- NAME READY STATUS RESTARTS AGE
- etcd-operator-etcd-operator-etcd-operator-7d579799f7-xq6f2 1/1 Running 0 19m
- ofagent-8ccb7f5fb-hwgfn 1/1 Running 0 4m
- ro-core-564f5cdcc7-2pch8 1/1 Running 0 4m
- rw-core1-7fbb878cdd-6npvr 1/1 Running 2 4m
- rw-core2-7fbb878cdd-k7w9j 1/1 Running 3 4m
- voltha-api-server-5f7c8b5b77-k6mrg 2/2 Running 0 4m
- voltha-cli-server-5df4c95b7f-kcpdl 1/1 Running 0 4m
- voltha-etcd-cluster-4rsqcvpwr4 1/1 Running 0 4m
- voltha-kafka-0 1/1 Running 0 4m
- voltha-zookeeper-0 1/1 Running 0 4m
-
-Install Adapters
-----------------
-
-The following commands install both the simulated OLT and ONU adapters
-as well as the adapters for an OpenOLT and OpenONU device.
-
-.. code:: bash
-
- helm install -f $TYPE-values.yaml -set use_go=true --set defaults.log_level=WARN \
- --namespace voltha --name sim onf/voltha-adapter-simulated
- helm install -f $TYPE-values.yaml -set use_go=true --set defaults.log_level=WARN \
- --namespace voltha --name open-olt onf/voltha-adapter-openolt
- helm install -f $TYPE-values.yaml -set use_go=true --set defaults.log_level=WARN \
- --namespace voltha --name open-onu onf/voltha-adapter-openonu
-
-Exposing VOLTHA Services
-------------------------
-
-At this point VOLTHA is deployed, and from within the Kubernetes cluster
-the VOLTHA services can be reached. However, from outside the Kubernetes
-cluster the services cannot be reached.
-
-.. code:: bash
-
- screen -dmS voltha-api kubectl port-forward -n voltha service/voltha-api 55555:55555
- screen -dmS voltha-ssh kubectl port-forward -n voltha service/voltha-cli 5022:5022
-
-Install FreeRADIUS Service
---------------------------
-
-.. code:: bash
-
- helm install -f minimal-values.yaml --namespace voltha --name radius onf/freeradius
-
-Configure ``voltctl`` to Connect to VOLTHA
-------------------------------------------
-
-In order for ``voltctl`` to connect to the VOLTHA instance deployed in
-the Kubernetes cluster it must know which IP address and port to use.
-This configuration can be persisted to a local config file using the
-following commands.
-
-.. code:: bash
-
- mkdir -p $HOME/.volt
- voltctl -a v2 -s localhost:55555 config > $HOME/.volt/config
-
-To test the connectivity you can query the version of the VOLTHA client
-and server::
-
- voltctl version
-
-The output should be similar to the following::
-
- Client:
- Version unknown-version
- Go version: unknown-goversion
- Vcs reference: unknown-vcsref
- Vcs dirty: unknown-vcsdirty
- Built: unknown-buildtime
- OS/Arch: unknown-os/unknown-arch
-
- Cluster:
- Version 2.1.0-dev
- Go version: 1.12.6
- Vcs feference: 28f120f1f4751284cadccf73f2f559ce838dd0a5
- Vcs dirty: false
- Built: 2019-06-26T16:58:22Z
- OS/Arch: linux/amd64
+If OLT is being used in in-band connectivity mode, the following
+`document <https://docs.google.com/document/d/1OKDJCPEFVTEythAFUS_I7Piew4jHmhk25llK6UF04Wg>`_
+details the configuration aspects in ONOS and the aggregation switch to
+trunk/switch in-band packets from the OLT to BNG or Voltha.