WIP: velero

[illume]

Please don't start this issue.

[vinniit-23]

Hi @illume 👋,

I'm applying for the CNCF LFX Mentorship – Headlamp: Velero Backup Management Plugin (2026 Term 3) project. Before submitting my application, I want to contribute to Headlamp and become more familiar with the codebase.

I've already set up the development environment and have been exploring the project. Could you recommend any beginner-friendly issues that would be a good place to start? If there are any issues related to the plugin system or Velero, I'd especially love to work on those.

Also, if there are any resources or documentation that explain Headlamp's architecture, plugin system, or overall design, I'd really appreciate it.

Thanks!

[naresh-coder123]

Hi @illume ,
I have applied for the CNCF LFX Mentorship – Headlamp: Velero Backup Management Plugin project(Term 3). To get a solid head start and really understand the codebase, I've already started exploring the project.

I’d love to start contributing with a beginner-friendly issue (or any open good-first-issue) to get familiar with the codebase and contribution workflow. If there are any starter tasks or low-hanging fruit related to the plugin system or Velero integration, that would be ideal!

Also, could you point me toward any architectural docs, design specs, or plugin development guides that dive into Headlamp's overall design? I’m really curious to understand how the plugin runtime and state management are structured under the hood.

Looking forward to contributing and getting involved with the community!

[Tharun2331]

Hi @illume ,

I hope you're doing well. I want to express my interest in the Headlamp: Velero Backup Management Plugin project (Term 3). To get oriented, I've set up a local Headlamp dev environment (backend + frontend running against a kind cluster) and gone through the existing plugins in this repo particularly kueue's resource/component split and cert-manager's use of ApiProxy to understand the conventions a new plugin here is expected to follow.

I have production TypeScript/React experience (Redux, Zod, RAG pipelines, AWS microservices, Terraform), and I'm installing Velero into my local kind cluster this week so I can start working against the real Backup/Restore/Schedule CRDs rather than the outcome description alone. Happy to pick up a smaller good first issue on this repo first if that's a useful way to build context before taking this on directly.

Thanks for your time!
Tharun

[pbcodesC]

Hey @illume,

Honestly, this project really caught my attention. Before looking into it, I didn’t realize you could build such a complete GUI experience around something like Velero — with backups, restores, dashboards, maps, integrations, etc. It got me genuinely curious about how Headlamp and the Velero plugin work under the hood, and that’s what made me want to contribute to this project.

I’ve also worked with Docker, AWS, Git/GitHub and Kubernetes, so I’d love to explore the Headlamp codebase and understand how the Velero integration is being built.

I’ll start with a small contribution to get comfortable with the project and hopefully work my way up to the main features :)

[Prathamesh09-coder]

Hi @illume👋
When you have a chance, could you please review this PR? I’d really appreciate any feedback or suggestions for improvement. I’m happy to make any requested changes.

Thanks for your time and for maintaining the project!

[ahuman1684]

Instead of adding another note of interest, here's what I worked out from reading
Velero's v1 API alongside the plugins already in this repo. Tell me where it's wrong.

Registration. All five kinds (Backup, Restore, Schedule,
BackupStorageLocation, VolumeSnapshotLocation) are in velero.io/v1 and all of them
are namespaced. So the config-driven approach in cert-manager/src/index.tsx gets
simpler here: cert-manager needs its hasNamespace flag because ClusterIssuer is
cluster-scoped, whereas Velero's set is uniform, so one array of
{name, path, ListComponent, DetailComponent} covers the sidebar.

Install detection. cert-manager/src/isCertManagerInstalled.ts probes
ApiProxy.request('/apis/cert-manager.io/v1') and returns false instead of throwing. The
Velero plugin needs the same guard against /apis/velero.io/v1. Without it every list
view errors out on a cluster that doesn't have Velero, which is most clusters someone
tries Headlamp on first.

Map integration. This is where Velero differs from flux in a way that matters.
flux/src/mapView.tsx builds edges with makeKubeToKubeEdge over metadata.uid, and
flux's graph mostly follows ownership. Velero doesn't set ownerReferences between these
kinds. The relationships are name references plus one label:

• Restore.spec.backupName → Backup
• Restore.spec.scheduleName → Schedule (a Restore can reference either)
• Backup.spec.storageLocation → BackupStorageLocation
• Backup.spec.volumeSnapshotLocations → VolumeSnapshotLocation (a list, so fan-out)
• Schedule → Backup via velero.io/schedule-name (ScheduleNameLabel)

So the map source has to resolve those by name within the Velero namespace, and tolerate
dangling ones. A Backup whose BSL was deleted should show as a broken edge rather than
disappear.

Phase isn't a three-state badge. This is the detail I'd most want to agree on early.
BackupPhase in pkg/apis/velero/v1/backup_types.go has thirteen values: New,
Queued, ReadyToStart, FailedValidation, InProgress, WaitingForPluginOperations,
WaitingForPluginOperationsPartiallyFailed, Finalizing, FinalizingPartiallyFailed,
Completed, PartiallyFailed, Failed, Deleting. Two of those will catch out a naive
status indicator. WaitingForPluginOperations reads as terminal but is still in flight,
and the ...PartiallyFailed variants of it and of Finalizing are in-flight states that
already carry a failure signal. Map those to green/amber/red by string and you'll report a
running backup as finished, which in a backup UI is the wrong direction to be wrong in.
I'd rather enumerate the phases explicitly and treat terminal-vs-in-flight as its own
axis.

