feat(build): add os-package native add-on template (#3425) #3471

Merged

mfreeman451 merged 1 commit from feat/addon-os-package-template into staging

2026-05-31 16:55:25 +00:00

mfreeman451 commented

2026-05-31 16:53:18 +00:00

Owner

What

delivery-models task 1.2 (os-package half) — the os-package add-on template. Companion to the per-arch pushed-artifact tarball (#3470); together they complete 1.2 within this change's scope.

An os-package add-on is delivered as a deb/rpm rather than a signed pushed-artifact tarball. This PR codifies that contract as an inert, copy-ready scaffold at build/packaging/addon-template/.

The contract (documented in the README)

Depends on serviceradar-agent (deb_depends / rpm_requires) — governed by the agent, meaningless without it.
Dormant on install. The package installs the binary, manifest, config, and systemd unit(s), but the post-install script never enables or starts anything. The agent activates the add-on (enables the unit / launches the on-host binary as a go-plugin) only when it is enabled for that agent in Edge Ops — so package presence never bypasses per-agent targeting/approval. Pre-remove stops + disables.
Standard install paths so the agent finds the binary via the manifest's exec.install_path + exec.binary; ships the self-describing addon.yaml so the on-host package is verifiable against the catalog.
Covers the systemd-timer (default, Bumblebee model), systemd-service, and agent-sidecar supervision variants.

build/packaging/addon-template/
  README.md            # contract + copy-ready packages.bzl & BUILD.bazel snippets
  addon.yaml           # delivery: os-package manifest
  config.schema.json   # source-side schema referenced by addon.yaml
  config/serviceradar-addon-example.json
  systemd/serviceradar-addon-example.service   # hardened Type=oneshot
  systemd/serviceradar-addon-example.timer
  scripts/postinstall.sh   # DORMANT: create user/dirs + daemon-reload, never enable
  scripts/preremove.sh     # stop + disable

Why inert (no BUILD.bazel / no PACKAGES entry)

release_targets.bzl's declare_release_artifacts() builds a _deb/_rpm for every PACKAGES key, so any real entry is auto-released. A "sample" os-package add-on would therefore ship as a real release artifact — not wanted. The scaffold deliberately has no BUILD.bazel and no PACKAGES entry, so it is neither built nor released and cannot break CI; it is the source you copy to package a real os-package add-on (netprobe, bumblebee). build/packaging/bumblebee-scan remains the shipping reference instance (os-package + systemd-timer).

Verification

sh -n clean on both scripts; config + config.schema.json parse as JSON; openspec validate add-native-addon-delivery-models --strict passes. tasks.md updated — 1.2 done within delivery-models (signing owned by build-signing, secret-blocked); only the breaking base-agent carve (1.1) remains.

🤖 Generated with Claude Code

## What delivery-models **task 1.2 (os-package half)** — the `os-package` add-on template. Companion to the per-arch pushed-artifact tarball (#3470); together they complete 1.2 within this change's scope. An `os-package` add-on is delivered as a deb/rpm rather than a signed pushed-artifact tarball. This PR codifies that contract as an inert, copy-ready scaffold at `build/packaging/addon-template/`. ## The contract (documented in the README) - **Depends on `serviceradar-agent`** (`deb_depends` / `rpm_requires`) — governed by the agent, meaningless without it. - **Dormant on install.** The package installs the binary, manifest, config, and systemd unit(s), but the post-install script **never enables or starts** anything. The agent activates the add-on (enables the unit / launches the on-host binary as a go-plugin) only when it is enabled for that agent in Edge Ops — so package presence never bypasses per-agent targeting/approval. Pre-remove stops + disables. - **Standard install paths** so the agent finds the binary via the manifest's `exec.install_path` + `exec.binary`; ships the self-describing `addon.yaml` so the on-host package is verifiable against the catalog. - Covers the **systemd-timer** (default, Bumblebee model), **systemd-service**, and **agent-sidecar** supervision variants. ## Contents ``` build/packaging/addon-template/ README.md # contract + copy-ready packages.bzl & BUILD.bazel snippets addon.yaml # delivery: os-package manifest config.schema.json # source-side schema referenced by addon.yaml config/serviceradar-addon-example.json systemd/serviceradar-addon-example.service # hardened Type=oneshot systemd/serviceradar-addon-example.timer scripts/postinstall.sh # DORMANT: create user/dirs + daemon-reload, never enable scripts/preremove.sh # stop + disable ``` ## Why inert (no BUILD.bazel / no PACKAGES entry) `release_targets.bzl`'s `declare_release_artifacts()` builds a `_deb`/`_rpm` for **every** `PACKAGES` key, so any real entry is auto-released. A "sample" os-package add-on would therefore ship as a real release artifact — not wanted. The scaffold deliberately has no `BUILD.bazel` and no `PACKAGES` entry, so it is neither built nor released and cannot break CI; it is the source you copy to package a real os-package add-on (netprobe, bumblebee). [`build/packaging/bumblebee-scan`](https://code.carverauto.dev/carverauto/serviceradar/src/branch/staging/build/packaging/bumblebee-scan) remains the shipping reference instance (os-package + systemd-timer). ## Verification `sh -n` clean on both scripts; config + config.schema.json parse as JSON; `openspec validate add-native-addon-delivery-models --strict` passes. tasks.md updated — 1.2 done within delivery-models (signing owned by build-signing, secret-blocked); only the breaking base-agent carve (1.1) remains. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Rows
Columns