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
==========
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/<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
<https://opae.github.io/latest/>`__, ``fpgainfo``, ``fpgabist``, etc.)
- `trace-cmd
<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>`__,
pcm, pcm-core, etc.)
- `ACPICA Tools
<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
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
<https://github.com/opcm/pcm>`__: 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
<https://designintools.intel.com/product_p/stlgrn108.htm>`__, contact an Intel
representative for access.
<https://designintools.intel.com/product_p/stlgrn108.htm>`__. 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=<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
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
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