# Velero: Kubernetes backup and restore split across a server and a CLI

> A CNCF sandbox project that snapshots cluster resources and persistent volumes, with a server running inside your cluster and a command-line client running on your laptop.

**velero-io/velero** — Backup and migrate Kubernetes applications and their persistent volumes

- Repository: https://github.com/velero-io/velero
- Website: https://velero.io
- Stars: 10,332 · Forks: 1,631
- Language: Go
- License: Apache-2.0
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/velero-io-velero

## A server on the cluster and a CLI on your machine

The README describes Velero, formerly Heptio Ark, as tooling for backing up and restoring Kubernetes cluster resources and persistent volumes, and it is unusually specific about the shape of the system: a server that runs on your cluster and a command-line client that runs locally. That two-part design explains most of Velero's behaviour, including the parts that surprise people. The server is what needs permission to read every resource you want captured, and it is where scheduling and retry logic live. The client is what you type, and it can be run from a laptop against a remote cluster without carrying cluster state with it.

It also explains why the build looks like a large Go program rather than a small one. The `go.mod` pulls in the AWS, Azure and Google Cloud SDKs alongside Kubernetes client libraries, because the storage backend is pluggable and each supported provider carries its own dependency weight. Deduplication comes from kopia, listed at v0.16.0, and the command-line surface comes from cobra. The tests use ginkgo and gomega rather than the standard library, and prometheus client_golang is in the dependency list for metrics.

The container image is built from a Go 1.26 base, so the version floor is not ancient:

```dockerfile
FROM --platform=$BUILDPLATFORM golang:1.26-trixie AS velero-builder
```

The module declaration in `go.mod` still points at the project's earlier home, which the README never mentions:

```
module github.com/vmware-tanzu/velero

go 1.26.0
```

## Three jobs that share one backup artifact

The README lists three things Velero lets you do, and they are worth reading as three angles on the same mechanism rather than three separate features. Taking backups and restoring in case of loss is the obvious one. Migrating cluster resources to another cluster reuses the same artifact with a different destination. Replicating a production cluster into development and testing clusters is the same thing again, aimed at test environments.

What makes these cheaper than doing them by hand is that a Velero backup is a single object containing both the Kubernetes object definitions and the volume data, with the mapping between them preserved. That joint artifact is the reason the project exists rather than a wrapper around a filesystem snapshot tool. A volume snapshot on its own gives you bytes with no idea which pod mounted them where.

Where the data actually lands is a separate decision from where the Kubernetes objects are recorded. The README keeps this at the level of saying you can run Velero with a public cloud platform or on-premises, and pushes the specifics of backends, providers and snapshotter plugins into the documentation site. For an evaluation that is the right split, because the provider matrix changes between releases and a README table would rot, but it does mean the README alone will not tell you whether your CSI driver has a working snapshotter. That check belongs with your storage documentation.

## What the compatibility matrix commits to, and where it disagrees with itself

The compatibility table is the most useful and the most confusing part of the README. It lists Velero 1.14 through 1.18, gives each a tested Kubernetes version set, and then states an expected compatibility range. The tested column is specific and moves sensibly: 1.14 tested on 1.27.9, 1.28.9 and 1.29.4, while 1.18 is tested on 1.33.7, 1.34.1 and 1.35.0.

The expected compatibility column, by contrast, reads 1.18-latest for all five rows, including Velero 1.14 and 1.15. Read literally, that claims a Velero 1.14 install is expected to work against Kubernetes 1.18 and later, which contradicts the tested column two rows above it. Both statements are in the README, and neither is marked as a typo.

The practical resolution is to treat the tested column as the real commitment and the other column as unmaintained. The README backs this up with two explicit concessions: maintainers say they cannot test every combination of Velero and supported Kubernetes versions for each release, and they say the table tracks current testing coverage rather than a support promise. Where a combination you want is not listed, the project's own advice is to test before installing or upgrading.

One promise in that table is worth holding them to, because it is the hard one. For each release, maintainers run a test that verifies the upgrade path from the n-2 minor release, checking that a backup created by the two previous versions restores with the new build. That is the guarantee that makes versioned upgrades safe, and it is a stronger statement than most backup tools make about their own history.

## The Go module path and release links still point at the old organization

The repository lives under velero-io, the README links to velero.io, and governance is maintained in a separate velero-io organization repository. The `go.mod` nonetheless declares the module as `github.com/vmware-tanzu/velero`, and the download links inside the v1.18.3 and v1.18.3-rc.2 release notes still point at releases under that same vmware-tanzu path.

These are two different kinds of leftover and they behave differently. A Go module path is fixed by convention at the point the module is first published, so an existing path that stops matching the repository location is a known, mostly harmless artifact of a rename. A stale download URL in release notes is closer to a plain broken link, and it matters more if anything automated reads those release bodies.

