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