Directory or file to migrate. Defaults to the current working directory.
'hyve migrate'
hyve migrate is three distinct commands under one parent, each solving a different problem. Picking the right one matters — they’re not interchangeable.
| Command | Source → Destination | Needs hyve context login? | Use it for |
|---|---|---|---|
hyve migrate [path] | Local files → the cluster you’re logged into | Yes | Day-to-day: pushing local definitions into an already-running cluster-mode deployment |
hyve migrate to-cluster | Local files → any cluster, by name or kubeconfig | No | Bootstrapping — the target cluster’s own API doesn’t need to exist yet |
hyve migrate cluster | The current host → another cluster, by name or kubeconfig | No | Moving (all or part of) the host cluster itself |
hyve migrate [path]
hyve migrate [path] [--dir <dir>] [--file <file>] [--write] [--skip-existing]Reads CR-shaped YAML (a directory tree, walking templates/, workflows/, then clusters/ in that order — or a single file) and creates each as a real resource via the API, going through your active hyve context login session.
[path] string --write boolean default: false Actually create resources. Without it, this is a dry run — lists what would be created, writes nothing.
--skip-existing boolean default: true Treat an already-exists response as success rather than a failure, so a partial migration can just be re-run.
hyve migrate ./my-config --writehyve migrate to-cluster
hyve migrate to-cluster (--to <kubeconfig> | --to-cluster <name>) [--dir <dir>] [--namespace <ns>] [--config-name <name>] [--write] [--force]Copies every ClusterDefinition (spec and status — driverOutputs/appliedResources, so the destination’s controller can act on an already-provisioned cluster instead of mistaking it for brand new), Templates and Workflows, plus hyve.yaml as a HyveConfig CR, directly onto a target cluster. No hyve context login or API needed on the target — this talks straight to its Kubernetes API server, the same as kubectl apply would, which is exactly why it works for bootstrapping a cluster whose controller+API aren’t deployed yet.
--to string Path to the target cluster’s kubeconfig — a fallback for ad hoc cases with no convenient ClusterDefinition to point at (disaster recovery, or a cluster hyve doesn’t otherwise know about yet).
--to-cluster string Name of a ClusterDefinition hyve already knows about, resolved to a kubeconfig the same way hyve cluster auth would (local-mode native driver auth, or cluster-mode’s access provider, whichever applies to where you’re currently running). The usual choice — prefer this over --to.
--dir string Local directory to migrate from. Defaults to the active context’s directory.
--namespace string default: hyve-system Namespace on the target cluster to create objects in.
--write boolean default: false Default is a dry run.
--force boolean default: false Overwrite an existing object with the same name instead of skipping it.
hyve migrate to-cluster --to-cluster unraid-host --namespace hyve-system --writehyve migrate cluster
hyve migrate cluster (--to <kubeconfig> | --to-cluster <name>) --write --i-have-stopped-the-source-controller [--namespace <ns>] [--force] [--skip-access-bindings]Moves (all or part of) which cluster hosts hyve’s control plane — hardware replacement, cloud migration, splitting one tenant onto its own dedicated cluster, whatever the reason. The source is always the current host — whatever hyve context current resolves to — there’s no --from flag; a wrong guess here is the one place this command could cause real damage (see the risk warning below), so it isn’t left to be specified, it’s read directly off your own active session. The target works the same as to-cluster above: --to-cluster <name> (preferred) or --to <kubeconfig> as a fallback.
--to string Path to the target cluster’s kubeconfig (fallback — prefer --to-cluster).
--to-cluster string Name of a ClusterDefinition hyve already knows about, resolved the same way hyve cluster auth would.
--namespace string default: hyve-system Scope. A tenant namespace copies only that organization’s ClusterDefinitions and access bindings (+ credentials Secrets) — everything else on the source is untouched, and its control plane keeps running for every other tenant the whole time. The default, hyve-system, is special-cased to copy everything: every organization (enumerated via hyve-api’s own datastore, see --db/--db-dsn below) plus the control plane’s own objects (HyveConfig, the host ClusterDefinition, superadmin bindings). This isn’t arbitrary — hyve-system is the control plane’s own home, so migrating it necessarily takes everything it’s responsible for along with it.
--i-have-stopped-the-source-controller boolean default: false Required alongside --write — refuses to run past a dry run without it, an explicit acknowledgment (not just a warning) that dual-reconciliation is a real risk. See below.
--skip-access-bindings boolean default: false Skip copying access bindings and their credentials Secrets — only ClusterDefinitions/HyveConfig.
--db string default: sqlite Backend for the source host’s own organization datastore, used only when --namespace=hyve-system to enumerate which organizations to migrate alongside the control plane — must match that host’s own hyve cluster-config api run --db.
--db-dsn string default: /data/orgdb.sqlite Data source name for --db — must point at the same database the source host’s hyve-api uses, never the target’s.
# Move the whole control plane onto a new hosthyve migrate cluster --to-cluster unraid-host \ --write --i-have-stopped-the-source-controller
# Split one tenant onto its own dedicated cluster, leaving everything# else on the current host runninghyve migrate cluster --to-cluster acme-dedicated --namespace acme \ --write --i-have-stopped-the-source-controller