If you are writing a script that consumes Velero releases, resolve the repository path rather than pasting a URL out of a release note, and prefer the container reference over the binary download link when you can. The image reference `velero/velero:v1.18.3` is version-pinned and does not carry the organization rename with it, which makes it the more stable thing to hard-code.

This is also a reasonable signal about how the project handles renames overall. The rename from Heptio Ark to Velero is mentioned in a single clause in the README's overview, with no migration note, because Velero is a rename of the project name and not of its import path, so no consumer action follows from it.

## Recent patch notes are about restores that used to come back broken

The v1.18.3 release was published on 2026-09-21, the same date as the last push on the default branch. Reading its change list is a decent proxy for what actually goes wrong with a Kubernetes backup tool, because the fixes cluster around two themes.

The first is data that was captured but could not be restored. One entry fixes PodVolumeBackup metadata loss on an fs-backup timeout, described in the note as having caused all fs-backup volumes to become unrestorable. A backup that succeeds and then cannot be read back is the worst failure mode this project can have, and it is the one worth checking for directly in your own environment rather than inferring from a green backup job.

The second theme is failing early instead of failing confusingly. One entry bounds WaitRestoreExecHook polling with resourceTimeout so restore exec hooks that never complete cannot wait forever, and another makes backup validation fail when a built-in data mover is requested but no node-agent pods are running. Both convert a hang or a silent misconfiguration into a refused operation.

There are also quieter correctness fixes worth noting: an empty ProviderSnapshotID no longer triggers a DeleteSnapshot call, and the cached node-agent LoadAffinity is no longer mutated, which had been appending an OS node selector term repeatedly across data mover pods. That second one is the kind of bug that only shows up after many backup cycles, which is exactly the sort of thing to look for when choosing a backup schedule.

## Where the README stops and velero.io takes over

The README is a good index and a thin manual. It gives you the architecture in two lines, the three use cases, the compatibility table, links to troubleshooting and start-contributing guides, and pointers to the Kubernetes Slack channels and the bi-weekly community meetings that alternate between Beijing-friendly and US/Europe-friendly time zones. It also states the project's CNCF sandbox status and the LF Projects copyright.

Everything a production decision needs is one hop away on velero.io: the getting started guide, architecture, the guide on extending Velero, and the support process page. The README explicitly asks you to use the version selector at the top of the documentation site, which is a small warning that the docs track releases rather than sitting at a single moving target.

For a project with over 800 open issues, that division of labour matters more than usual. The repository tells you what the software is made of and what has recently broken. The documentation tells you how to install it, which plugins your environment needs, and how a restore behaves when a resource no longer exists. Reading the compatibility table first, then the architecture page, gives you enough to decide whether a restore is something you want to depend on before you schedule the first one.

## Conclusion

Velero is a good fit when you need cluster resources and volume data to come back together, because that joint restore is the reason the project exists rather than a feature bolted onto a volume snapshotter. The documentation on velero.io is where the real decisions live: which storage backend you register, which snapshotter your volumes use, and how the n-2 upgrade path applies to your setup. Start by reading the compatibility table for the version you intend to run and checking that your Kubernetes version appears in the tested column, then read the architecture page before your first scheduled backup.

## FAQ

### What is the current version of Velero?

The most recent release is v1.18.3, published on 2026-09-21. The matching container image is velero/velero:v1.18.3, and the documentation for that line lives at velero.io/docs/v1.18/ rather than at the unversioned path.

### Does Velero support every Kubernetes version its README mentions?

Not according to the README's own table. The tested column is specific and moves with each Velero release, so v1.18 is tested on Kubernetes 1.33.7, 1.34.1 and 1.35.0, while v1.14 is tested on 1.27.9, 1.28.9 and 1.29.4. The expected compatibility column repeats 1.18-latest for every row, which contradicts the tested column, so treat the tested list as the real commitment and test anything outside it.

### What does a Velero backup actually capture?

Both the Kubernetes object definitions and the persistent volume data, kept in a single backup artifact along with the mapping between them. That joint capture is what lets a restore bring an application back as a working unit rather than as data with no record of which pod owned it.

### Is it safe to upgrade Velero across several minor versions?

The project states that for each release, maintainers run a test verifying the upgrade path from the n-2 minor release, confirming that a backup created by the previous two versions restores with the new build. That covers a two-minor-version span, so a larger jump should be planned as a sequence of documented upgrades rather than a single leap.

## Sources

- [License: Apache-2.0](https://github.com/velero-io/velero/blob/main/LICENSE)
- [Project website](https://velero.io)
- [README](https://github.com/velero-io/velero/blob/main/README.md)
- [Releases](https://github.com/velero-io/velero/releases)
- [velero-io/velero on GitHub](https://github.com/velero-io/velero)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/velero-io-velero