Workload library import — a shared Workload body via `$import`
A single stateless web service whose Recipe synthesizes its Kubernetes Workload
from a shared library entry instead of an inline body. This is the third
authoring mode of spec.workload on a Recipe:
- Mode 1 (inline): a Go-template Workload written directly in the Recipe.
- Mode 2 (file import):
$import: ./relative/path.yaml— a local file. - Mode 3 (library import):
$import: <Library>#/workloads/<Entry>— aWorkloadLibraryentry referenced by bare-name identity.
The web-service Recipe here uses Mode 3:
spec: capability: helm implements: example/compute/web-service workload: $import: BaseWorkloads#/workloads/StatelessServiceWrite the reference as one unbroken token: no space and no line break anywhere in
it, from the library name through the fragment. A reference carrying whitespace is
refused rather than trimmed, and the build halts — see
errors/fatal-halts.md “A reference to a library
entry carries whitespace”.
BaseWorkloads is a WorkloadLibrary published in the hub catalog
(workloadlibrary/base-workloads). Its StatelessService entry is a Go template
evaluated in this Recipe’s render context, so .values.image (from the
Component/Aggregate) and .infra.* (replicas, port, compute — from the Release)
flow into it exactly as they would an inline body. Factoring the Workload into a
library changes nothing about what deploys: the rendered output is byte-identical
to the equivalent inline Workload.
The library’s version is supplied by the per-Release lockfile — no registry host
appears in the reference. On aggrega pull, BaseWorkloads is pinned in the
lockfile’s workload_libraries section; on aggrega build, the pinned library is
resolved and its entry rendered.
Scaffold the example
You can build this example with the commands below, or have your AI assistant build it for you.
Write the example into a new folder named after it:
aggrega scaffold --example workload-library-importIt then prints the commands to run next. The first changes into the new folder:
cd workload-library-importBuild
aggrega pull --release release.yaml # pins BaseWorkloads in release.lockaggrega build --release release.yamlThe catalog resolves from the hub registry named in .aggrega-config.yaml
(which supplies BaseWorkloads and the helm provider) plus this example’s local
catalog/ (the web-service Component and Recipe). Manifests land under
dist/app/helm/ — the boundary’s directory: followed by the provider
capability.
With an AI assistant
An AI assistant set up with Aggrega’s tools can do the same: paste this prompt into it.
Use the Aggrega tools only, and create no folder yourself. If the Workspace folder holds no `workload-library-import` folder yet, call the `scaffold` tool once with `example` set to `workload-library-import` and no `dir`: it writes the example into a new `workload-library-import` folder. Then call the `build` tool with `workspace_root` set to `workload-library-import`, `release` set to `release.yaml`, `auto_pull` set to true and `write` set to true. Tell me which files the build wrote; they are under `workload-library-import/dist/`.Verifying the byte-identity claim
Replace the Recipe’s workload: { $import: … } with a workload: | block
holding the StatelessService body verbatim, rebuild, and diff the two dist/
trees. They match exactly: the library reference resolves to the same template
text, evaluated in the same render context, so the import is a factoring of the
authoring surface with no effect on the rendered bytes.