blob: 1758f035bcb5ddd61f0a93296f0fae75fcf2507b [file] [log] [blame]
Matteo Scandolo1f5530b2019-12-17 10:12:31 -08001.. _deploy_physical:
2
3Deploy a physical VOLTHA POD
4============================
5
6Quickstart
7----------
8
Zack Williamsc6460c22019-12-18 14:54:43 -07009The quickstart assumes you POD is already correctly cabled, if not you can
10refer to :ref:`Physical_Layout`
Matteo Scandolo1f5530b2019-12-17 10:12:31 -080011
12Requires:
13
14- a physical kubernetes cluster
15- `kind-voltha <https://github.com/ciena/kind-voltha>`_ cloned on your machine
16
17
Zack Williamsc6460c22019-12-18 14:54:43 -070018Enter the ``kind-voltha`` directory and execute this command (``kubectl`` must
19be installed and pointing to your cluster):
Matteo Scandolo1f5530b2019-12-17 10:12:31 -080020
21.. code:: bash
22
23 DEPLOY_K8S=no WITH_RADIUS=y CONFIG_SADIS=y ./voltha up
24
25If you already have a ``radius`` server that you want to use, change the flag to ``WITH_RADIUS=n``
26and `configure ONOS accordingly <https://github.com/opencord/aaa>`_.
27
28TLDR;
29-----
30
Zack Williamsc6460c22019-12-18 14:54:43 -070031Below are the complete steps to install a physical cluster. It assumes
32``kubectl`` and ``helm`` commands are already available.
Matteo Scandolo1f5530b2019-12-17 10:12:31 -080033
34Configure Helm
35--------------
36
Zack Williamsc6460c22019-12-18 14:54:43 -070037Helm provide a capability to install and manage Kubernetes applications.
Matteo Scandolo1f5530b2019-12-17 10:12:31 -080038VOLTHAs default deployment mechanism utilized Helm. Before Helm can be
39used to deploy VOLTHA it must be initialized and the repositories that
40container the artifacts required to deploy VOLTHA must be added to Helm.
41
42.. code:: bash
43
44 helm repo add incubator https://kubernetes-charts-incubator.storage.googleapis.com
45 helm repo add stable https://kubernetes-charts.storage.googleapis.com
46 helm repo add onf https://charts.opencord.org
47 helm repo update
48
49.. _installation_steps:
50
51Install EtcdOperator
52--------------------
53
54ETCD Operator is a utility that allows applications to create and manage
55ETCD key/value clusters as Kubernetes resources. VOLTHA utilizes this
56utility to create its key/value store. *NOTE: it is not required that
Zack Williamsc6460c22019-12-18 14:54:43 -070057VOLTHA create its own datastore as VOLTHA can utilize an existing
Matteo Scandolo1f5530b2019-12-17 10:12:31 -080058datastore, but for this example VOLTHA will creates its own datastore*
59
60.. code:: bash
61
62 helm install -f $TYPE-values.yaml --namespace voltha --name etcd-operator stable/etcd-operator
63
64Wait for operator pods
65~~~~~~~~~~~~~~~~~~~~~~
66
Zack Williamsc6460c22019-12-18 14:54:43 -070067Before continuing, the Kubernetes pods associated with ETCD Operator must
Matteo Scandolo1f5530b2019-12-17 10:12:31 -080068be in the ``Running`` state.
69
70.. code:: bash
71
72 kubectl get -n voltha pod
73
74Once all the pods are in the ``Running`` state the output, for a
75**full** deployment should be similar to the output below. For a
76**minimal** deployment there will only be a single pod, the
77``etcd-operator-etcd-operator-etcd-operator`` pod.
78
79.. code:: bash
80
81 NAME READY STATUS RESTARTS AGE
82 etcd-operator-etcd-operator-etcd-backup-operator-7897665cfq75w2 1/1 Running 0 2m
83 etcd-operator-etcd-operator-etcd-operator-7d579799f7-bjdnj 1/1 Running 0 2m
84 etcd-operator-etcd-operator-etcd-restore-operator-7d77d878wwcn7 1/1 Running 0 2m
85
86It is not just VOLTHA
87---------------------
88
89To demonstrate the capability of VOLTHA other *partner* applications are
Zack Williamsc6460c22019-12-18 14:54:43 -070090required, such as ONOS. The following sections describe how to install
Matteo Scandolo1f5530b2019-12-17 10:12:31 -080091and configure these *partner* applications.
92
Zack Williamsc6460c22019-12-18 14:54:43 -070093*NOTE: It is important to start ONOS before VOLTHA as if they are started in
94the reverse order the ``ofagent`` sometimes does not connect to the SDN
Matteo Scandolo1f5530b2019-12-17 10:12:31 -080095controller*\ `VOL-1764 <https://jira.opencord.org/browse/VOL-1764>`__.
96
97ONOS (OpenFlow Controller)
98~~~~~~~~~~~~~~~~~~~~~~~~~~
99
Zack Williamsc6460c22019-12-18 14:54:43 -0700100VOLTHA exposes an OLT and its connected ONUs as an OpenFlow switch. To control
101that virtual OpenFlow switch an OpenFlow controller is required. For most
102VOLTHA deployments that controller is ONOS, with a set of ONOS applications
103installed. To install ONOS use the following Helm command:
Matteo Scandolo1f5530b2019-12-17 10:12:31 -0800104
105.. code:: bash
106
107 helm install -f $TYPE-values.yaml --name onos onf/onos
108
109Exposing ONOS Services
110^^^^^^^^^^^^^^^^^^^^^^
111
112.. code:: bash
113
114 screen -dmS onos-ui kubectl port-forward service/onos-ui 8181:8181
115 screen -dmS onos-ssh kubectl port-forward service/onos-ssh 8101:8101
116
117Configuring ONOS Applications
118^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
119
120Configuration files have been provided to configure aspects of the ONOS
121deployment. The following curl commands push those configurations to the
122ONOS instance. It is possible (likely) that ONOS wont be immediately
123ready to accept REST requests, so the first ``curl`` command may need
124retried until ONOS is ready to accept REST connections.
125
126.. code:: bash
127
128 curl --fail -sSL --user karaf:karaf \
129 -X POST -H Content-Type:application/json \
130 http://127.0.0.1:8181/onos/v1/network/configuration/apps/org.opencord.kafka \
131 --data @onos-files/onos-kafka.json
132 curl --fail -sSL --user karaf:karaf \
133 -X POST -H Content-Type:application/json \
134 http://127.0.0.1:8181/onos/v1/network/configuration/apps/org.opencord.dhcpl2relay \
135 --data @onos-files/onos-dhcpl2relay.json
136 curl --fail -sSL --user karaf:karaf \
137 -X POST -H Content-Type:application/json \
138 http://127.0.0.1:8181/onos/v1/configuration/org.opencord.olt.impl.Olt \
139 --data @onos-files/olt-onos-olt-settings.json
140 curl --fail -sSL --user karaf:karaf \
141 -X POST -H Content-Type:application/json \
142 http://127.0.0.1:8181/onos/v1/configuration/org.onosproject.net.flow.impl.FlowRuleManager \
143 --data @onos-files/olt-onos-enableExtraneousRules.json
144
145SADIS Configuration
146^^^^^^^^^^^^^^^^^^^
147
148The ONOS applications leverage the *Subscriber and Device Information
149Store (SADIS)* when processing EAPOL and DHCP packets from VOLTHA
Zack Williamsc6460c22019-12-18 14:54:43 -0700150controlled devices. In order for VOLTHA to function properly, SADIS
Matteo Scandolo1f5530b2019-12-17 10:12:31 -0800151entries must be configured into ONOS.
152
153The repository contains two example SADIS configuration that can be used
154with ONOS depending if you using VOLTHA with *tech profile* support
155(``onos-files/onos-sadis-no-tp.json``) or without *tech profile* support
156(``onos-files/onos-sadis-tp.json``). Either of these configurations can
157be pushed to ONOS using the following command:
158
159.. code:: bash
160
161 curl --fail -sSL --user karaf:karaf \
162 -X POST -H Content-Type:application/json \
163 http://127.0.0.1:8181/onos/v1/network/configuration/apps/org.opencord.sadis \
164 --data @<selected SADIS configuration file>
165
166Install VOLTHA Core
167-------------------
168
169VOLTHA has two main *parts*: core and adapters. The **core** provides
170the main logic for the VOLTHA application and the **adapters** contain
171logic to adapter vendor neutral operations to vendor specific devices.
172
173Before any adapters can be deployed the VOLTHA core must be installed
174and in the ``Running`` state. The following Helm command installs the
175core components of VOLTHA based on the desired deployment type.
176
177.. code:: bash
178
179 helm install -f $TYPE-values.yaml --set use_go=true --set defaults.log_level=WARN \
180 --namespace voltha --name voltha onf/voltha
181
182During the install of the core VOLTHA components some containers may
Zack Williamsc6460c22019-12-18 14:54:43 -0700183"crash" or restart. This is normal as there are dependencies, such as
Matteo Scandolo1f5530b2019-12-17 10:12:31 -0800184the read/write cores cannot start until the ETCD cluster is established
185and so they crash until the ETCD cluster is operational. Eventually all
186the containers should be in a ``Running`` state as queried by the
187command:
188
189.. code:: bash
190
191 kubectl get -n voltha pod
192
193The output should be similar to the following with a different number of
194``etcd-operator`` and ``voltha-etcd-cluster`` pods depending on the
195deployment type.
196
197.. code:: bash
198
199 NAME READY STATUS RESTARTS AGE
200 etcd-operator-etcd-operator-etcd-operator-7d579799f7-xq6f2 1/1 Running 0 19m
201 ofagent-8ccb7f5fb-hwgfn 1/1 Running 0 4m
202 ro-core-564f5cdcc7-2pch8 1/1 Running 0 4m
203 rw-core1-7fbb878cdd-6npvr 1/1 Running 2 4m
204 rw-core2-7fbb878cdd-k7w9j 1/1 Running 3 4m
205 voltha-api-server-5f7c8b5b77-k6mrg 2/2 Running 0 4m
206 voltha-cli-server-5df4c95b7f-kcpdl 1/1 Running 0 4m
207 voltha-etcd-cluster-4rsqcvpwr4 1/1 Running 0 4m
208 voltha-kafka-0 1/1 Running 0 4m
209 voltha-zookeeper-0 1/1 Running 0 4m
210
211Install Adapters
212----------------
213
214The following commands install both the simulated OLT and ONU adapters
215as well as the adapters for an OpenOLT and OpenONU device.
216
217.. code:: bash
218
219 helm install -f $TYPE-values.yaml -set use_go=true --set defaults.log_level=WARN \
220 --namespace voltha --name sim onf/voltha-adapter-simulated
221 helm install -f $TYPE-values.yaml -set use_go=true --set defaults.log_level=WARN \
222 --namespace voltha --name open-olt onf/voltha-adapter-openolt
223 helm install -f $TYPE-values.yaml -set use_go=true --set defaults.log_level=WARN \
224 --namespace voltha --name open-onu onf/voltha-adapter-openonu
225
226Exposing VOLTHA Services
227------------------------
228
Zack Williamsc6460c22019-12-18 14:54:43 -0700229At this point VOLTHA is deployed, and from within the Kubernetes cluster
Matteo Scandolo1f5530b2019-12-17 10:12:31 -0800230the VOLTHA services can be reached. However, from outside the Kubernetes
231cluster the services cannot be reached.
232
233.. code:: bash
234
235 screen -dmS voltha-api kubectl port-forward -n voltha service/voltha-api 55555:55555
236 screen -dmS voltha-ssh kubectl port-forward -n voltha service/voltha-cli 5022:5022
237
238Install FreeRADIUS Service
239--------------------------
240
241.. code:: bash
242
243 helm install -f minimal-values.yaml --namespace voltha --name radius onf/freeradius
244
245Configure ``voltctl`` to Connect to VOLTHA
246------------------------------------------
247
Zack Williamsc6460c22019-12-18 14:54:43 -0700248In order for ``voltctl`` to connect to the VOLTHA instance deployed in
Matteo Scandolo1f5530b2019-12-17 10:12:31 -0800249the Kubernetes cluster it must know which IP address and port to use.
250This configuration can be persisted to a local config file using the
251following commands.
252
253.. code:: bash
254
255 mkdir -p $HOME/.volt
256 voltctl -a v2 -s localhost:55555 config > $HOME/.volt/config
257
258To test the connectivity you can query the version of the VOLTHA client
Zack Williamsc6460c22019-12-18 14:54:43 -0700259and server::
Matteo Scandolo1f5530b2019-12-17 10:12:31 -0800260
261 voltctl version
262
Zack Williamsc6460c22019-12-18 14:54:43 -0700263The output should be similar to the following::
Matteo Scandolo1f5530b2019-12-17 10:12:31 -0800264
265 Client:
266 Version unknown-version
267 Go version: unknown-goversion
268 Vcs reference: unknown-vcsref
269 Vcs dirty: unknown-vcsdirty
270 Built: unknown-buildtime
271 OS/Arch: unknown-os/unknown-arch
272
273 Cluster:
274 Version 2.1.0-dev
275 Go version: 1.12.6
276 Vcs feference: 28f120f1f4751284cadccf73f2f559ce838dd0a5
277 Vcs dirty: false
278 Built: 2019-06-26T16:58:22Z
Zack Williamsc6460c22019-12-18 14:54:43 -0700279 OS/Arch: linux/amd64