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-2022 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 the O-RAN INF
  17 platform.
  18
  19 The audience of this document is assumed to have basic knowledge of
  20 kubernetes CLI, and helm chart cli.
  21
  22 Preface
  23 -------
  24
  25 In the context of hosting a RAN Application on INF, the O-RAN O2
  26 Application provides and exposes the IMS and DMS service APIs of the O2
  27 interface between the O-Cloud (INF) and the Service Management &
  28 Orchestration (SMO), in the O-RAN Architecture.
  29
  30 The O2 interfaces enable the management of the O-Cloud (INF)
  31 infrastructure and the deployment life-cycle management of O-RAN
  32 cloudified NFs that run on O-Cloud (INF). See `O-RAN O2 General Aspects
  33 and Principles
  34 2.0 <https://orandownloadsweb.azurewebsites.net/specifications>`__, and
  35 `INF O2
  36 documentation <https://docs.o-ran-sc.org/projects/o-ran-sc-pti-o2/en/latest/>`__.
  37
  38 The O-RAN O2 application is integrated into INF as a system application.
  39 The O-RAN O2 application package is saved in INF during system
  40 installation, but it is not applied by default.
  41
  42 System administrators can follow the procedures below to install and
  43 uninstall the O-RAN O2 application.
  44
  45 INF O2 Service Install
  46 ======================
  47
  48 1. Prerequisites
  49 ----------------
  50
  51 Configure the internal Ceph storage for the O2 application persistent
  52 storage, see INF Storage Configuration and Management: `Configure the
  53 Internal Ceph Storage
  54 Backend <https://docs.starlingx.io/storage/kubernetes/configure-the-internal-ceph-storage-backend.html#configure-the-internal-ceph-storage-backend>`__.
  55
  56 Enable PVC support in ``oran-o2`` namespace, see INF Storage
  57 Configuration and Management: `Enable ReadWriteOnce PVC Support in
  58 Additional
  59 Namespaces <https://docs.starlingx.io/storage/kubernetes/enable-readwriteonce-pvc-support-in-additional-namespaces.html#enable-readwriteonce-pvc-support-in-additional-namespaces>`__.
  60
  61 2. Procedure
  62 ------------
  63
  64 You can install O-RAN O2 application on INF from the command line.
  65
  66 1. Locate the O2 application tarball in
  67    ``/usr/local/share/applications/helm``.
  68
  69    For example:
  70
  71    ::
  72
  73       /usr/local/share/applications/helm/oran-o2-<version>.tgz
  74
  75 2. Download ``admin_openrc.sh`` from the INF admin dashboard.
  76
  77    -  Visit http://put_your_OAM_IP_here:8080/project/api_access/
  78    -  Click the **Download OpenStack RC File”/”OpenStack RC File**
  79       button
  80
  81 3. Copy the file to the controller host.
  82
  83 4. Source the platform environment.
  84
  85    ::
  86
  87       $ source ./admin_openrc.sh
  88       ~(keystone_admin)]$
  89
  90 5. Upload the application.
  91
  92    ::
  93
  94       ~(keystone_admin)]$ system application-upload /usr/local/share/applications/helm/oran-o2-<version>.tgz
  95
  96 6. Prepare the override ``yaml`` file.
  97
  98    1. Create a service account for SMO application.
  99
 100       Create a ServiceAccount which can be used to provide SMO
 101       application with minimal access permission credentials.
 102
 103       ::
 104
 105          export SMO_SERVICEACCOUNT=smo1
 106
 107          cat <<EOF > smo-serviceaccount.yaml
 108          apiVersion: rbac.authorization.k8s.io/v1
 109          kind: Role
 110          metadata:
 111            namespace: default
 112            name: pod-reader
 113          rules:
 114          - apiGroups: [""] # "" indicates the core API group
 115            resources: ["pods"]
 116            verbs: ["get", "watch", "list"]
 117          ---
 118          apiVersion: v1
 119          kind: ServiceAccount
 120          metadata:
 121            name: ${SMO_SERVICEACCOUNT}
 122            namespace: default
 123          ---
 124          apiVersion: rbac.authorization.k8s.io/v1
 125          kind: RoleBinding
 126          metadata:
 127            name: read-pods
 128            namespace: default
 129          roleRef:
 130            apiGroup: rbac.authorization.k8s.io
 131            kind: Role
 132            name: pod-reader
 133          subjects:
 134          - kind: ServiceAccount
 135            name: ${SMO_SERVICEACCOUNT}
 136            namespace: default
 137          EOF
 138
 139          kubectl apply -f smo-serviceaccount.yaml
 140
 141    2. Create a secret for service account and obtain an access token.
 142
 143       Create a secret with the type service-account-token and pass the
 144       ServiceAccount in the annotation section as shown below:
 145
 146       ::
 147
 148          export SMO_SECRET=smo1-secret
 149
 150          cat <<EOF > smo-secret.yaml
 151          apiVersion: v1
 152          kind: Secret
 153          metadata:
 154            name: ${SMO_SECRET}
 155            annotations:
 156              kubernetes.io/service-account.name: ${SMO_SERVICEACCOUNT}
 157          type: kubernetes.io/service-account-token
 158          EOF
 159
 160          kubectl apply -f smo-secret.yaml
 161
 162          export SMO_TOKEN_DATA=$(kubectl get secrets $SMO_SECRET -o jsonpath='{.data.token}' | base64 -d -w 0)
 163
 164    3. Create certificates for the O2 service.
 165
 166       Obtain an intermediate or Root CA-signed certificate and key from
 167       a trusted intermediate or Root Certificate Authority (CA). Refer
 168       to the documentation for the external Root CA that you are using
 169       on how to create a public certificate and private key pairs signed
 170       by an intermediate or Root CA for HTTPS.
 171
 172       For lab purposes, see INF Security: `Create Certificates Locally
 173       using
 174       openssl <https://docs.starlingx.io/security/kubernetes/create-certificates-locally-using-openssl.html#create-certificates-locally-using-openssl>`__
 175       to create an Intermediate or test Root CA certificate and key, and
 176       use it to locally sign test certificates.
 177
 178       The resulting files, from either an external CA or locally
 179       generated for the lab with openssl, should be:
 180
 181       -  Local CA certificate - ``my-root-ca-cert.pem``
 182       -  Server certificate - ``my-server-cert.pem``
 183       -  Server key - ``my-server-key.pem``
 184
 185       ..
 186
 187          **Note** If using a server certificate signed by a local CA
 188          (i.e. lab scenario above), this local CA certificate
 189          (e.g. my-root-ca-cert.pem from lab scenario above) must be
 190          shared with the SMO application for the O2 server certificate
 191          verification.
 192
 193    4. Prepare the O2 service application configuration file.
 194
 195       As per the Cloudification and Orchestration use case defined in
 196       O-RAN Working Group 6, the following information should be
 197       generated by SMO:
 198
 199       -  O-Cloud Gload ID - ``OCLOUD_GLOBAL_ID``
 200       -  SMO Register URL - ``SMO_REGISTER_URL``
 201
 202       See `O-RAN Cloudification and Orchestration Use Cases and
 203       Requirements for O-RAN Virtualized
 204       RAN <https://orandownloadsweb.azurewebsites.net/specifications>`__.
 205
 206       ::
 207
 208          API_HOST_EXTERNAL_FLOATING=$(echo ${OS_AUTH_URL} | awk -F / '{print $3}' | cut -d: -f1)
 209
 210          cat <<EOF > app.conf
 211          [DEFAULT]
 212
 213          ocloud_global_id = ${OCLOUD_GLOBAL_ID}
 214          smo_register_url = ${SMO_REGISTER_URL}
 215          smo_token_data = ${SMO_TOKEN_DATA}
 216
 217          [OCLOUD]
 218          OS_AUTH_URL = ${OS_AUTH_URL}
 219          OS_USERNAME = ${OS_USERNAME}
 220          OS_PASSWORD = ${OS_PASSWORD}
 221          API_HOST_EXTERNAL_FLOATING = ${API_HOST_EXTERNAL_FLOATING}
 222
 223          [API]
 224
 225          [WATCHER]
 226
 227          [PUBSUB]
 228          EOF
 229
 230    5. Retrieve the CA certificate from your SMO vendor.
 231
 232       If the SMO application provides service via HTTPS, and the server
 233       certificate is self-signed, the CA certficate should be retrieved
 234       from the SMO.
 235
 236       This procedure assumes that the name of the certificate is
 237       ``smo-ca.pem``
 238
 239    6. Populate the override yaml file.
 240
 241       Refer to the previous step for the required override values.
 242
 243       ::
 244
 245          APPLICATION_CONFIG=$(base64 app.conf -w 0)
 246          SERVER_CERT=$(base64 my-server-cert.pem -w 0)
 247          SERVER_KEY=$(base64 my-server-key.pem -w 0)
 248          SMO_CA_CERT=$(base64 smo-ca.pem -w 0)
 249
 250          cat <<EOF > o2service-override.yaml
 251
 252          applicationconfig: ${APPLICATION_CONFIG}
 253          servercrt: ${SERVER_CERT}
 254          serverkey: ${SERVER_KEY}
 255          smocacrt: ${SMO_CA_CERT}
 256
 257          EOF
 258
 259       To deploy other versions of an image required for a quick
 260       solution, to have early access to the features (eg.
 261       oranscinf/pti-o2imsdms:2.0.0), and to authenticate images that are
 262       hosted by a private registry, follow the steps below:
 263
 264       1. Create a docker-registry secret in ``oran-o2`` namespace.
 265
 266          ::
 267
 268             export O2SERVICE_IMAGE_REG=<docker-server-endpoint>
 269
 270             kubectl create secret docker-registry private-registry-key \
 271             --docker-server=${O2SERVICE_IMAGE_REG} --docker-username=${USERNAME} \
 272             --docker-password=${PASSWORD} -n oran-o2
 273
 274       2. Refer to the ``imagePullSecrets`` in override file.
 275
 276          ::
 277
 278             cat <<EOF > o2service-override.yaml
 279             imagePullSecrets:
 280               - private-registry-key
 281
 282             o2ims:
 283               serviceaccountname: admin-oran-o2
 284               images:
 285                 tags:
 286                   o2service: ${O2SERVICE_IMAGE_REG}/docker.io/oranscinf/pti-o2imsdms:2.0.0
 287                   postgres: ${O2SERVICE_IMAGE_REG}/docker.io/library/postgres:9.6
 288                   redis: ${O2SERVICE_IMAGE_REG}/docker.io/library/redis:alpine
 289                 pullPolicy: IfNotPresent
 290               logginglevel: "DEBUG"
 291
 292             applicationconfig: ${APPLICATION_CONFIG}
 293             servercrt: ${SERVER_CERT}
 294             serverkey: ${SERVER_KEY}
 295             smocacrt: ${SMO_CA_CERT}
 296
 297             EOF
 298
 299 7. Update the overrides for the oran-o2 application.
 300
 301    ::
 302
 303       ~(keystone_admin)]$ system helm-override-update oran-o2 oran-o2 oran-o2 --values o2service-override.yaml
 304
 305       # Check the overrides
 306       ~(keystone_admin)]$ system helm-override-show oran-o2 oran-o2 oran-o2
 307
 308 8. Run the **system application-apply** command to apply the updates.
 309
 310    ::
 311
 312       ~(keystone_admin)]$ system application-apply oran-o2
 313
 314 9. Monitor the status using the command below.
 315
 316    ::
 317
 318       ~(keystone_admin)]$ watch -n 5 system application-list
 319
 320    OR
 321
 322    ::
 323
 324       ~(keystone_admin)]$ watch kubectl get all -n oran-o2
 325
 326 3. Results
 327 ----------
 328
 329 You have launched services in the above namespace.
 330
 331 4. Postrequisites
 332 -----------------
 333
 334 You will need to integrate INF with an SMO application that performs
 335 management of O-Cloud infrastructure and the deployment life cycle
 336 management of O-RAN cloudified NFs. See the following API reference for
 337 details:
 338
 339 -  `API O-RAN O2
 340    interface <https://docs.o-ran-sc.org/projects/o-ran-sc-pti-o2/en/latest/api.html>`__
 341
 342 INF O2 Service Uninstall
 343 ========================
 344
 345 .. _procedure-1:
 346
 347 1. Procedure
 348 ------------
 349
 350 You can uninstall the O-RAN O2 application on INF from the command line.
 351
 352 1. Uninstall the application.
 353
 354    Remove O2 application related resources.
 355
 356    ::
 357
 358       ~(keystone_admin)]$ system application-remove oran-o2
 359
 360 2. Delete the application.
 361
 362    Remove the uninstalled O2 application’s definition, including the
 363    manifest and helm charts and helm chart overrides, from the system.
 364
 365    ::
 366
 367       ~(keystone_admin)]$ system application-delete oran-o2
 368
 369 .. _results-1:
 370
 371 2. Results
 372 ----------
 373
 374 You have uninstalled the O2 application from the system.