Configuration overview

A project is described by one YAML file, xianyun.yaml. If you have caproni.yaml, Xianyun reads that instead and you don’t need to change anything. When both exist in one directory, xianyun.yaml wins.

Minimal file

version: 2

cluster:
  driver: auto
  network:
    hostname: myapp.test

version must be 2, and cluster with its network block is required. Everything else is optional.

The sections

Key	Purpose
`cluster`	Which driver to use, the cluster’s hostnames, driver settings, and the image cache. Reference
`repositories`	Git repositories Xianyun clones and updates
`deployers`	What to install into the cluster: Helm charts, Kustomize overlays, namespaces
`reloaders`	Edit-mode processes with hot reload, through mirrord or Skaffold
`variables`	Named values you reference elsewhere. Variables
`extends`	Other config fragments to merge in, by path or HTTPS URL

How files combine

Xianyun builds the final configuration from several sources and deep-merges them, with later ones overriding earlier ones:

The base file, xianyun.yaml.
Any extends: fragments, left to right.
xianyun.local.yaml next to the base file, for settings that are only yours.
A xianyun-project.yaml from each repository with edit_mode: true, which can add reloaders and lifecycle hooks.

List values for lifecycle_hooks, additional_hostnames, and dynamic_overrides append instead of replacing.

Because several of those sources can come from outside your own file, read Security before you add a remote extends or an edit-mode repository you don’t control.

Composition is covered on its own page: Composing configuration.

Check what you wrote

$ xianyun config validate    # check it against the schema
$ xianyun config print       # show the fully merged, expanded result

config print is the quickest way to see what a variable or an extends produced. It also prints expanded environment values, so don’t paste its output somewhere public if your config references secrets.

The schema is schema/config.v2.schema.json in the repository. Editors that understand JSON Schema can use it for completion if you add this to the top of your file:

# yaml-language-server: $schema=../schema/config.v2.schema.json

Examples

The repository’s examples/ directory has working files. These all pass xianyun config validate:

cluster-only.yaml, the smallest useful configuration.
namespace-deployer.yaml, kustomize-deployer.yaml, local-chart.yaml, and oci-chart.yaml, one per deployer style.
simple-helm-chart-k3d.yaml, a Helm chart plus repositories and an edit-mode reloader.
external.yaml, which adopts an existing cluster.
variables.yaml, which shows variable definitions and file-typed variables.