Composing configuration

You can keep a shared base configuration in version control and layer personal or optional pieces on top of it. Two mechanisms do this: a local override file, and extends: fragments.

Run xianyun config print at any point to see the fully merged result. Everything on this page was checked against that output.

Local overrides

Put xianyun.local.yaml next to xianyun.yaml (or caproni.local.yaml next to caproni.yaml) for settings that are only yours. Xianyun loads it automatically, resolves it relative to the base file, and so it works when you pass -c /path/to/xianyun.yaml. Add it to .gitignore.

# xianyun.local.yaml, not committed
cluster:
  colima:
    memory: 16GiB
    cores: 8

Merge rules

Value	Behaviour
Maps	Merged recursively; overlay keys add to or replace base keys
Scalars	The overlay wins
`null`	Removes the key, so the default applies
`lifecycle_hooks`, `cluster.network.additional_hostnames`, `dynamic_overrides`	Lists are appended
Any other list	The overlay replaces the base list

You only write what you want to change. For example, with k3d.agents: 4 in the base file, a local file that sets agents: 7 gives 7, and one that sets agents: null gives 0, the default.

Appended lists keep a fixed order: fragments first, then the base file, then the local file. With a.frag.test in a fragment, a.base.test in the base file, and a.local.test in the local file, the merged additional_hostnames came out in that order.

Shared fragments with `extends:`

extends: pulls other files into the base. They’re merged left to right, and the base file wins over every fragment. In a test, a fragment that set hostname: frag.test and k3d.servers: 3 lost to a base file with hostname: base.test and servers: 1.

# xianyun.yaml
version: 2
extends:
  - xianyun.shared.yaml
  - services/xianyun.valkey.yaml
cluster:
  driver: k3d
  network:
    hostname: myapp.test

A fragment holds only the keys it adds or overrides, such as another repository, deployer, or reloader. Name fragments xianyun.<name>.yaml (caproni.<name>.yaml is accepted too). Paths in extends: are relative to the file that lists them, so a fragment can live in a subdirectory next to its supporting files.

A fragment can’t contain extends: itself. Xianyun stops with fragment files must not contain extends:.

xianyun.local.yaml can also use extends: to pull in fragments you don’t commit.

Fragments over HTTPS

An entry in extends: can be an https:// URL whose file name matches xianyun*.yaml or caproni*.yaml. Relative paths inside that fragment, such as a Helm values file, are fetched from the fragment’s location, not from your project. Directories can’t be fetched, so a remote fragment can’t point a Kustomize deployer at a local directory.

Remote fragments carry real risk. They have no pinning, checksum, or signature, and they can add repositories, deployers, and lifecycle hooks that run commands. Read Security before you extend one you don’t control, and prefer a fragment kept in your own repository.

What Xianyun adds on its own

Nothing. Every deployer in the resolved configuration comes from your file, a fragment you extended, your local file, or a xianyun-project.yaml in an edit-mode repository. Two Kustomize overlays are built into the binary but still need a deployer to use them: path: builtin:dev-ca and path: builtin:traefik-tlsstore. See the reference.

The builtin: overlays haven’t been deployed end to end; see Known limitations.

Keyboard shortcuts