Configuration reference
This page summarises the keys. The authoritative description is the schema, schema/config.v2.schema.json, and xianyun config validate enforces it.
Top level
| Key | Type | Required |
|---|---|---|
version | integer, must be 2 | yes |
cluster | object | yes |
extends | list of paths or HTTPS URLs | no |
repositories | map of name to repository | no |
deployers | map of name to deployer | no |
reloaders | map of name to reloader | no |
variables | map of name to value | no |
cluster
| Key | Meaning |
|---|---|
driver | auto, colima, k3d, external, vcluster, or mock. auto picks k3d on Linux and colima elsewhere. mock is for tests. |
name.strategy | static (default, uses xianyun) or directory-hash |
network.hostname | The primary hostname, for example gitlab.test. Required. |
network.additional_hostnames | More hostnames to set up, for example a registry |
network.cluster_domain | The cluster DNS domain, when it isn’t under .local |
registry_mirror | The pull-through image cache. See below. |
driver and k3s.disable can’t contain variables. They must be written literally.
Driver settings
| Block | Keys |
|---|---|
k3d | agents, servers, image, port_mappings, k3s.disable, extra_args (passed verbatim to k3d cluster create, one token per entry) |
colima | memory, cores, disk, k3s.disable. Colima always runs on the containerd runtime. |
external | context, the kubeconfig context to use (the current one if omitted). down and destroy return an error because Xianyun doesn’t own the cluster. |
vcluster | host_context (required), namespace, chart_version, values, manage_namespace |
mock | No settings |
registry_mirror
| Key | Meaning |
|---|---|
managed | true runs and supervises a host-side zot cache. Default false. |
endpoint | URL of a cache you run yourself, reachable from the cluster nodes. Required when managed is false, and not allowed when it’s true. |
upstreams | Registry hostnames whose pulls go through the cache, such as docker.io. The feature is off when this is empty. |
See Registry cache.
repositories
Each entry needs repository (a Git URL) and directory (where to clone it). Optional keys: ref (a branch, tag, or commit; a tag or SHA pins the repository), edit_mode, and lifecycle_hooks.
deployers
Each deployer has a type, an optional needs list naming deployers that must finish first, and an optional repository. Deployers without a needs edge run in no defined order.
| Type | Body | Notes |
|---|---|---|
helm | helm.namespace (required), wait, timeout, values_file, dynamic_overrides, repository, release | Charts can be local, OCI, or from a chart repository |
kustomize | kustomize.path (required), namespace, files | builtin:dev-ca and builtin:traefik-tlsstore are built-in targets |
namespace | namespace.namespaces (list of names, required), delete_on_undeploy | Creates namespaces and waits for each to be usable |
The builtin: overlays haven’t been deployed end to end; see Known limitations.
reloaders
| Type | Body |
|---|---|
mirror | mirror.target (namespace, kubernetes_type, name), mirror.edit_mode_processes (required), filesystem, network |
skaffold | skaffold settings and repository |
kubernetes_type is one of deployment, statefulset, daemonset, or pod. Each edit_mode_processes entry has a command, and optionally a port and a context of mirrord or local. See Edit mode.
lifecycle_hooks
A hook has a type and one of script, mirror_script, or job. The types are edit_mode_prepare, edit_mode_start, and edit_mode_stop.
A script is split into arguments with quote handling and run directly, with no shell, so $HOME, pipes, and ; mean nothing to Xianyun. Wrap the command in sh -c '...' if you need shell behaviour. Hooks inherit your environment plus the predefined variables and KUBECONFIG.