1e0a465559193e719a1ac0c5c112fd7c48c0926e
[pti/o2.git] / docs / installation-guide.rst
1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. SPDX-License-Identifier: CC-BY-4.0
3 .. Copyright (C) 2021 Wind River Systems, Inc.
4
5
6 Installation Guide
7 ==================
8
9 .. contents::
10    :depth: 3
11    :local:
12
13 Abstract
14 --------
15
16 This document describes how to install INF O2 service over O-RAN INF platform.
17
18 The audience of this document is assumed to have basic knowledge in kubernetes cli, helm chart cli.
19
20
21 Preface
22 -------
23
24 Before starting the installation and deployment of O-RAN O2 service, you should have already deployed O-RAN INF platform, and you need to download the helm charts or build from source as described in developer-guide.
25
26
27 INF O2 Service in E Release
28 ===========================
29
30 1. Provision remote cli for kubernetes over INF platform
31 --------------------------------------------------------
32
33
34 1.1 Setup Service Account over O-RAN INF platform
35 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
36
37 The following instruction must be done over INF platform controller host (controller-0)
38
39 -  Please see the O-RAN INF documentation to find out how to ssh to controller host of INF platform.
40
41 .. code:: shell
42
43   USER="admin-user"
44   NAMESPACE="kube-system"
45
46   cat <<EOF > admin-login.yaml
47   apiVersion: v1
48   kind: ServiceAccount
49   metadata:
50     name: ${USER}
51     namespace: kube-system
52   ---
53   apiVersion: rbac.authorization.k8s.io/v1
54   kind: ClusterRoleBinding
55   metadata:
56     name: ${USER}
57   roleRef:
58     apiGroup: rbac.authorization.k8s.io
59     kind: ClusterRole
60     name: cluster-admin
61   subjects:
62   - kind: ServiceAccount
63     name: ${USER}
64     namespace: kube-system
65   EOF
66
67   kubectl apply -f admin-login.yaml
68   TOKEN_DATA=$(kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep ${USER} | awk '{print $1}') | grep "token:" | awk '{print $2}')
69   echo $TOKEN_DATA
70
71
72 1.2 Setup remote cli over another linux host (ubuntu as example)
73 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
74
75 The following instruction should be done outside of INF platform controller host
76
77 .. code:: shell
78
79   sudo apt-get install -y apt-transport-https
80   echo "deb http://mirrors.ustc.edu.cn/kubernetes/apt kubernetes-xenial main" | \
81   sudo tee -a /etc/apt/sources.list.d/kubernetes.list
82   gpg --keyserver keyserver.ubuntu.com --recv-keys 836F4BEB
83   gpg --export --armor 836F4BEB | sudo apt-key add -
84   sudo apt-get update
85   sudo apt-get install -y kubectl
86
87   source <(kubectl completion bash) # setup autocomplete in bash into the current shell, bash-completion package should be installed first.
88   echo "source <(kubectl completion bash)" >> ~/.bashrc # add autocomplete permanently to your bash shell.
89
90   curl -O https://get.helm.sh/helm-v3.5.3-linux-amd64.tar.gz
91   tar xvf helm-v3.5.3-linux-amd64.tar.gz
92   sudo cp linux-amd64/helm /usr/local/bin/
93
94   source <(helm completion bash)
95   echo "source <(helm completion bash)" >> ~/.bashrc
96
97   OAM_IP=<INF OAM IP>
98   NAMESPACE=oran-o2
99   TOKEN_DATA=<TOKEN_DATA from INF>
100
101   USER="admin-user"
102
103   kubectl config set-cluster inf-cluster --server=https://${OAM_IP}:6443 --insecure-skip-tls-verify
104   kubectl config set-credentials ${USER} --token=$TOKEN_DATA
105   kubectl config set-context ${USER}@inf-cluster --cluster=inf-cluster --user ${USER} --namespace=${NAMESPACE}
106   kubectl config use-context ${USER}@inf-cluster
107
108   kubectl get pods -A
109
110
111 2. Deploy INF O2 service
112 ------------------------
113
114 2.1 Retrieve Helm chart for deploying of INF O2 service
115 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
116
117 .. code:: shell
118
119   git clone -b e-release "https://gerrit.o-ran-sc.org/r/pti/o2"
120
121
122
123 2.2 Prepare override yaml
124 ~~~~~~~~~~~~~~~~~~~~~~~~~
125
126 .. code:: shell
127
128   export NAMESPACE=oran-o2
129   kubectl create ns ${NAMESPACE}
130
131   # default kube config location is ~/.kube/config
132   cp ~/.kube/config o2/charts/resources/scripts/init/k8s_kube.conf
133
134   export OS_AUTH_URL=<INF OAM Auth URL e.g.: http://OAM_IP:5000/v3>
135   export OS_USERNAME=<INF username e.g.: admin>
136   export OS_PASSWORD=<INF password for user e.g.: adminpassword>
137
138   # If the external OAM IP same as OS_AUTH_URL's IP address, you can use the below command to set the environment
139   # export API_HOST_EXTERNAL_FLOATING=$(echo ${OS_AUTH_URL} | sed -e s,`echo ${OS_AUTH_URL} | grep :// | sed -e's,^\(.*//\).*,\1,g'`,,g | cut -d/ -f1 | sed -e 's,:.*,,g')
140   export API_HOST_EXTERNAL_FLOATING=<INF external_oam_floating_address e.g.: 128.10.10.10>
141
142   # please specify the smo service account yaml file
143   export SMO_SERVICEACCOUNT=<your input here eg.: smo>
144   # service account and binding for smo yaml file
145
146   cat <<EOF >smo-serviceaccount.yaml
147   apiVersion: rbac.authorization.k8s.io/v1
148   kind: Role
149   metadata:
150     namespace: default
151     name: pod-reader
152   rules:
153   - apiGroups: [""] # "" indicates the core API group
154     resources: ["pods"]
155     verbs: ["get", "watch", "list"]
156   ---
157   apiVersion: v1
158   kind: ServiceAccount
159   metadata:
160     name: ${SMO_SERVICEACCOUNT}
161     namespace: default
162   ---
163   apiVersion: rbac.authorization.k8s.io/v1
164   kind: RoleBinding
165   metadata:
166     name: read-pods
167     namespace: default
168   roleRef:
169     apiGroup: rbac.authorization.k8s.io
170     kind: Role
171     name: pod-reader
172   subjects:
173   - kind: ServiceAccount
174     name: ${SMO_SERVICEACCOUNT}
175     namespace: default
176
177   EOF
178
179   kubectl apply -f smo-serviceaccount.yaml
180
181   #export the smo account token data
182   export SMO_TOKEN_DATA=$(kubectl -n default describe secret $(kubectl -n default get secret | grep ${SMO_SERVICEACCOUNT} | awk '{print $1}') | grep "token:" | awk '{print $2}')
183
184   #prepare the application config file
185   cat <<EOF >app.conf
186   [DEFAULT]
187
188   ocloud_global_id = 4e24b97c-8c49-4c4f-b53e-3de5235a4e37
189   smo_register_url = http://127.0.0.1:8090/register
190   smo_token_data = ${SMO_TOKEN_DATA}
191
192   [API]
193   test = "hello"
194
195   [WATCHER]
196
197   [PUBSUB]
198
199   EOF
200
201   #prepare the ssl cert files or generate with below command.
202
203   PARENT="imsserver"
204   openssl req \
205   -x509 \
206   -newkey rsa:4096 \
207   -sha256 \
208   -days 365 \
209   -nodes \
210   -keyout $PARENT.key \
211   -out $PARENT.crt \
212   -subj "/CN=${PARENT}" \
213   -extensions v3_ca \
214   -extensions v3_req \
215   -config <( \
216     echo '[req]'; \
217     echo 'default_bits= 4096'; \
218     echo 'distinguished_name=req'; \
219     echo 'x509_extension = v3_ca'; \
220     echo 'req_extensions = v3_req'; \
221     echo '[v3_req]'; \
222     echo 'basicConstraints = CA:FALSE'; \
223     echo 'keyUsage = nonRepudiation, digitalSignature, keyEncipherment'; \
224     echo 'subjectAltName = @alt_names'; \
225     echo '[ alt_names ]'; \
226     echo "DNS.1 = www.${PARENT}"; \
227     echo "DNS.2 = ${PARENT}"; \
228     echo '[ v3_ca ]'; \
229     echo 'subjectKeyIdentifier=hash'; \
230     echo 'authorityKeyIdentifier=keyid:always,issuer'; \
231     echo 'basicConstraints = critical, CA:TRUE, pathlen:0'; \
232     echo 'keyUsage = critical, cRLSign, keyCertSign'; \
233     echo 'extendedKeyUsage = serverAuth, clientAuth')
234
235
236   applicationconfig=`base64 app.conf -w 0`
237   caconfig=`base64 imsserver.crt -w 0`
238   serverkeyconfig=`base64 imsserver.key -w 0`
239
240   echo $applicationconfig
241   echo $caconfig
242   echo $serverkeyconfig
243
244
245   cat <<EOF>o2service-override.yaml
246   o2ims:
247     serviceaccountname: admin-oran-o2
248     image:
249       repository: nexus3.o-ran-sc.org:10004/o-ran-sc/pti-o2imsdms
250       tag: 2.0.0
251       pullPolicy: IfNotPresent
252     logginglevel: "DEBUG"
253
254   ocloud:
255     OS_AUTH_URL: "${OS_AUTH_URL}"
256     OS_USERNAME: "${OS_USERNAME}"
257     OS_PASSWORD: "${OS_PASSWORD}"
258     API_HOST_EXTERNAL_FLOATING: "${API_HOST_EXTERNAL_FLOATING}"
259
260   applicationconfig: ${applicationconfig}
261   caconfig: ${caconfig}
262   serverkeyconfig: ${serverkeyconfig}
263
264   EOF
265
266   cat o2service-override.yaml
267
268
269 2.3 Deploy by helm cli
270 ~~~~~~~~~~~~~~~~~~~~~~
271
272 .. code:: shell
273
274   helm install o2service o2/charts -f o2service-override.yaml
275   helm list |grep o2service
276   kubectl -n ${NAMESPACE} get pods |grep o2api
277   kubectl -n ${NAMESPACE} get services |grep o2api
278
279
280 2.4 Verify INF O2 service
281 ~~~~~~~~~~~~~~~~~~~~~~~~~
282
283 .. code:: shell
284
285   curl -k http(s)://<OAM IP>:30205/o2ims_infrastructureInventory/v1/
286
287
288 2.5 INF O2 Service API Swagger
289 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
290
291 - Swagger UI can be found with URL: http(s)://<OAM IP>:30205
292
293
294 3. Register INF O2 Service to SMO
295 ---------------------------------
296
297 - assumed you have setup SMO O2 endpoint for registration
298 - INF O2 service will post the INF platform registration data to that SMO O2 endpoint
299
300
301 .. code:: shell
302
303   curl -X 'GET' \
304   'http(s)://<OAM IP>:30205/provision/v1/smo-endpoint' \
305   -H 'accept: application/json'
306
307   curl -k -X 'POST' \
308     'http(s)://<OAM IP>:30205/provision/v1/smo-endpoint' \
309     -H 'accept: application/json' \
310     -H 'Content-Type: application/json' \
311     -d '{"endpoint": "<SMO O2 endpoint for registration>"}'
312
313   # Confirm SMO endpoint provision status
314   curl -X 'GET' \
315   'http(s)://<OAM IP>:30205/provision/v1/smo-endpoint' \
316   -H 'accept: application/json'
317
318
319 References
320 ----------
321
322 - `O-RAN-SC INF`_
323
324 .. _`O-RAN-SC INF`: https://docs.o-ran-sc.org/en/latest/projects.html#infrastructure-inf