starlingx/docs
Code Issues Proposed changes

Update vRAN documentation

Browse Source 
- 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 <elaine.fonaro@windriver.com>
Change-Id: I2a3adc495bb5ebacea32bbe324be5cf6c76f3dce
This commit is contained in:
Elaine Fonaro 2022-12-15 17:39:45 -03:00
parent 2f15495466
commit 1a76203b6f
1 changed files with 120 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

205
doc/source/usertasks/kubernetes/vran-tools-2c3ee49f4b0b.rst
View File

@ -4,63 +4,84 @@
vRAN Tools vRAN Tools
========== ==========
The following open-source |vRAN| tools are delivered in the following container The |vRAN| tools consist of the following open-source packages that are delivered
image, ``docker.io/starlingx/stx-debian-tools-dev:stx.8.0-v1.0.3``: 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/<package name>.
- ``dmidecode`` - `dmidecode
<https://packages.debian.org/bullseye/dmidecode>`__
- ``net-tools`` - `net-tools
<https://packages.debian.org/bullseye/net-tools>`__:
includes ``arp``, ``ifconfig``, ``netstat``, ``nameif``, ``route``, ``mii-tool``, ``iptunnel``, ``ipmaddr``, etc.
- ``iproute`` - `iproute2
<https://packages.debian.org/bullseye/iproute2>`__:
includes the network tools ``arpd``, ``ip``, ``nstat``, ``ss``, and others.
- ``ethtool`` - `ethtool
<https://packages.debian.org/bullseye/ethtool>`__
- ``tcpdump`` - `tcpdump
<https://packages.debian.org/bullseye/tcpdump>`__
- ``turbostat`` - `linux-cpupower
<https://packages.debian.org/bullseye/linux-cpupower>`__
- OPAE Tools (`Open Programmable Acceleration Engine - `trace-cmd
<https://opae.github.io/latest/>`__, ``fpgainfo``, ``fpgabist``, etc.) <https://packages.debian.org/bullseye/trace-cmd>`__
- ACPICA Tools (``acpidump``, ``acpixtract``, etc.) - `OPAE Tools
<https://opae.github.io/1.3.0/>`__:
includes ``fpgainfo``, ``fpgabist``, among other ``Field Programmable Gate Array`` tools.
- PCM Tools (`https://github.com/opcm/pcm <https://github.com/opcm/pcm>`__, - `ACPICA Tools
pcm, pcm-core, etc.) <https://packages.debian.org/bullseye/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 - `PCM Tools
a Kubernetes pod and ``exec`` into a shell in the container in order to execute <https://github.com/opcm/pcm>`__: includes ``pcm``, and other ``Processor Counter Monitor`` tools.
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. 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 The suggested yaml manifest to launch the ``stx-debian-tools-dev`` container is
as follows: as follows:
.. code-block:: none .. code-block:: none
# Creating the Kubernetes Deployment
cat << EOF > stx-debian-tools-dev.yaml
apiVersion: apps/v1 apiVersion: apps/v1
kind: Deployment kind: Deployment
metadata: metadata:
name: stx-debian-tools name: stx-debian-tools-dev
spec: spec:
replicas: 1 replicas: 1
selector: selector:
matchLabels: matchLabels:
app: stx-debian-tools app: stx-debian-tools-dev
template: template:
metadata: metadata:
labels: labels:
app: stx-debian-tools app: stx-debian-tools-dev
spec: spec:
containers: containers:
- name: stx-debian-tools - name: stx-debian-tools-dev
image: docker.io/starlingx/stx-debian-tools-dev:stx.8.0-v1.0.3 image: docker.io/starlingx/stx-debian-tools-dev:stx.8.0-v1.0.3
imagePullPolicy: Always imagePullPolicy: Always
stdin: true stdin: true
tty: true tty: true
securityContext: 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: 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 runAsUser: 0 # run as root
volumeMounts: volumeMounts:
- mountPath: /tmp - mountPath: /tmp
@ -70,79 +91,106 @@ as follows:
hostPath: hostPath:
path: /tmp path: /tmp
type: Directory type: Directory
hostIPC: true # Use the host's network namespace https://www.man7.org/linux/man-pages/man7/network_namespaces.7.html # Use host ipc ns [https://man7.org/linux/man-pages/man7/ipc_namespaces.7.html]
hostNetwork: true # Use the host's network namespace https://www.man7.org/linux/man-pages/man7/network_namespaces.7.html hostIPC: true
hostPID: true # Use the host's pid namespace https://man7.org/linux/man-pages/man7/pid_namespaces.7.html # 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: For example:
.. code-block:: none .. code-block:: none
# Create pod # Create pod
~(keystone_admin)] $ kubectl apply -f stx-debian-tools.yaml $ kubectl apply -f stx-debian-tools-dev.yaml
# Get the running pods # Get the running pods
~(keystone_admin)] $ kubectl get pods $ kubectl get pods
NAME READY STATUS RESTARTS AGE 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: Then ``exec`` into shell in container:
.. code-block:: none .. code-block:: none
# Attach to pod $ STX_DEBIAN_TOOLS_DEV=$(kubectl get pods | grep '^stx-debian-tools-dev' | awk '/Running/ {print $1}')
~(keystone_admin)] $ kubectl exec -it stx-debian-tools -- bash
[root@controller-0 /]# $ echo $STX_DEBIAN_TOOLS_DEV
[root@controller-0 /]# stx-debian-tools-dev-xxxx-xxxx
$ kubectl exec -it $STX_DEBIAN_TOOLS_DEV -- bash
------------------------------------------- -------------------------------------------
Build, deploy and run non-open-source tools Build, deploy and run non-open-source tools
------------------------------------------- -------------------------------------------
The ``docker.io/starlingx/stx-debian-tools-dev:stx.8.0-v1.0.3`` container image The ``starlingx/stx-debian-tools-dev:stx.8.0-v1.0.3`` container image also
also contains the |prod| development tools. contains development tools.
Using this container as your base image, this enables the |prod| user to build Using this container image as a Dockerfile base image enables |prod| users to
a custom container for building and installing of custom or non-opensource build a custom container image for building and installing custom or non-opensource
tools (specifically ones requiring |prod| load-specific kernel headers) on a tools on |prod| target.
|prod| target, and then using those tools on |prod|.
For example this can be used for running the non-opensource Intel tool, For example, this can be used for running the non-opensource Intel Quartzville
Quartzville. tools. The necessary (open-source) Intel iqvlinux driver is already pre-installed
in |prod| for Debian. Quartzville is available at:
Quartzville is available at
`https://designintools.intel.com/product_p/stlgrn108.htm `https://designintools.intel.com/product_p/stlgrn108.htm
<https://designintools.intel.com/product_p/stlgrn108.htm>`__, contact an Intel <https://designintools.intel.com/product_p/stlgrn108.htm>`__. Contact Intel if
representative for access. you need access.
You can create and build a Docker image with Quartzville tools as follows: You can create and build a container to run Quartzville tools on Kubernetes as
follows:
Running on Kubernetes:
.. code-block:: none .. code-block:: none
# Creating the Dockerfile # Creating the Dockerfile
cat << EOF > 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 USER root
WORKDIR /root WORKDIR /root
ADD ./348742_Quartzville_Tools_637987.zip /root COPY 348742_Quartzville_Tools_637987.zip /root/quartzville.zip
RUN yum install -y centos-release-scl
RUN yum install -y devtoolset-9 # Install Quartzville Tools
RUN yum install -y kernel-devel # ATTENTION: There is a known issue in celo64e that crashes the host.
RUN unzip /root/348742_Quartzville_Tools_637987.zip # The issue might affect nvmupdate64e as well.
RUN rm /root/348742_Quartzville_Tools_637987.zip # Only eeupdate64e and lanconf64e are supported in this release.
RUN chmod +x TOOLS/Linux_x64/OEM_Mfg/install RUN set -ex && \
RUN chmod +x TOOLS/Linux_x64/SVTools/lanconf64e unzip quartzville.zip \
CMD /bin/bash -c "cd TOOLS/Linux_x64/OEM_Mfg/ && scl enable devtoolset-9 ./install && sleep infinity" "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 EOF
# Building the image with Quartzville # Building the container image with Quartzville
sudo docker build -t stx-debian-tools-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 # Test container (optional)
cat << EOF > stx-debian-tools-quartzville.yml 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 apiVersion: v1
kind: Pod kind: Pod
metadata: metadata:
@ -161,7 +209,7 @@ Running on Kubernetes:
runAsUser: 0 runAsUser: 0
capabilities: capabilities:
add: ["NET_ADMIN", "SYS_ADMIN"] 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 - name: usrsrc
mountPath: /usr/src/ mountPath: /usr/src/
- name: libmodules - name: libmodules
@ -178,37 +226,24 @@ Running on Kubernetes:
EOF EOF
# Create secret for local registry # Create secret for local registry
kubectl create secret docker-registry regcred --docker-server=registry.local:9001 --docker-username=admin --docker-password=<admin-keystone-user-password> kubectl create secret docker-registry regcred --docker-server=registry.local:9001 \
--docker-username=admin --docker-password=<admin-keystone-user-password>
# Log in local registry # Log in local registry
sudo docker login -u admin -p <admin-keystone-user-password> registry.local:9001 sudo docker login registry.local:9001 -u admin -p <admin-keystone-user-password>
# Tagging for local registry # 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 # Push image to local registry
sudo docker push registry.local:9001/public/stx-debian-tools-quartzville:latest sudo docker push registry.local:9001/public/stx-debian-tools-quartzville:latest
# Create pod # 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 # Attach to pod
kubectl exec -it stx-debian-tools-quartzville -- scl enable devtoolset-9 /bin/bash kubectl exec -it stx-debian-tools-quartzville -- /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