This tutorial creates two small YAML files and uses Ref Bundle to collect them into one deployable file.
You need Python 3.10 or newer and access to the package registry that provides Ref Bundle. Install the package in a virtual environment:
python -m pip install ref-bundle
ref-bundle --helpCreate components/runtimes.yaml:
python:
image: python:3.13-slim
replicas: 2
healthcheck:
path: /health
interval: 30The top-level python key gives the component a stable name. Other root
documents can reuse the same value.
Create config.yaml beside the components directory:
version: 1
services:
orders:
runtime:
$ref: components/runtimes.yaml#/python
port: 8080The part before # locates the document. The fragment /python is a JSON
Pointer selecting the python key in that document.
Your files now look like this:
.
├── components
│ └── runtimes.yaml
└── config.yaml
Run:
ref-bundle config.yamlBecause no output path or format was specified, Ref Bundle writes YAML to standard output. The collected document includes the component in place of the reference:
version: 1
services:
orders:
runtime:
image: python:3.13-slim
replicas: 2
healthcheck:
path: /health
interval: 30
port: 8080Create a JSON bundle:
ref-bundle config.yaml --ext json --output build/config.jsonRef Bundle creates the build directory if needed. build/config.json is a
single file and no longer requires components/runtimes.yaml at runtime.
You have now separated the maintainable source configuration from its portable delivery artifact.
- Build a modular configuration covers naming, repository layout, reuse, and validation in CI.
- Use the playground lets you experiment with references in a browser.
- CLI reference documents all formats, transports, credentials, and output behavior.