Lab 1: Packaging an xApp into a CompositionModel

In xApp Training — Lab 5 you built a KPM+RC xApp for RAN slicing and ran it on bare-metal against a Near-RT RIC. In this lab you take that exact xApp and use the CDK to package it into a container image and a CompositionModel, published to the cluster-local registry — the first half of shipping it as a managed Element.

Prerequisites

• You have completed xApp Training — Lab 5 and have a working RAN-slicing xApp (lab5.py or lab5.c).
• You are on the control-plane node of your cluster (see the Overview), with a brc that includes the cdk command (brc cdk --help).
• You have logged in once with brc login <username> so the bubbleran-hub secret exists.

danger

Make sure your composition models are up to date before starting — see the update-models steps.

Step 1 — Place your xApp where the CDK can find it

The CDK discovers entry points in the SDK's dev and usr trees. The training labs live under labs/, which the CDK does not scan, so copy your finished xApp into the tree that matches the API it uses and give it a hyphenated name.

Python xApp

cd /path/to/xapp_sdk
cp labs/lab5.py src/dev/python3/ran-slicing.py

The entry point must initialise the SDK. Lab 5 uses the usr SDK, so:

src/dev/python3/ran-slicing.py

import xapp_usr_sdk as xapp
# ... your KPM subscription + RC slicing control loop ...
xapp.init(sys.argv)

Either SDK module works from either Python tree, and the CDK detects the init call whatever you alias the module to.

C xApp

For C the tree decides which SDK library is linked, so it has to match your code. Lab 5 calls init_xapp_sdk() and node_data_xapp_sdk(), which live in the usr SDK, so the source belongs under src/usr/c/. Add it to that tree's LIST_XAPP:

src/usr/c/CMakeLists.txt

set(LIST_XAPP
    ran-slicing
)

Then compile from the SDK root, so the binary lands under build/src/usr/c/:

cd /path/to/xapp_sdk && cmake -S . -B build && cmake --build build -j

The C mode gets a usr- prefix

An xApp in a usr/ tree becomes a usr-prefixed mode, so src/usr/c/ran-slicing.c is the mode usr-ran-slicing. Use that name wherever this lab and Lab 2 say ran-slicing. A dev-API xApp under src/dev/c/ keeps the plain name.

Step 2 — Build the image

From the xapp_sdk root, build the xApp image. The CDK layers your xApp, its shared libraries and any auto-detected pip dependencies on top of the CDK base image:

cd /path/to/xapp_sdk
brc cdk image build --xapp ran-slicing

INFO Using default image: registry.<cluster>.local:5000/telco-fabric/<org>/xapps:latest
INFO Found 1 Python xApp(s): ran-slicing
INFO Detected pip packages: ...
INFO Running docker build, tagging as 'registry.<cluster>.local:5000/telco-fabric/<org>/xapps:latest'...

--xapp keeps your image and model to just your xApp

Without it the CDK packages every xApp in the checkout, which in a fresh SDK means its two dozen examples as well. --xapp takes a mode name or a source name, and can be repeated or comma-separated (--xapp ran-slicing,usr-ran-slicing). Omit it once if you want to see the full list of what your tree contains.

Sanity-check locally first

Before pushing, start your xApp inside the image the same way the platform will, by handing image run the launcher and your mode name:

brc cdk image run registry.<cluster>.local:5000/telco-fabric/<org>/xapps:latest \
  -- /opt/hydra/run python-xapp ran-slicing
# a C xApp:  -- /opt/hydra/run c-xapp usr-ran-slicing

It will reach the SDK banner and then stop for want of a config, which on a cluster the manager supplies. That is enough to prove the entry point is in the image under the right name and that its libraries resolve.

brc cdk image run with no command only starts the image's API server, and brc cdk image shell gives you a plain shell without the SDK on PYTHONPATH, so neither exercises the xApp. Use them to poke around, not to validate.

brc cdk image shell registry.<cluster>.local:5000/telco-fabric/<org>/xapps:latest

Fix something interactively with image patch

If the image is missing a dependency or needs a quick tweak, image patch drops you into a shell inside the image, there you may install or change whatever you need, then exit, and the CDK commits the result into a new image:

brc cdk image patch registry.<cluster>.local:5000/telco-fabric/<org>/xapps:latest
# inside the shell, e.g.:  apt-get update && apt-get install -y <pkg>
#                          pip3 install <pkg>
# ...then exit the shell

On exit it prints the filesystem diff and writes <image>-patched (use --target to choose the tag, --push to push it straight away).

Step 3 — Push the image to the cluster-local registry

brc cdk image push

INFO Pushing registry.<cluster>.local:5000/telco-fabric/<org>/xapps:latest...
latest: digest: sha256:... size: ...
INFO Pushed registry.<cluster>.local:5000/telco-fabric/<org>/xapps:latest

Each org keeps a single :latest tag, so a push overwrites the previous image. You can confirm it landed:

oras repo tags registry.<cluster>.local:5000/telco-fabric/<org>/xapps
# latest

Step 4 — Generate and install the CompositionModel

You can first inspect what will be generated, without deploying anything:

brc cdk model build --xapp ran-slicing -o composition-model.yaml

This renders a CompositionModel with one deployment-mode per xApp (here ran-slicing), wiring the xapp workload to the image you just pushed, exposing the e42ap port (36422/sctp), and mounting an Athena manager sidecar that renders the runtime config and connects the xApp to the RIC.

If you finish inspecting it, you can install it. This packages the model as a Helm chart, pushes it to the cluster-local registry, and creates the CompositionModel in the cluster:

brc cdk model install --xapp ran-slicing

INFO Found 1 Python xApp(s): ran-slicing
INFO Packaged chart: <org>-0.0.1.tgz
INFO Pushed chart to oci://registry.<cluster>.local:5000/telco-fabric/models/<org>:0.0.1
INFO CompositionModel "<org>" deployed in namespace trirematics (version 0.0.1)

Step 5 — Verify

brc list model
# or:
kubectl -n trirematics get compositionmodels

You should see a model named after your org/cluster. It now contains a ran-slicing deployment-mode that references your pushed image:

NAME    PROVIDER    VERSION   LICENSE       AGE
<org>   BubbleRAN   v1.0.0    Proprietary   12s

Model name & mode

With model install, the CompositionModel is named after your org (the kubeconfig cluster), and each xApp is a deployment-mode inside it. So the model reference you will use in the next lab is <org>/ran-slicing. (Use brc cdk model build -N <name> if you want to render it under a custom name.)

Outcome

By the end of this lab you have succesfully packaged:

• An xApp image in the cluster-local registry: registry.<cluster>.local:5000/telco-fabric/<org>/xapps:latest.
• A CompositionModel <org> with a ran-slicing mode, ready to be referenced from a Network.

Continue to Lab 2 to deploy it as a managed Element.