From 1a76203b6fcdb29849fbb3a30da450cd988b3cd8 Mon Sep 17 00:00:00 2001 From: Elaine Fonaro Date: Thu, 15 Dec 2022 17:39:45 -0300 Subject: [PATCH] Update vRAN documentation - Fixed links and sentences re-wording. - Fixed more instructions. - Fixed the ADD instruction. - Editorial edits. - Fixed and added some instructions. - Added information to the vRAN Tools list. - Updated stx-debian-tools-dev container information. - Updated the docker file creation information. Story: 2010138 Task: 47046 Signed-off-by: Elaine Fonaro Change-Id: I2a3adc495bb5ebacea32bbe324be5cf6c76f3dce --- .../kubernetes/vran-tools-2c3ee49f4b0b.rst | 205 ++++++++++-------- 1 file changed, 120 insertions(+), 85 deletions(-) diff --git a/doc/source/usertasks/kubernetes/vran-tools-2c3ee49f4b0b.rst b/doc/source/usertasks/kubernetes/vran-tools-2c3ee49f4b0b.rst index 6511f48f1..555ec8cc4 100644 --- a/doc/source/usertasks/kubernetes/vran-tools-2c3ee49f4b0b.rst +++ b/doc/source/usertasks/kubernetes/vran-tools-2c3ee49f4b0b.rst @@ -4,63 +4,84 @@ vRAN Tools ========== -The following open-source |vRAN| tools are delivered in the following container -image, ``docker.io/starlingx/stx-debian-tools-dev:stx.8.0-v1.0.3``: +The |vRAN| tools consist of the following open-source packages that are delivered +in the container image ``starlingx/stx-debian-tools-dev:stx.8.0-v1.0.3``. For more +detailed information on the tools packages, click the hyperlink on the +package names, which will lead you to the Debian Bullseye package information +web page https://packages.debian.org/bullseye/. -- ``dmidecode`` +- `dmidecode + `__ -- ``net-tools`` +- `net-tools + `__: + includes ``arp``, ``ifconfig``, ``netstat``, ``nameif``, ``route``, ``mii-tool``, ``iptunnel``, ``ipmaddr``, etc. -- ``iproute`` +- `iproute2 + `__: + includes the network tools ``arpd``, ``ip``, ``nstat``, ``ss``, and others. -- ``ethtool`` +- `ethtool + `__ -- ``tcpdump`` +- `tcpdump + `__ -- ``turbostat`` +- `linux-cpupower + `__ -- OPAE Tools (`Open Programmable Acceleration Engine - `__, ``fpgainfo``, ``fpgabist``, etc.) +- `trace-cmd + `__ -- ACPICA Tools (``acpidump``, ``acpixtract``, etc.) +- `OPAE Tools + `__: + includes ``fpgainfo``, ``fpgabist``, among other ``Field Programmable Gate Array`` tools. -- PCM Tools (`https://github.com/opcm/pcm `__, - pcm, pcm-core, etc.) +- `ACPICA Tools + `__: + includes ``acpidump``, ``acpixtract``, and other ``ACPI Component Architecture`` tools. -To use them on the |prod| Platform, you must launch this container image in -a Kubernetes pod and ``exec`` into a shell in the container in order to execute -the commands. The Kubernetes pod must run in a privileged and host context, -such that the above tools provide information on resources in the host context. +- `PCM Tools + `__: includes ``pcm``, and other ``Processor Counter Monitor`` tools. + +You can launch this container image in a Kubernetes pod and ``exec`` into a shell +in the container in order to execute the commands. The Kubernetes pod must run +in a privileged and host context, such that the above tools provide information +on resources in the host context. The suggested yaml manifest to launch the ``stx-debian-tools-dev`` container is as follows: .. code-block:: none + # Creating the Kubernetes Deployment + cat << EOF > stx-debian-tools-dev.yaml apiVersion: apps/v1 kind: Deployment metadata: - name: stx-debian-tools + name: stx-debian-tools-dev spec: replicas: 1 selector: matchLabels: - app: stx-debian-tools + app: stx-debian-tools-dev template: metadata: labels: - app: stx-debian-tools + app: stx-debian-tools-dev spec: containers: - - name: stx-debian-tools + - name: stx-debian-tools-dev image: docker.io/starlingx/stx-debian-tools-dev:stx.8.0-v1.0.3 imagePullPolicy: Always stdin: true tty: true securityContext: - privileged: true # processes in privileged containers are essentially equivalent to root on the host + # processes in privileged containers are essentially equivalent to root on the host + privileged: true capabilities: - add: ["NET_ADMIN", "SYS_ADMIN"] # add the capabilities you need https://man7.org/linux/man-pages/man7/capabilities.7.html + # add capabilities https://man7.org/linux/man-pages/man7/capabilities.7.html + add: ["NET_ADMIN", "SYS_ADMIN"] runAsUser: 0 # run as root volumeMounts: - mountPath: /tmp @@ -70,79 +91,106 @@ as follows: hostPath: path: /tmp type: Directory - hostIPC: true # Use the host's network namespace https://www.man7.org/linux/man-pages/man7/network_namespaces.7.html - hostNetwork: true # Use the host's network namespace https://www.man7.org/linux/man-pages/man7/network_namespaces.7.html - hostPID: true # Use the host's pid namespace https://man7.org/linux/man-pages/man7/pid_namespaces.7.html + # Use host ipc ns [https://man7.org/linux/man-pages/man7/ipc_namespaces.7.html] + hostIPC: true + # Use host network ns [https://www.man7.org/linux/man-pages/man7/network_namespaces.7.html] + hostNetwork: true + # Use host pid ns [https://man7.org/linux/man-pages/man7/pid_namespaces.7.html] + hostPID: true + EOF For example: .. code-block:: none # Create pod - ~(keystone_admin)] $ kubectl apply -f stx-debian-tools.yaml + $ kubectl apply -f stx-debian-tools-dev.yaml # Get the running pods - ~(keystone_admin)] $ kubectl get pods + $ kubectl get pods NAME READY STATUS RESTARTS AGE - stx-debian-tools 1/1 Running 0 6s + stx-debian-tools-dev-xxxx-xxxx 1/1 Running 0 6s Then ``exec`` into shell in container: .. code-block:: none - # Attach to pod - ~(keystone_admin)] $ kubectl exec -it stx-debian-tools -- bash - [root@controller-0 /]# - [root@controller-0 /]# + $ STX_DEBIAN_TOOLS_DEV=$(kubectl get pods | grep '^stx-debian-tools-dev' | awk '/Running/ {print $1}') + + $ echo $STX_DEBIAN_TOOLS_DEV + stx-debian-tools-dev-xxxx-xxxx + + $ kubectl exec -it $STX_DEBIAN_TOOLS_DEV -- bash ------------------------------------------- Build, deploy and run non-open-source tools ------------------------------------------- -The ``docker.io/starlingx/stx-debian-tools-dev:stx.8.0-v1.0.3`` container image -also contains the |prod| development tools. +The ``starlingx/stx-debian-tools-dev:stx.8.0-v1.0.3`` container image also +contains development tools. -Using this container as your base image, this enables the |prod| user to build -a custom container for building and installing of custom or non-opensource -tools (specifically ones requiring |prod| load-specific kernel headers) on a -|prod| target, and then using those tools on |prod|. +Using this container image as a Dockerfile base image enables |prod| users to +build a custom container image for building and installing custom or non-opensource +tools on |prod| target. -For example this can be used for running the non-opensource Intel tool, -Quartzville. - -Quartzville is available at +For example, this can be used for running the non-opensource Intel Quartzville +tools. The necessary (open-source) Intel iqvlinux driver is already pre-installed +in |prod| for Debian. Quartzville is available at: `https://designintools.intel.com/product_p/stlgrn108.htm -`__, contact an Intel -representative for access. +`__. Contact Intel if +you need access. -You can create and build a Docker image with Quartzville tools as follows: - -Running on Kubernetes: +You can create and build a container to run Quartzville tools on Kubernetes as +follows: .. code-block:: none # Creating the Dockerfile cat << EOF > Dockerfile - FROM docker.io/starlingx/stx-debian-tools-dev:stx.7.0-v1.0.1 + FROM docker.io/starlingx/stx-debian-tools-dev:stx.8.0-v1.0.3 USER root WORKDIR /root - ADD ./348742_Quartzville_Tools_637987.zip /root - RUN yum install -y centos-release-scl - RUN yum install -y devtoolset-9 - RUN yum install -y kernel-devel - RUN unzip /root/348742_Quartzville_Tools_637987.zip - RUN rm /root/348742_Quartzville_Tools_637987.zip - RUN chmod +x TOOLS/Linux_x64/OEM_Mfg/install - RUN chmod +x TOOLS/Linux_x64/SVTools/lanconf64e - CMD /bin/bash -c "cd TOOLS/Linux_x64/OEM_Mfg/ && scl enable devtoolset-9 ./install && sleep infinity" + COPY 348742_Quartzville_Tools_637987.zip /root/quartzville.zip + + # Install Quartzville Tools + # ATTENTION: There is a known issue in celo64e that crashes the host. + # The issue might affect nvmupdate64e as well. + # Only eeupdate64e and lanconf64e are supported in this release. + RUN set -ex && \ + unzip quartzville.zip \ + "TOOLS/Linux_x64/*" \ + "TOOLS/DOCS/*" \ + "TOOLS/*.txt" \ + "TOOLS/*.pdf" \ + -d quartzville && \ + cd quartzville/TOOLS/Linux_x64/OEM_Mfg && \ + rm -f celo64e nvmupdate64e && \ + install -t /usr/local/bin/ \ + eeupdate64e \ + ../SVTools/lanconf64e && \ + cd - && \ + rm quartzville.zip + + # Enable the ll alias for convenience (optional) + RUN set -ex && \ + sed -i 's/# alias ll=/alias ll=/' ~/.bashrc + + CMD echo 'Press Ctrl-C to exit'; \ + sleep infinity EOF - # Building the image with Quartzville + # Building the container image with Quartzville sudo docker build -t stx-debian-tools-quartzville . - # Create the yml for Kubernetes; note the additional mounting of the host kernel headers from the host - cat << EOF > stx-debian-tools-quartzville.yml + # Test container (optional) + sudo docker run -it --rm --privileged \ + -v /usr/src/:/usr/src \ + -v /lib/modules:/lib/modules \ + --name stx-debian-tools-quartzville stx-debian-tools-quartzville + + # Create kubernetes POD + cat << EOF > stx-debian-tools-quartzville.yaml apiVersion: v1 kind: Pod metadata: @@ -161,7 +209,7 @@ Running on Kubernetes: runAsUser: 0 capabilities: add: ["NET_ADMIN", "SYS_ADMIN"] - volumeMounts: # Mount host kernel headers in container + volumeMounts: # Mount the host linux headers directory as a volume in the container - name: usrsrc mountPath: /usr/src/ - name: libmodules @@ -178,37 +226,24 @@ Running on Kubernetes: EOF # Create secret for local registry - kubectl create secret docker-registry regcred --docker-server=registry.local:9001 --docker-username=admin --docker-password= + kubectl create secret docker-registry regcred --docker-server=registry.local:9001 \ + --docker-username=admin --docker-password= # Log in local registry - sudo docker login -u admin -p registry.local:9001 + sudo docker login registry.local:9001 -u admin -p # Tagging for local registry - sudo docker tag stx-debian-tools-quartzville:latest registry.local:9001/public/stx-debian-tools-quartzville:latest + sudo docker tag stx-debian-tools-quartzville:latest \ + registry.local:9001/public/stx-debian-tools-quartzville:latest # Push image to local registry sudo docker push registry.local:9001/public/stx-debian-tools-quartzville:latest # Create pod - kubectl apply -f stx-debian-tools-quartzville.yml + kubectl apply -f stx-debian-tools-quartzville.yaml + + # Check POD status + kubectl -n default get pods # Attach to pod - kubectl exec -it stx-debian-tools-quartzville -- scl enable devtoolset-9 /bin/bash - # < execute testing with quartzville tool > - -------- -Cleanup -------- - -After finishing executing commands on the container just run the following -commands to uninstall Quartzville driver: - -.. code-block:: none - - # Inside the container - cd TOOLS/Linux_x64/OEM_Mfg/ - ./install uninstall - exit - - # Delete the quartzville pod - kubectl delete pods stx-debian-tools-quartzville + kubectl exec -it stx-debian-tools-quartzville -- /bin/bash