X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=docs%2Finstallation-guide.rst;h=6856ea0a6d67d65b48042a207603acb2de97cf58;hb=5229119cf0fee426b2d14af3887b6fe4f78318a6;hp=617ec4f5531a074c0cd35aae040e3bc0d6cfa69a;hpb=5affabd057a01b9aaa4c7354e950753a8898954c;p=pti%2Fo2.git diff --git a/docs/installation-guide.rst b/docs/installation-guide.rst index 617ec4f..6856ea0 100644 --- a/docs/installation-guide.rst +++ b/docs/installation-guide.rst @@ -1,6 +1,6 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. SPDX-License-Identifier: CC-BY-4.0 -.. Copyright (C) 2021 Wind River Systems, Inc. +.. Copyright (C) 2021-2022 Wind River Systems, Inc. Installation Guide @@ -13,198 +13,362 @@ Installation Guide Abstract -------- -This document describes how to install INF O2 service over O-RAN INF platform. - -The audience of this document is assumed to have basic knowledge in kubernetes cli, helm chart cli. +This document describes how to install INF O2 service over the O-RAN INF +platform. +The audience of this document is assumed to have basic knowledge of +kubernetes CLI, and helm chart cli. Preface ------- -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. +In the context of hosting a RAN Application on INF, the O-RAN O2 +Application provides and exposes the IMS and DMS service APIs of the O2 +interface between the O-Cloud (INF) and the Service Management & +Orchestration (SMO), in the O-RAN Architecture. + +The O2 interfaces enable the management of the O-Cloud (INF) +infrastructure and the deployment life-cycle management of O-RAN +cloudified NFs that run on O-Cloud (INF). See `O-RAN O2 General Aspects +and Principles +2.0 `__, and +`INF O2 +documentation `__. + +The O-RAN O2 application is integrated into INF as a system application. +The O-RAN O2 application package is saved in INF during system +installation, but it is not applied by default. + +System administrators can follow the procedures below to install and +uninstall the O-RAN O2 application. + +INF O2 Service Install +====================== + +1. Prerequisites +---------------- + +Configure the internal Ceph storage for the O2 application persistent +storage, see INF Storage Configuration and Management: `Configure the +Internal Ceph Storage +Backend `__. + +Enable PVC support in ``oran-o2`` namespace, see INF Storage +Configuration and Management: `Enable ReadWriteOnce PVC Support in +Additional +Namespaces `__. + +2. Procedure +------------ + +You can install O-RAN O2 application on INF from the command line. + +1. Locate the O2 application tarball in + ``/usr/local/share/applications/helm``. + + For example: + + :: + + /usr/local/share/applications/helm/oran-o2-.tgz + +2. Download ``admin_openrc.sh`` from the INF admin dashboard. + + - Visit http://put_your_OAM_IP_here:8080/project/api_access/ + - Click the **Download OpenStack RC File”/”OpenStack RC File** + button + +3. Copy the file to the controller host. + +4. Source the platform environment. + + :: + + $ source ./admin_openrc.sh + ~(keystone_admin)]$ + +5. Upload the application. + + :: + + ~(keystone_admin)]$ system application-upload /usr/local/share/applications/helm/oran-o2-.tgz + +6. Prepare the override ``yaml`` file. + + 1. Create a service account for SMO application. + + Create a ServiceAccount which can be used to provide SMO + application with minimal access permission credentials. + :: -INF O2 Service in E Release -=========================== + export SMO_SERVICEACCOUNT=smo1 -1. Provision remote cli for kubernetes over INF platform --------------------------------------------------------- + cat < smo-serviceaccount.yaml + apiVersion: rbac.authorization.k8s.io/v1 + kind: Role + metadata: + namespace: default + name: pod-reader + rules: + - apiGroups: [""] # "" indicates the core API group + resources: ["pods"] + verbs: ["get", "watch", "list"] + --- + apiVersion: v1 + kind: ServiceAccount + metadata: + name: ${SMO_SERVICEACCOUNT} + namespace: default + --- + apiVersion: rbac.authorization.k8s.io/v1 + kind: RoleBinding + metadata: + name: read-pods + namespace: default + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: pod-reader + subjects: + - kind: ServiceAccount + name: ${SMO_SERVICEACCOUNT} + namespace: default + EOF + kubectl apply -f smo-serviceaccount.yaml -1.1 Setup Service Account over O-RAN INF platform -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + 2. Create a secret for service account and obtain an access token. -The following instruction must be done over INF platform controller host (controller-0) + Create a secret with the type service-account-token and pass the + ServiceAccount in the annotation section as shown below: -- Please see the O-RAN INF documentation to find out how to ssh to controller host of INF platform. + :: -.. code:: shell + export SMO_SECRET=smo1-secret - USER="admin-user" - NAMESPACE="kube-system" + cat < smo-secret.yaml + apiVersion: v1 + kind: Secret + metadata: + name: ${SMO_SECRET} + annotations: + kubernetes.io/service-account.name: ${SMO_SERVICEACCOUNT} + type: kubernetes.io/service-account-token + EOF - cat < admin-login.yaml - apiVersion: v1 - kind: ServiceAccount - metadata: - name: ${USER} - namespace: kube-system - --- - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRoleBinding - metadata: - name: ${USER} - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: cluster-admin - subjects: - - kind: ServiceAccount - name: ${USER} - namespace: kube-system - EOF + kubectl apply -f smo-secret.yaml - kubectl apply -f admin-login.yaml - TOKEN_DATA=$(kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep ${USER} | awk '{print $1}') | grep "token:" | awk '{print $2}') - echo $TOKEN_DATA + export SMO_TOKEN_DATA=$(kubectl get secrets $SMO_SECRET -o jsonpath='{.data.token}' | base64 -d -w 0) + 3. Create certificates for the O2 service. -1.2 Setup remote cli over another linux host (ubuntu as example) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Obtain an intermediate or Root CA-signed certificate and key from + a trusted intermediate or Root Certificate Authority (CA). Refer + to the documentation for the external Root CA that you are using + on how to create a public certificate and private key pairs signed + by an intermediate or Root CA for HTTPS. -The following instruction should be done outside of INF platform controller host + For lab purposes, see INF Security: `Create Certificates Locally + using + openssl `__ + to create an Intermediate or test Root CA certificate and key, and + use it to locally sign test certificates. -.. code:: shell + The resulting files, from either an external CA or locally + generated for the lab with openssl, should be: - sudo apt-get install -y apt-transport-https - echo "deb http://mirrors.ustc.edu.cn/kubernetes/apt kubernetes-xenial main" | \ - sudo tee -a /etc/apt/sources.list.d/kubernetes.list - gpg --keyserver keyserver.ubuntu.com --recv-keys 836F4BEB - gpg --export --armor 836F4BEB | sudo apt-key add - - sudo apt-get update - sudo apt-get install -y kubectl + - Local CA certificate - ``my-root-ca-cert.pem`` + - Server certificate - ``my-server-cert.pem`` + - Server key - ``my-server-key.pem`` - source <(kubectl completion bash) # setup autocomplete in bash into the current shell, bash-completion package should be installed first. - echo "source <(kubectl completion bash)" >> ~/.bashrc # add autocomplete permanently to your bash shell. + .. - curl -O https://get.helm.sh/helm-v3.5.3-linux-amd64.tar.gz - tar xvf helm-v3.5.3-linux-amd64.tar.gz - sudo cp linux-amd64/helm /usr/local/bin/ + **Note** If using a server certificate signed by a local CA + (i.e. lab scenario above), this local CA certificate + (e.g. my-root-ca-cert.pem from lab scenario above) must be + shared with the SMO application for the O2 server certificate + verification. - source <(helm completion bash) - echo "source <(helm completion bash)" >> ~/.bashrc + 4. Prepare the O2 service application configuration file. - OAM_IP= - NAMESPACE=orano2 - TOKEN_DATA= + As per the Cloudification and Orchestration use case defined in + O-RAN Working Group 6, the following information should be + generated by SMO: - USER="admin-user" + - O-Cloud Gload ID - ``OCLOUD_GLOBAL_ID`` + - SMO Register URL - ``SMO_REGISTER_URL`` - kubectl config set-cluster inf-cluster --server=https://${OAM_IP}:6443 --insecure-skip-tls-verify - kubectl config set-credentials ${USER} --token=$TOKEN_DATA - kubectl config set-context ${USER}@inf-cluster --cluster=inf-cluster --user ${USER} --namespace=${NAMESPACE} - kubectl config use-context ${USER}@inf-cluster + See `O-RAN Cloudification and Orchestration Use Cases and + Requirements for O-RAN Virtualized + RAN `__. - kubectl get pods -A + :: + API_HOST_EXTERNAL_FLOATING=$(echo ${OS_AUTH_URL} | awk -F / '{print $3}' | cut -d: -f1) -2. Deploy INF O2 service ------------------------- + cat < app.conf + [DEFAULT] -2.1 Retrieve Helm chart for deploying of INF O2 service -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ocloud_global_id = ${OCLOUD_GLOBAL_ID} + smo_register_url = ${SMO_REGISTER_URL} + smo_token_data = ${SMO_TOKEN_DATA} -.. code:: shell + [OCLOUD] + OS_AUTH_URL = ${OS_AUTH_URL} + OS_USERNAME = ${OS_USERNAME} + OS_PASSWORD = ${OS_PASSWORD} + API_HOST_EXTERNAL_FLOATING = ${API_HOST_EXTERNAL_FLOATING} - git clone -b e-release "https://gerrit.o-ran-sc.org/r/pti/o2" + [API] + [WATCHER] + [PUBSUB] + EOF -2.2 Prepare override yaml -~~~~~~~~~~~~~~~~~~~~~~~~~ + 5. Retrieve the CA certificate from your SMO vendor. -.. code:: shell + If the SMO application provides service via HTTPS, and the server + certificate is self-signed, the CA certficate should be retrieved + from the SMO. - export NAMESPACE=orano2 - kubectl create ns ${NAMESPACE} + This procedure assumes that the name of the certificate is + ``smo-ca.pem`` - # default kube config location is ~/.kube/config - cp ~/.kube/config o2/charts/resources/scripts/init/k8s_kube.conf + 6. Populate the override yaml file. - export OS_AUTH_URL= - export OS_USERNAME= - export OS_PASSWORD= + Refer to the previous step for the required override values. - cat <o2service-override.yaml - o2ims: - imagePullSecrets: admin-orano2-registry-secret - image: - repository: nexus3.o-ran-sc.org:10004/o-ran-sc/pti-o2imsdms - tag: 1.0.0 - pullPolicy: IfNotPresent - logginglevel: "DEBUG" + :: - ocloud: - OS_AUTH_URL: "${OS_AUTH_URL}" - OS_USERNAME: "${OS_USERNAME}" - OS_PASSWORD: "${OS_PASSWORD}" - K8S_KUBECONFIG: "/opt/k8s_kube.conf" - EOF + APPLICATION_CONFIG=$(base64 app.conf -w 0) + SERVER_CERT=$(base64 my-server-cert.pem -w 0) + SERVER_KEY=$(base64 my-server-key.pem -w 0) + SMO_CA_CERT=$(base64 smo-ca.pem -w 0) + cat < o2service-override.yaml -2.3 Deploy by helm cli -~~~~~~~~~~~~~~~~~~~~~~ + applicationconfig: ${APPLICATION_CONFIG} + servercrt: ${SERVER_CERT} + serverkey: ${SERVER_KEY} + smocacrt: ${SMO_CA_CERT} -.. code:: shell + EOF - helm install o2service o2/charts/ -f o2service-override.yaml - helm list |grep o2service - kubectl -n ${NAMESPACE} get pods |grep o2service - kubectl -n ${NAMESPACE} get services |grep o2service + To deploy other versions of an image required for a quick + solution, to have early access to the features (eg. + oranscinf/pti-o2imsdms:2.0.3), and to authenticate images that are + hosted by a private registry, follow the steps below: + 1. Create a docker-registry secret in ``oran-o2`` namespace. -2.4 Verify INF O2 service -~~~~~~~~~~~~~~~~~~~~~~~~~ + :: -.. code:: shell + export O2SERVICE_IMAGE_REG= - curl -k http(s)://:30205/o2ims_infrastructureInventory/v1/ + kubectl create secret docker-registry private-registry-key \ + --docker-server=${O2SERVICE_IMAGE_REG} --docker-username=${USERNAME} \ + --docker-password=${PASSWORD} -n oran-o2 + 2. Refer to the ``imagePullSecrets`` in override file. -2.5 INF O2 Service API Swagger -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + :: -- Swagger UI can be found with URL: http(s)://:30205 - + cat < o2service-override.yaml + imagePullSecrets: + - private-registry-key -3. Register INF O2 Service to SMO ---------------------------------- + o2ims: + serviceaccountname: admin-oran-o2 + images: + tags: + o2service: ${O2SERVICE_IMAGE_REG}/docker.io/oranscinf/pti-o2imsdms:2.0.3 + postgres: ${O2SERVICE_IMAGE_REG}/docker.io/library/postgres:9.6 + redis: ${O2SERVICE_IMAGE_REG}/docker.io/library/redis:alpine + pullPolicy: IfNotPresent + logginglevel: "DEBUG" -- assumed you have setup SMO O2 endpoint for registration -- INF O2 service will post the INF platform registration data to that SMO O2 endpoint + applicationconfig: ${APPLICATION_CONFIG} + servercrt: ${SERVER_CERT} + serverkey: ${SERVER_KEY} + smocacrt: ${SMO_CA_CERT} + EOF -.. code:: shell +7. Update the overrides for the oran-o2 application. - curl -X 'GET' \ - 'http(s)://:30205/provision/v1/smo-endpoint' \ - -H 'accept: application/json' + :: - curl -k -X 'POST' \ - 'http(s)://:30205/provision/v1/smo-endpoint' \ - -H 'accept: application/json' \ - -H 'Content-Type: application/json' \ - -d '{"endpoint": ""}' + ~(keystone_admin)]$ system helm-override-update oran-o2 oran-o2 oran-o2 --values o2service-override.yaml - # Confirm SMO endpoint provision status - curl -X 'GET' \ - 'http(s)://:30205/provision/v1/smo-endpoint' \ - -H 'accept: application/json' + # Check the overrides + ~(keystone_admin)]$ system helm-override-show oran-o2 oran-o2 oran-o2 +8. Run the **system application-apply** command to apply the updates. -References + :: + + ~(keystone_admin)]$ system application-apply oran-o2 + +9. Monitor the status using the command below. + + :: + + ~(keystone_admin)]$ watch -n 5 system application-list + + OR + + :: + + ~(keystone_admin)]$ watch kubectl get all -n oran-o2 + +3. Results ---------- -- `O-RAN-SC INF`_ +You have launched services in the above namespace. + +4. Postrequisites +----------------- + +You will need to integrate INF with an SMO application that performs +management of O-Cloud infrastructure and the deployment life cycle +management of O-RAN cloudified NFs. See the following API reference for +details: + +- `API O-RAN O2 + interface `__ + +INF O2 Service Uninstall +======================== + +.. _procedure-1: + +1. Procedure +------------ + +You can uninstall the O-RAN O2 application on INF from the command line. + +1. Uninstall the application. + + Remove O2 application related resources. + + :: + + ~(keystone_admin)]$ system application-remove oran-o2 + +2. Delete the application. + + Remove the uninstalled O2 application’s definition, including the + manifest and helm charts and helm chart overrides, from the system. + + :: + + ~(keystone_admin)]$ system application-delete oran-o2 + +.. _results-1: + +2. Results +---------- -.. _`O-RAN-SC INF`: https://docs.o-ran-sc.org/en/latest/projects.html#infrastructure-inf +You have uninstalled the O2 application from the system.