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_SECRET=$(kubectl -n default get serviceaccounts $SMO_SERVICEACCOUNT -o jsonpath='{.secrets[0].name}')
 183   export SMO_TOKEN_DATA=$(kubectl -n default get secrets $SMO_SECRET -o jsonpath='{.data.token}')
 184
 185   #prepare the application config file
 186   cat <<EOF >app.conf
 187   [DEFAULT]
 188
 189   ocloud_global_id = 4e24b97c-8c49-4c4f-b53e-3de5235a4e37
 190
 191   smo_register_url = http://127.0.0.1:8090/register
 192   smo_token_data = ${SMO_TOKEN_DATA}
 193
 194   [OCLOUD]
 195   OS_AUTH_URL: ${OS_AUTH_URL}
 196   OS_USERNAME: ${OS_USERNAME}
 197   OS_PASSWORD: ${OS_PASSWORD}
 198   API_HOST_EXTERNAL_FLOATING: ${API_HOST_EXTERNAL_FLOATING}
 199
 200   [API]
 201
 202   [WATCHER]
 203
 204   [PUBSUB]
 205
 206   EOF
 207
 208   #prepare the ssl cert files or generate with below command.
 209
 210   PARENT="imsserver"
 211   openssl req \
 212   -x509 \
 213   -newkey rsa:4096 \
 214   -sha256 \
 215   -days 365 \
 216   -nodes \
 217   -keyout $PARENT.key \
 218   -out $PARENT.crt \
 219   -subj "/CN=${PARENT}" \
 220   -extensions v3_ca \
 221   -extensions v3_req \
 222   -config <( \
 223     echo '[req]'; \
 224     echo 'default_bits= 4096'; \
 225     echo 'distinguished_name=req'; \
 226     echo 'x509_extension = v3_ca'; \
 227     echo 'req_extensions = v3_req'; \
 228     echo '[v3_req]'; \
 229     echo 'basicConstraints = CA:FALSE'; \
 230     echo 'keyUsage = nonRepudiation, digitalSignature, keyEncipherment'; \
 231     echo 'subjectAltName = @alt_names'; \
 232     echo '[ alt_names ]'; \
 233     echo "DNS.1 = www.${PARENT}"; \
 234     echo "DNS.2 = ${PARENT}"; \
 235     echo '[ v3_ca ]'; \
 236     echo 'subjectKeyIdentifier=hash'; \
 237     echo 'authorityKeyIdentifier=keyid:always,issuer'; \
 238     echo 'basicConstraints = critical, CA:TRUE, pathlen:0'; \
 239     echo 'keyUsage = critical, cRLSign, keyCertSign'; \
 240     echo 'extendedKeyUsage = serverAuth, clientAuth')
 241
 242
 243   applicationconfig=`base64 app.conf -w 0`
 244   servercrt=`base64 imsserver.crt -w 0`
 245   serverkey=`base64 imsserver.key -w 0`
 246   smocacrt=`base64 smoca.crt -w 0`
 247
 248   echo $applicationconfig
 249   echo $servercrt
 250   echo $serverkey
 251   echo $smocacrt
 252
 253
 254   cat <<EOF>o2service-override.yaml
 255   imagePullSecrets:
 256     - default-registry-key
 257
 258   o2ims:
 259     serviceaccountname: admin-oran-o2
 260     images:
 261       tags:
 262         o2service: nexus3.o-ran-sc.org:10004/o-ran-sc/pti-o2imsdms:2.0.0
 263         postgres: docker.io/library/postgres:9.6
 264         redis: docker.io/library/redis:alpine
 265       pullPolicy: IfNotPresent
 266     logginglevel: "DEBUG"
 267
 268   applicationconfig: ${applicationconfig}
 269   servercrt: ${servercrt}
 270   serverkey: ${serverkey}
 271   smocacrt: ${smocacrt}
 272
 273   EOF
 274
 275   cat o2service-override.yaml
 276
 277
 278 2.3 Deploy by helm cli
 279 ~~~~~~~~~~~~~~~~~~~~~~
 280
 281 .. code:: shell
 282
 283   helm install o2service o2/charts -f o2service-override.yaml
 284   helm list |grep o2service
 285   kubectl -n ${NAMESPACE} get pods |grep o2api
 286   kubectl -n ${NAMESPACE} get services |grep o2api
 287
 288
 289 2.4 Verify INF O2 service
 290 ~~~~~~~~~~~~~~~~~~~~~~~~~
 291
 292 .. code:: shell
 293
 294   curl -k http(s)://<OAM IP>:30205/o2ims_infrastructureInventory/v1/
 295
 296
 297 2.5 INF O2 Service API Swagger
 298 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 299
 300 - Swagger UI can be found with URL: http(s)://<OAM IP>:30205
 301
 302
 303 3. Register INF O2 Service to SMO
 304 ---------------------------------
 305
 306 - assumed you have setup SMO O2 endpoint for registration
 307 - INF O2 service will post the INF platform registration data to that SMO O2 endpoint
 308
 309
 310 .. code:: shell
 311
 312   curl -X 'GET' \
 313   'http(s)://<OAM IP>:30205/provision/v1/smo-endpoint' \
 314   -H 'accept: application/json'
 315
 316   curl -k -X 'POST' \
 317     'http(s)://<OAM IP>:30205/provision/v1/smo-endpoint' \
 318     -H 'accept: application/json' \
 319     -H 'Content-Type: application/json' \
 320     -d '{"endpoint": "<SMO O2 endpoint for registration>"}'
 321
 322   # Confirm SMO endpoint provision status
 323   curl -X 'GET' \
 324   'http(s)://<OAM IP>:30205/provision/v1/smo-endpoint' \
 325   -H 'accept: application/json'
 326
 327
 328 References
 329 ----------
 330
 331 - `O-RAN-SC INF`_
 332
 333 .. _`O-RAN-SC INF`: https://docs.o-ran-sc.org/en/latest/projects.html#infrastructure-inf