Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR-0003: Compatibility aliases for config, environment, and data paths

Status: accepted · Date: 2026-10-13 · Decision makers: James Hebden

Context and Problem Statement

Renaming caproni to xianyun touches things users have on disk and in their shells: config filenames, environment variables, the data directory that holds the dev CA and the registry cache, the trusted certificate’s name, and the names of Kubernetes objects. Some of those are cheap to alias and some aren’t. The project had to decide which carry forward and which change cleanly.

Decision Drivers

  • An existing Caproni project must work unmodified
  • State on disk (the trusted CA, the registry cache) must not be orphaned or double-created
  • Names visible inside clusters are referenced by user manifests and certificates
  • Each alias is permanent maintenance

Considered Options

  1. Alias config, environment, and data-path names; rename in-cluster objects with no alias
  2. Alias everything, including in-cluster object names
  3. Rename everything with a one-time migration command

Decision Outcome

Chosen option: “Alias config, environment, and data-path names; rename in-cluster objects”, because those first three are read by Xianyun itself and can be handled in one place, while an in-cluster alias would mean creating duplicate objects (two issuers, two Secrets) that drift.

Concretely, the primary names are xianyun.yaml, xianyun.local.yaml, xianyun-project.yaml, XIANYUN_* variables, and ~/.local/share/xianyun. The caproni.* equivalents are read when the primary doesn’t exist; a xianyun.* file wins if both exist. extends: fragments may be named xianyun*.yaml or caproni*.yaml. The CAPRONI_* environment aliases remain for NO_CACHE and the three predefined cluster variables. The ClusterIssuer and Secret are named xianyun-ca.

Consequences

Good:

  • Existing projects load without edits
  • Legacy trust-store entries are found and cleaned up on uninstall

Bad:

  • Behaviour is split across two names for the lifetime of the aliases, and some places still use the old one: the CA’s common name is still “Caproni Dev CA”, the kubeconfig backup suffix is .caproni.bak, and k3d.rs and colima.rs hard-code .local/share/caproni while datadir resolves to xianyun with a fallback. State can end up split across two directories.
  • The user documentation still says caproni-ca in places, so following it against the Rust binary would reference an issuer that doesn’t exist. examples/own-infrastructure.yaml passes --default-issuer-name=caproni-ca.
  • schema/config.v2.schema.json still limits extends entries to caproni.*.yaml; the unit test passes, so the pattern is probably applied before schema validation, which hasn’t been confirmed end to end.

Neutral:

  • Removing an alias later needs a deprecation window and a new ADR

Implementation Location

  • crates/xianyun-core/src/config/global.rs
  • crates/xianyun-core/src/config/merge.rs
  • crates/xianyun-core/src/naming.rs
  • crates/xianyun-executor/src/datadir.rs
  • crates/xianyun-pki/src/truststore/system_linux.rs

More Information

  • Retroactively documented on 2026-10-13 from README.md (“Configuration compatibility”) and crates/xianyun-deploy/PORT_NOTES.md.
  • Related: FR-001, TM-KUBE-001.