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 Python entry points under src/dev/python3/ and C entry points from src/dev/c/CMakeLists.txt. The training labs live under labs/, so copy your finished xApp into the SDK's development tree 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, e.g.:

src/dev/python3/ran-slicing.py

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

C xApp

Place the source under src/dev/c/ and add it to LIST_XAPP so it is built and discovered:

src/dev/c/CMakeLists.txt

set(LIST_XAPP
    ran-slicing
)

Then compile it so the binary exists under build/src/dev/c/:

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

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

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'...

Sanity-check locally first

Before pushing, you can run the image transiently to confirm it starts and finds its dependencies:

brc cdk image run registry.<cluster>.local:5000/telco-fabric/<org>/xapps:latest
# or open a shell inside it (changes discarded on exit):
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 -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

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.