Velero
Velero: from zero to active upstream contributor¶
This guide takes you from the design philosophy of Velero through its internals, extension points, codebase layout, and into the practical mechanics of contributing upstream.
Before you start, you should be familiar with Kubernetes and the Kubernetes API.
You should also be familiar with Kubernetes Operators and Custom Resource Definitions (CRDs).
Specifically you'd follow this guide much better if you have:
- Kubernetes controller-runtime and CRD conceptual knowledge;
- Go proficiency;
- Familiarity with object storage (S3/GCS semantics);
- Basic CSI architecture knowledge.
How to Best Use This Guide¶
Work through the sections in order on a first pass. Each section builds on the previous. Once you have done the full read, the sections work well as standalone references too.
Fastest path to productivity
After reading Architecture
and Core CRDs, set up a local kind cluster with
Velero + MinIO, then trace a full backup with
--log-level debug.
The code becomes real in a way that reading alone can't achieve.
Contents¶
| Section | What you get |
|---|---|
| Foundations | |
| Overview and Design | Why Velero is built the way it is. The API-centric, not etcd-centric bet. |
| Architecture | Process topology, controller-runtime reconcilers, plugin gRPC model. |
| Core CRDs | Every CRD field that matters and its lifecycle semantics. |
| Internals | |
| Backup Mechanics | The full backup pipeline, step by step, with object store layout. |
| Restore Mechanics | Priority ordering, conflict handling, PV restore paths. |
| Controller Deep Dive | All 19 controllers, state machines, which controller owns which phase. |
| Hooks System | Backup pre/post hooks, restore init container hooks, annotation vs spec. |
| Extensions | |
| Plugin System | All plugin interfaces in Go, process model, deployment pattern. |
| Node Agent and Kopia | File-level volume backup internals, data mover microservice model. |
| CSI Snapshots | The recommended volume path, VolumeSnapshotClass gotchas, vSphere CSI. |
| Contributing | |
| Codebase Tour | Package map, key files per subsystem, testing conventions, metrics. |
| Contributing Upstream | Governance, PR conventions, high-value contribution areas. |