Your first project

This page uses the terminal. The same commands are what your agent calls, so it’s worth running them once yourself to see what they print.

Write a configuration

Create xianyun.yaml in your project directory:

version: 2

cluster:
  driver: auto # k3d on Linux, colima on macOS
  network:
    hostname: myapp.test

version and cluster are the only required keys, and cluster.network is required inside cluster. See the configuration overview for everything else.

Xianyun looks for xianyun.yaml in the current directory and then in each parent, stopping at your home directory. If it finds only caproni.yaml, it uses that, so existing Caproni projects work unchanged.

Validate it

$ xianyun config validate
✓ Configuration is valid (v2)
  • 0 deployers configured
  • 0 repositories defined
  • 0 reloaders configured

A mistake produces a schema error that names the field as a JSON pointer, for example /cluster/driver: "nonsense" is not one of [...], and exits non-zero.

Check your machine

$ xianyun doctor

doctor reports problems it knows about. It currently runs two diagnostics, cluster domain and orphaned mirror copies, which is fewer than the Go tool had.

Bring the cluster up and down

$ xianyun up        # start the cluster and wait for its API to answer
$ xianyun status    # show the cluster state
$ xianyun kubectl get nodes
$ xianyun down      # stop it, keep its state
$ xianyun destroy   # delete it and its data

xianyun kubectl runs your kubectl with KUBECONFIG pointing at this project’s cluster, so you don’t touch your default context. xianyun set-kube-context merges the cluster into your own kubeconfig if you’d rather use it directly.

down and destroy succeed when no cluster exists, so they’re safe to repeat. With driver: external they return an error instead, because Xianyun doesn’t own that cluster’s lifecycle.

Optional host setup

$ xianyun ca trust                 # install the dev CA (asks for sudo)
$ xianyun update-etc-hosts --dry-run
$ xianyun update-etc-hosts         # write hostnames to /etc/hosts (asks for sudo)

Both change your machine outside the project, which is why they’re gated when an agent calls them. See Trusting the dev CA.

Connect an agent so it can run these for you.

Keyboard shortcuts