Warning
Kopiur is brand new and under active, breaking development. Things are incomplete, untested in the wild, and the CRD surface, behavior, and APIs will change without notice. Do not run this against data you care about.
Please do not open Pull Requests. The codebase is moving too fast for external PRs to be reviewable right now — they'll likely conflict or target code that's about to be rewritten. Open an Issue instead to report a bug, request a feature, or start a discussion. Issues are very welcome; PRs will be politely closed with a pointer back here for the time being.
Kopiur (Kopia + Rust) is a Kopia-native Kubernetes backup operator written in Rust on kube-rs. It makes a kopia repository a first-class Kubernetes resource and separates the backup recipe from its invocation from its schedule, so backups can be triggered by cron, kubectl create, Argo Events, or a Helm hook — and a kopia snapshot's lifecycle is tied to its Backup CR by a finalizer + deletionPolicy. The whole CRD surface is modeled as Rust enums so invalid states are unrepresentable and reconcilers handle every variant at compile time. See ADR-0003 for the full design.
Status: alpha — API group
kopiur.home-operations.com, versionv1alpha1. The CRD surface may still change between releases.
| CRD | Scope | Layer | Purpose |
|---|---|---|---|
Repository |
Namespaced | Storage | A kopia repository owned by one namespace: backend, encryption, credentials. |
ClusterRepository |
Cluster | Storage | A shared repository for platform teams, gated by allowedNamespaces. |
BackupConfig |
Namespaced | Recipe | What to back up: PVC sources, identity, retention, policy, hooks. Idempotent. |
Backup |
Namespaced | Invocation + Catalog | One kopia snapshot as a Kubernetes object. The universal trigger entry point. |
BackupSchedule |
Namespaced | Cron | When it runs: cron + jitter + timezone; creates Backup CRs. |
Restore |
Namespaced | Operation | Restore a snapshot to a PVC, or act as a passive volume-populator source. |
Maintenance |
Namespaced | Lifecycle | Schedules kopia maintenance quick + full with an ownership lease. |
kubectl create namespace kopiur-system
helm install kopiur deploy/helm/kopiur \
--namespace kopiur-system \
--set webhook.certManager.enabled=true
kubectl get crd -l app.kubernetes.io/part-of=kopiurThen apply a worked example:
kubectl apply -f deploy/examples/01-single-pvc-scheduled.yamlFull install guide, prerequisites (k8s >= 1.24, optional cert-manager), install modes, and the CRD-lifecycle caveat: docs/install.md.
Day-to-day operations without hand-written YAML — trigger/inspect/restore snapshots, run maintenance, browse files inside snapshots, diagnose installs, migrate from VolSync:
kubectl krew index add kopiur https://github.com/home-operations/kopiur.git
kubectl krew install kopiur/kopiur
kubectl kopiur statusFull reference: docs/cli/index.md.
crates/ Rust workspace (api, kopia, webhook, controller, mover, xtask)
deploy/crds/ Generated CRDs (cargo xtask gen-crds) — checked in
deploy/rbac/ Generated RBAC (cargo xtask gen-rbac) — checked in
deploy/helm/ Helm chart (deploy/helm/kopiur)
deploy/examples/ 8 runnable usage walkthroughs
docs/adr/ Architecture Decision Records (0003 is canonical)
📖 Docs site: https://kopiur.home-operations.com/ — user guide, ADRs, and the generated Rust API reference.