Bundle your first configuration

This tutorial creates two small YAML files and uses Ref Bundle to collect them into one deployable file.

Before you begin

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 --help

1. Create a reusable component

Create components/runtimes.yaml:

python:
  image: python:3.13-slim
  replicas: 2
  healthcheck:
    path: /health
    interval: 30

The top-level python key gives the component a stable name. Other root documents can reuse the same value.

2. Reference the component

Create config.yaml beside the components directory:

version: 1
services:
  orders:
    runtime:
      $ref: components/runtimes.yaml#/python
    port: 8080

The 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

3. Preview the collected configuration

Run:

ref-bundle config.yaml

Because 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: 8080

4. Write a deployable artifact

Create a JSON bundle:

ref-bundle config.yaml --ext json --output build/config.json

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

Next steps