Upgrading to Kranz 0.15

Kranz 0.15 composes configuration from several autonomous files. Four changes can break an existing setup; each section says how to recognise it and what to change. Everything else in the release is additive and described in Composing configurations.

Native Kranz files can form the recursive composition tree. Existing Procfile and supported Process Compose projects can join it as terminal leaves, including through glob and discovery, without conversion to kranz.yaml.

If you are upgrading from 0.7 or earlier, keep the older 0.8 CLI migration separate from the new composition semantics:

kranz prod.yaml     # 0.7
kranz -f prod.yaml  # 0.8 and later

The -f option itself is not new in 0.15. Version 0.15 changes only what repeated -f values mean. See Upgrading to 0.8 for the original positional-argument migration.

Repeated -f composes instead of merging

Up to 0.14, kranz -f kranz.yaml -f kranz.local.yaml merged the second file into the first. From 0.15 both files are complete projects composed side by side, so a partial file passed with -f either fails validation or adds services instead of changing them.

Pass partial files as override layers:

# 0.14
kranz -f kranz.yaml -f kranz.local.yaml

# 0.15
kranz -f kranz.yaml --override kranz.local.yaml

Or declare the layer in the root file:

project: Shop
overrides:
  - kranz.local.yaml

The same applies to KRANZ_CONFIG with several paths: move partial files to KRANZ_OVERRIDE. An override layer cannot declare defaults, include, overrides, or protected; move those into the base file.

Keep repeated -f where every file is a complete project that runs on its own.

Confirmed CLI actions need an explicit second step

Previously, naming an exact action in the CLI implicitly approved its confirm: true setting, while MCP returned confirmation_required. The two surfaces are fail-closed consistently in 0.15:

kranz actions run api/migrate             # review confirmation_required plan
kranz actions run api/migrate --confirm   # execute that freshly resolved plan

Actions without confirm: true still run with one command. CLI JSON includes the resolved plan under error.details.plan; MCP continues returning the plan-bound one-shot confirmation_token for its second call.

Colliding service names are qualified

When two composed files declare the same service name, both services are now qualified by their directory, for example catalog/api and checkout/api. Scripts, selectors, and depends_on entries that use the bare name fail with an ambiguity error listing the choices. kranz config check reports each collision as display_name_qualified; use the qualified names it prints.

reload --output json has no restarted set

A reload no longer restarts running services. A running service that changed, was renamed, or was removed keeps its accepted configuration until you restart it, and appears under pending with service_id, name, kind, and reason. Automation that read restarted should read pending and restart the listed services explicitly.

Check the upgraded project

kranz config check     # diagnostics for qualified names and override layers
kranz config sources   # every file as an include tree, with what it contributed