The rest of the detail view comes straight off status: progress.itemsBackedUp and
progress.totalItems for a progress indicator, validationErrors for the failure case,
startTimestamp and completionTimestamp for duration.
BackupStorageLocation.status has phase (Available / Unavailable),
lastValidationTime and lastSyncedTime. accessMode belongs on that tile too, since a
BSL in ReadOnly still reports Available but can't take new backups. You can have an
entirely green storage row and nowhere left to back up to.

Schedule adherence is the outcome I think is hardest, and it's the reason I'd start
there. It's the only one that isn't a field read. A Schedule that stopped firing looks
identical to a healthy one on its own object, and the signal is the absence of a recent
Backup carrying its label. Detecting it means comparing spec.schedule against the newest
labelled Backup's status.startTimestamp and flagging the drift.

Actions. For creating Backups and Restores from the UI, a details-view header action
along the lines of flux/src/actions/headerActionsProcessor.tsx seems more discoverable
than a separate create form. "Back up now" on a Schedule mirrors
velero backup create --from-schedule, and "Restore from this" on a completed Backup is
what people reach for when something's already gone wrong.

One question for @illume and @shubham-pampattiwar: should the plugin assume the standard
velero namespace or discover the install namespace? Velero can be installed elsewhere,
and it decides whether that's a plugin setting or a lookup.

[Ralthos]

@ahuman1684's read on the phase enum matches mine, and the WaitingForPluginOperations
trap is real. I want to add the part nobody has raised yet, because I have spent the last
two weeks on the Velero side of it.

Logs and artifacts do not come back over the API. Backup logs, restore logs, volume
info and the resource list are all reached through the DownloadRequest CR: create one,
wait for the controller to sign status.downloadURL, then GET that URL. Two things about
that flow will bite a browser plugin harder than they bite the CLI.

Processed has not meant "there is a file." The controller maps the target kind to an
object key and signs it by convention, without checking the object is present. A backup
that ended in FailedValidation never wrote a log, and a DownloadRequest against it
still reaches Processed with a populated URL that returns 404. I filed that as
velero-io/velero#10232 with a reproduction. velero-io/velero#10252 is the fix:
DownloadRequestPhase gains Failed and DownloadRequestStatus gains Message, so the
controller declines instead of signing a dead URL and the reason travels on the object.
It merged on 21 August, so both fields are in velero.io/v1 for whichever Velero release
comes next.

For the plugin that means the poll loop needs three exits: URL present, phase Failed
(stop, surface status.message), and a client-side timeout. It also means the plugin
cannot assume Failed exists. Against any Velero at or before the current release there
is no terminal failure phase, the request sits in New indefinitely, and the honest UI
says no log was produced for this backup. Reporting a storage problem there points at the
wrong thing. Whatever the plugin does has to work against both server versions.

@shubham-pampattiwar, that one is really a question for you: how far back should the plugin
support Velero servers? The answer decides whether the terminal-phase handling is the normal
path with a fallback, or a capability check with two code paths kept in step.

The GET is cross-origin. One question I would like settled early, because it splits
the two designs. velero backup logs fetches the signed URL from the Velero client
process. A Headlamp plugin fetching it from page JavaScript is making a cross-origin
request to the object store, so it depends on CORS being configured on the bucket, which
most Velero installs have no reason to have done. I have not measured this against a real
S3 or MinIO bucket, so I would rather ask than assert: @illume, is the intent for the
plugin to fetch signed URLs directly from the browser, or to route them through the
Headlamp backend the way externalproxy does? If it is the former, log viewing works on
some clusters and silently fails on others depending on bucket config, and that is worth
knowing before any UI is built on top of it.

Smaller point: the printer columns added to Backup, Restore,
VolumeSnapshotLocation and DownloadRequest recently (velero-io/velero#10200, velero-io/velero#10216,
velero-io/velero#10229) are a reasonable starting set for the list views here, since they are the
fields Velero maintainers picked as the at-a-glance ones.

I am applying for this project. My contributions so far are upstream in velero-io/velero
and reviews in this repo. I read "please don't start this issue" as meaning what it says,
so there is no plugin code from me.

[Ralthos]

I wrote the security side of this up as a STRIDE threat model: #1238. It
is a document, with no plugin code in it.

The finding I would most want checked is I1. A DownloadRequest with
target.kind: BackupContents gets a ten minute signed URL to the backup tarball, the
controller signs it without checking who asked, and backups contain Secrets unless someone
excluded them. So create on downloadrequests in the Velero namespace is closer to
cluster-wide secret read than the permission name suggests, and that changes what a download
control in this plugin should look like and what its RBAC guidance has to say.

The rest covers restore as object creation, irreversible backup deletion, actions addressed
to the wrong cluster in a multi-cluster selection, and a health dashboard showing green when
it could not reach anything.

Every claim carries a Verified, Plausible or Open label. The mechanisms are Verified against
Velero source and cited by line. The escalation I1 implies is Plausible, because I have not
run it against a restricted ServiceAccount, and the document says so rather than leaving it
to be found.

[Ralthos]

On the namespace question, one data point: the CLI never discovers its own namespace.
NewFactory in pkg/client/factory.go reads VELERO_NAMESPACE, then the config file, then
falls back to DefaultNamespace ("velero"), with --namespace overriding. It is always told.

The plugin has a signal the CLI does not. All five kinds are namespaced and velero install
creates a default BackupStorageLocation, so one cluster-wide BSL list returns the install
namespace in metadata.namespace.

Two cases break that as the only path. It needs cluster-scoped list permission, so a
namespace-scoped user gets an empty list and lands in the same neutral state as "not installed",
which is the probe problem in #1083. And a cluster can run more than one install, so the list
can come back with several and a setting has to pick between them.

Discovery with an explicit override seems to cover all three, though that is the mentors' call.