Versions and Compatibility
The Version Axes
- Component versions. Every image versions, builds and ships on its own cadence, in the repository where its code lives. A CU-IP fix bumps CU-IP and publishes a CU-IP image; it does not require a Racora release.
- The cluster layer. The k3s platform installs an upstream k3s release, never a
Racora build. Which one is a curated pin (
cluster.k3s.versioninversions.yaml), bumped deliberately, never auto-resolved. - The Racora release.
vX.Y.Zis a curation: one known-good version of every component plus one k3s release, the way a Linux distribution release pins package versions.
versions.yaml names every pin: the k3s release, each component image, each upstream
image (<YYYYMMDD>_<sha8>, the nightly of a project that publishes no versioned tags). A
release ships those pins as they are on the tagged commit, which is what every change
before it was checked against; the release's chart-values.yaml records them. A new
image enters through a change to its pin, whose pipeline installs it in every
integration suite before it merges; a gNB built from an OCUDU source is produced by
Racora's own intake run first (Release Process, The gNB
Contract).
An upstream image can also carry a change. When something Racora needs is submitted to
the upstream project but not yet merged, the release builds that image from the
submitted change itself, names the merge request in versions.yaml, and versions it
<YYYYMMDD>_<sha8>-cns after the carried commit. The carry is removed the day the
change merges, and the pin goes back to the project's own build.
The Image Set
| Group | Built in | Examples |
|---|---|---|
| external | their own repositories | gnb and open5gs (the gNB repository), cuip |
| internal | the racora repository | racora-controller, racora-core-controller, rann-p-forwarder, ettus-device-plugin |
| upstream | an upstream OCUDU project's published build, mirrored unmodified, or Racora's build of a change it has submitted there while the change is not yet merged | o1-adapter (the OCUDU O1 adapter, an O-RU's M-plane client) |
| third-party | upstream, mirrored unmodified | ClickHouse, Tempo, the OpenTelemetry collector, Grafana, the NVIDIA device plugin |
| cluster | the upstream k3s release, mirrored | the k3s binary and its checksum |
All are independently versioned; "internal" only says where the code lives.
What a Release Fixes
A published release is an immutable, self-contained snapshot. The chart carries its
image pins in its defaults (global.components, one key per component), the images sit
at immutable tags in one registry namespace
(registry.gitlab.com/cognitive-network-solutions/racora/*, re-rootable with
global.systemDefaultRegistry), the k3s binary is a fixed upstream release, and the
installer that runs on a host is the one packaged with that release: for a release
install, the front door served at get.racora.io only resolves the version and runs the
release's own installer package. On a host Racora installed, a provision-rf or uninstall run uses the persisted copy of
that release's installer (/opt/racora/installer); on any other host it follows
INSTALL_RACORA_VERSION when it is set and the repository's main branch otherwise. Any
release installs its own set, for as long as its images and package files
exist. Published releases start at v0.8.0; the assets a release publishes are on
Release Process, and every release with its pins is on
Release History.
What Upgrades with What
A RAN platform stacks layers that version independently. Naming the layer you mean is what makes an upgrade predictable (Upgrade Racora):
| Layer | What it is | Touches | Mechanism |
|---|---|---|---|
| the cluster platform | k3s: the upstream binary Racora installed; otherwise your distribution | every node's kubelet | k3s: re-run the installer on the control node, and on a worker only when the k3s pin moved; otherwise your platform's procedure |
| the release | the chart with its pinned image set | the pods whose spec changed | k3s: re-run the installer on the control node; otherwise helm upgrade |
| one component image | for example a new gNB or CU-IP between releases | that component's workloads (the gNB: CU-CP, CU-UP and every DU) | global.components.<name> in the HelmChartConfig, or in your values file on a cluster you run (Update a Component) |
| the CRD schemas | the NRCell and Subscriber APIs | the whole cluster | k3s: re-applied out-of-band by the installer; otherwise inside the release |
| the host layer | the installer, the core provider's host units, provisioning, node labels | each affected node | re-run the installer on that node, or re-provision |
| stateful data | the subscriber database, telemetry | where it is stored | the claim survives; telemetry on emptyDir does not |
A release bump that exists because one image changed touches only the nodes that run it; a CRD change is applied by the installer or the release, never by hand.
Immutability and Retention
- A published tag is never overwritten.
gnb:v0.4.6always means the same image; a change gets a new tag. Pin real version tags, never a floatinglatest. - Old release images are kept. As long as a release's images and package files are in the registries, that release installs.
Updating one component between releases is a task: Update a Component.