Skip to content

Commit 71c654b

Browse files
authored
feat(backups): backup api rework (#1873)
<!-- Thank you for making a contribution! Here are some tips for you: - Start the PR title with the [label] of Cozystack component: - For system components: [platform], [system], [linstor], [cilium], [kube-ovn], [dashboard], [cluster-api], etc. - For managed apps: [apps], [tenant], [kubernetes], [postgres], [virtual-machine] etc. - For development and maintenance: [tests], [ci], [docs], [maintenance]. - If it's a work in progress, consider creating this PR as a draft. - Don't hesistate to ask for opinion and review in the community chats, even if it's still a draft. - Add the label `backport` if it's a bugfix that needs to be backported to a previous version. --> ## What this PR does ### Release note <!-- Write a release note: - Explain what has changed internally and for users. - Start with the same [label] as in the PR title - Follow the guidelines at https://github.com/kubernetes/community/blob/master/contributors/guide/release-notes.md. --> Closes #1880 ```release-note Added BackupClass into BackupJob and BackupPlan for simplify UX. ``` The following functions related StorageRef were removed as they are no longer used after migrating to BackupClass API: // - resolveBucketStorageRef: Previously resolved S3 credentials from Bucket storageRef // - createS3CredsForVelero: Previously created Velero S3 credentials secrets // - createBackupStorageLocation: Previously created Velero BackupStorageLocation resources // - createVolumeSnapshotLocation: Previously created Velero VolumeSnapshotLocation resources <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added BackupClass CRD and backupClassName field; webhook enforces and defaults/validates backupClassName. * **Refactor** * Removed inline storageRef/strategyRef from specs; controllers resolve strategy and parameters from BackupClass. Application apiGroup defaults to apps.cozystack.io. Velero flow now uses resolved parameters. * **Tests** * Added unit tests for BackupClass resolution, BackupJob/Plan factory, webhook validation, and Velero template rendering. * **Chores** * Manager cache/indexing updated to track BackupClass and index BackupJobs by backupClassName. <sub>✏️ Tip: You can customize this high-level summary in your review settings.</sub> <!-- end of auto-generated comment: release notes by coderabbit.ai -->
2 parents 2812df8 + 73d6e30 commit 71c654b

23 files changed

Lines changed: 1892 additions & 498 deletions

‎api/backups/v1alpha1/DESIGN.md‎

Lines changed: 89 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -100,13 +100,13 @@ Describe **when**, **how**, and **where** to back up a specific managed applicat
100100
```go
101101
type PlanSpec struct {
102102
// Application to back up.
103+
// If apiGroup is not specified, it defaults to "apps.cozystack.io".
103104
ApplicationRef corev1.TypedLocalObjectReference `json:"applicationRef"`
104105

105-
// Where backups should be stored.
106-
StorageRef corev1.TypedLocalObjectReference `json:"storageRef"`
107-
108-
// Driver-specific BackupStrategy to use.
109-
StrategyRef corev1.TypedLocalObjectReference `json:"strategyRef"`
106+
// BackupClassName references a BackupClass that contains strategy and other parameters (e.g. storage reference).
107+
// The BackupClass will be resolved to determine the appropriate strategy and parameters
108+
// based on the ApplicationRef.
109+
BackupClassName string `json:"backupClassName"`
110110

111111
// When backups should run.
112112
Schedule PlanSchedule `json:"schedule"`
@@ -145,12 +145,12 @@ Core Plan controller:
145145
* Create a `BackupJob` in the same namespace:
146146

147147
* `spec.planRef.name = plan.Name`
148-
* `spec.applicationRef = plan.spec.applicationRef`
149-
* `spec.storageRef = plan.spec.storageRef`
150-
* `spec.strategyRef = plan.spec.strategyRef`
151-
* `spec.triggeredBy = "Plan"`
148+
* `spec.applicationRef = plan.spec.applicationRef` (normalized with default apiGroup if not specified)
149+
* `spec.backupClassName = plan.spec.backupClassName`
152150
* Set `ownerReferences` so the `BackupJob` is owned by the `Plan`.
153151

152+
**Note:** The `BackupJob` controller resolves the `BackupClass` to determine the appropriate strategy and parameters, based on the `ApplicationRef`. The strategy template is processed with a context containing the `Application` object and `Parameters` from the `BackupClass`.
153+
154154
The Plan controller does **not**:
155155

156156
* Execute backups itself.
@@ -159,17 +159,64 @@ The Plan controller does **not**:
159159

160160
---
161161

162-
### 4.2 Storage
162+
### 4.2 BackupClass
163+
164+
**Group/Kind**
165+
`backups.cozystack.io/v1alpha1, Kind=BackupClass`
166+
167+
**Purpose**
168+
Define a class of backup configurations that encapsulate strategy and parameters per application type. `BackupClass` is a cluster-scoped resource that allows admins to configure backup strategies and parameters in a reusable way.
169+
170+
**Key fields (spec)**
171+
172+
```go
173+
type BackupClassSpec struct {
174+
// Strategies is a list of backup strategies, each matching a specific application type.
175+
Strategies []BackupClassStrategy `json:"strategies"`
176+
}
177+
178+
type BackupClassStrategy struct {
179+
// StrategyRef references the driver-specific BackupStrategy (e.g., Velero).
180+
StrategyRef corev1.TypedLocalObjectReference `json:"strategyRef"`
181+
182+
// Application specifies which application types this strategy applies to.
183+
// If apiGroup is not specified, it defaults to "apps.cozystack.io".
184+
Application ApplicationSelector `json:"application"`
185+
186+
// Parameters holds strategy-specific parameters, like storage reference.
187+
// Common parameters include:
188+
// - backupStorageLocationName: Name of Velero BackupStorageLocation
189+
// +optional
190+
Parameters map[string]string `json:"parameters,omitempty"`
191+
}
163192

164-
**API Shape**
193+
type ApplicationSelector struct {
194+
// APIGroup is the API group of the application.
195+
// If not specified, defaults to "apps.cozystack.io".
196+
// +optional
197+
APIGroup *string `json:"apiGroup,omitempty"`
198+
199+
// Kind is the kind of the application (e.g., VirtualMachine, MySQL).
200+
Kind string `json:"kind"`
201+
}
202+
```
165203

166-
TBD
204+
**BackupClass resolution**
167205

168-
**Storage usage**
206+
* When a `BackupJob` or `Plan` references a `BackupClass` via `backupClassName`, the controller:
207+
1. Fetches the `BackupClass` by name.
208+
2. Matches the `ApplicationRef` against strategies in the `BackupClass`:
209+
* Normalizes `ApplicationRef.apiGroup` (defaults to `"apps.cozystack.io"` if not specified).
210+
* Finds a strategy where `ApplicationSelector` matches the `ApplicationRef` (apiGroup and kind).
211+
3. Returns the matched `StrategyRef` and `Parameters`.
212+
* Strategy templates (e.g., Velero's `backupTemplate.spec`) are processed with a context containing:
213+
* `Application`: The application object being backed up.
214+
* `Parameters`: The parameters from the matched `BackupClassStrategy`.
169215

170-
* `Plan` and `BackupJob` reference `Storage` via `TypedLocalObjectReference`.
171-
* Drivers read `Storage` to know how/where to store or read artifacts.
172-
* Core treats `Storage` spec as opaque; it does not directly talk to S3 or buckets.
216+
**Parameters**
217+
218+
* Parameters are passed via `Parameters` in the `BackupClass` (e.g., `backupStorageLocationName` for Velero).
219+
* The driver uses these parameters to resolve the actual resources (e.g., Velero's `BackupStorageLocation` CRD).
173220

174221
---
175222

@@ -189,16 +236,13 @@ type BackupJobSpec struct {
189236
PlanRef *corev1.LocalObjectReference `json:"planRef,omitempty"`
190237

191238
// Application to back up.
239+
// If apiGroup is not specified, it defaults to "apps.cozystack.io".
192240
ApplicationRef corev1.TypedLocalObjectReference `json:"applicationRef"`
193241

194-
// Storage to use.
195-
StorageRef corev1.TypedLocalObjectReference `json:"storageRef"`
196-
197-
// Driver-specific BackupStrategy to use.
198-
StrategyRef corev1.TypedLocalObjectReference `json:"strategyRef"`
199-
200-
// Informational: what triggered this run ("Plan", "Manual", etc.).
201-
TriggeredBy string `json:"triggeredBy,omitempty"`
242+
// BackupClassName references a BackupClass that contains strategy and related parameters
243+
// The BackupClass will be resolved to determine the appropriate strategy and parameters
244+
// based on the ApplicationRef.
245+
BackupClassName string `json:"backupClassName"`
202246
}
203247
```
204248

@@ -223,7 +267,9 @@ type BackupJobStatus struct {
223267
* Each driver controller:
224268

225269
* Watches `BackupJob`.
226-
* Reconciles runs where `spec.strategyRef.apiGroup/kind` matches its **strategy type(s)**.
270+
* Resolves the `BackupClass` referenced by `spec.backupClassName`.
271+
* Matches the `ApplicationRef` against strategies in the `BackupClass` to find the appropriate strategy.
272+
* Reconciles runs where the resolved strategy's `apiGroup/kind` matches its **strategy type(s)**.
227273
* Driver responsibilities:
228274

229275
1. On first reconcile:
@@ -232,7 +278,12 @@ type BackupJobStatus struct {
232278
* Set `status.phase = Running`.
233279
2. Resolve inputs:
234280

235-
* Read `Strategy` (driver-owned CRD), `Storage`, `Application`, optionally `Plan`.
281+
* Resolve `BackupClass` from `spec.backupClassName`.
282+
* Match `ApplicationRef` against `BackupClass` strategies to get `StrategyRef` and `Parameters`.
283+
* Read `Strategy` (driver-owned CRD) from `StrategyRef`.
284+
* Read `Application` from `ApplicationRef`.
285+
* Extract parameters from `Parameters` (e.g., `backupStorageLocationName` for Velero).
286+
* Process strategy template with context: `Application` object and `Parameters` from `BackupClass`.
236287
3. Execute backup logic (implementation-specific).
237288
4. On success:
238289

@@ -264,13 +315,14 @@ Represent a single **backup artifact** for a given application, decoupled from a
264315
type BackupSpec struct {
265316
ApplicationRef corev1.TypedLocalObjectReference `json:"applicationRef"`
266317
PlanRef *corev1.LocalObjectReference `json:"planRef,omitempty"`
267-
StorageRef corev1.TypedLocalObjectReference `json:"storageRef"`
268318
StrategyRef corev1.TypedLocalObjectReference `json:"strategyRef"`
269319
TakenAt metav1.Time `json:"takenAt"`
270320
DriverMetadata map[string]string `json:"driverMetadata,omitempty"`
271321
}
272322
```
273323

324+
**Note:** Parameters are not stored directly in `Backup`. Instead, they are resolved from `BackupClass` parameters when the backup was created. The storage location is managed by the driver (e.g., Velero's `BackupStorageLocation`) and referenced via parameters in the `BackupClass`.
325+
274326
**Key fields (status)**
275327

276328
```go
@@ -290,7 +342,8 @@ type BackupStatus struct {
290342
* Creates a `Backup` in the same namespace (typically owned by the `BackupJob`).
291343
* Populates `spec` fields with:
292344

293-
* The application, storage, strategy references.
345+
* The application reference.
346+
* The strategy reference (resolved from `BackupClass` during `BackupJob` execution).
294347
* `takenAt`.
295348
* Optional `driverMetadata`.
296349
* Sets `status` with:
@@ -306,6 +359,8 @@ type BackupStatus struct {
306359
* Anchor `RestoreJob` operations.
307360
* Implement higher-level policies (retention) if needed.
308361

362+
**Note:** Parameters are resolved from `BackupClass` when the `BackupJob` is created. The driver uses these parameters to determine where to store backups. The storage location itself is managed by the driver (e.g., Velero's `BackupStorageLocation` CRD) and is not directly referenced in the `Backup` resource. When restoring, the driver resolves the storage location from the original `BackupClass` parameters or from the driver's own metadata.
363+
309364
---
310365

311366
### 4.5 RestoreJob
@@ -353,13 +408,13 @@ type RestoreJobStatus struct {
353408
* Determines effective:
354409

355410
* **Strategy**: `backup.spec.strategyRef`.
356-
* **Storage**: `backup.spec.storageRef`.
411+
* **Storage**: Resolved from driver metadata or `BackupClass` parameters (e.g., `backupStorageLocationName` stored in `driverMetadata` or resolved from the original `BackupClass`).
357412
* **Target application**: `spec.targetApplicationRef` or `backup.spec.applicationRef`.
358413
* If effective strategy’s GVK is one of its supported strategy types → driver is responsible.
359414
3. Behaviour:
360415

361416
* On first reconcile, set `status.startedAt` and `phase = Running`.
362-
* Resolve `Backup`, `Storage`, `Strategy`, target application.
417+
* Resolve `Backup`, storage location (from driver metadata or `BackupClass`), `Strategy`, target application.
363418
* Execute restore logic (implementation-specific).
364419
* On success:
365420

@@ -414,8 +469,10 @@ The Cozystack backups core API:
414469
* Uses a single group, `backups.cozystack.io`, for all core CRDs.
415470
* Cleanly separates:
416471

417-
* **When & where** (Plan + Storage) – core-owned.
472+
* **When** (Plan schedule) – core-owned.
473+
* **How & where** (BackupClass) – central configuration unit that encapsulates strategy and parameters (e.g., storage reference) per application type, resolved per BackupJob/Plan.
474+
* **Execution** (BackupJob) – created by Plan when schedule fires, resolves BackupClass to get strategy and parameters, then delegates to driver.
418475
* **What backup artifacts exist** (Backup) – driver-created but cluster-visible.
419-
* **Execution lifecycle** (BackupJob, RestoreJob) – shared contract boundary.
476+
* **Restore lifecycle** (RestoreJob) – shared contract boundary.
420477
* Allows multiple strategy drivers to implement backup/restore logic without entangling their implementation with the core API.
421478

‎api/backups/v1alpha1/backup_types.go‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -57,13 +57,10 @@ type BackupSpec struct {
5757
// +optional
5858
PlanRef *corev1.LocalObjectReference `json:"planRef,omitempty"`
5959

60-
// StorageRef refers to the Storage object that describes where the backup
61-
// artifact is stored.
62-
StorageRef corev1.TypedLocalObjectReference `json:"storageRef"`
63-
6460
// StrategyRef refers to the driver-specific BackupStrategy that was used
6561
// to create this backup. This allows the driver to later perform restores.
66-
StrategyRef corev1.TypedLocalObjectReference `json:"strategyRef"`
62+
// This references a cluster-scoped resource, so it does not include a namespace.
63+
StrategyRef TypedClusterObjectReference `json:"strategyRef"`
6764

6865
// TakenAt is the time at which the backup was taken (as reported by the
6966
// driver). It may differ slightly from metadata.creationTimestamp.
Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
// SPDX-License-Identifier: Apache-2.0
2+
// Package v1alpha1 defines backups.cozystack.io API types.
3+
//
4+
// Group: backups.cozystack.io
5+
// Version: v1alpha1
6+
package v1alpha1
7+
8+
import (
9+
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
10+
"k8s.io/apimachinery/pkg/runtime"
11+
)
12+
13+
func init() {
14+
SchemeBuilder.Register(func(s *runtime.Scheme) error {
15+
s.AddKnownTypes(GroupVersion,
16+
&BackupClass{},
17+
&BackupClassList{},
18+
)
19+
return nil
20+
})
21+
}
22+
23+
// +kubebuilder:object:root=true
24+
// +kubebuilder:resource:scope=Cluster
25+
// +kubebuilder:subresource:status
26+
27+
// BackupClass defines a class of backup configurations that can be referenced
28+
// by BackupJob and Plan resources. It encapsulates strategy and storage configuration
29+
// per application type.
30+
type BackupClass struct {
31+
metav1.TypeMeta `json:",inline"`
32+
metav1.ObjectMeta `json:"metadata,omitempty"`
33+
34+
Spec BackupClassSpec `json:"spec,omitempty"`
35+
Status BackupClassStatus `json:"status,omitempty"`
36+
}
37+
38+
// +kubebuilder:object:root=true
39+
40+
// BackupClassList contains a list of BackupClasses.
41+
type BackupClassList struct {
42+
metav1.TypeMeta `json:",inline"`
43+
metav1.ListMeta `json:"metadata,omitempty"`
44+
Items []BackupClass `json:"items"`
45+
}
46+
47+
// BackupClassSpec defines the desired state of a BackupClass.
48+
type BackupClassSpec struct {
49+
// Strategies is a list of backup strategies, each matching a specific application type.
50+
Strategies []BackupClassStrategy `json:"strategies"`
51+
}
52+
53+
// BackupClassStrategy defines a backup strategy for a specific application type.
54+
type BackupClassStrategy struct {
55+
// StrategyRef references the driver-specific BackupStrategy (e.g., Velero).
56+
// This references a cluster-scoped resource, so it does not include a namespace.
57+
StrategyRef TypedClusterObjectReference `json:"strategyRef"`
58+
59+
// Application specifies which application types this strategy applies to.
60+
Application ApplicationSelector `json:"application"`
61+
62+
// Parameters holds strategy-specific and storage-specific parameters.
63+
// Common parameters include:
64+
// - backupStorageLocationName: Name of Velero BackupStorageLocation
65+
// +optional
66+
Parameters map[string]string `json:"parameters,omitempty"`
67+
}
68+
69+
// TypedClusterObjectReference contains enough information to let you locate a
70+
// cluster-scoped typed resource. It does not include a namespace because
71+
// cluster-scoped resources do not have namespaces.
72+
type TypedClusterObjectReference struct {
73+
// APIGroup is the group for the resource being referenced.
74+
// If APIGroup is not specified, the specified Kind must be in the core API group.
75+
// For any other third-party types, APIGroup is required.
76+
// +optional
77+
APIGroup *string `json:"apiGroup,omitempty"`
78+
79+
// Kind is the type of resource being referenced.
80+
Kind string `json:"kind"`
81+
82+
// Name is the name of resource being referenced.
83+
Name string `json:"name"`
84+
}
85+
86+
// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
87+
func (in *TypedClusterObjectReference) DeepCopyInto(out *TypedClusterObjectReference) {
88+
*out = *in
89+
if in.APIGroup != nil {
90+
in, out := &in.APIGroup, &out.APIGroup
91+
*out = new(string)
92+
**out = **in
93+
}
94+
}
95+
96+
// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new TypedClusterObjectReference.
97+
func (in *TypedClusterObjectReference) DeepCopy() *TypedClusterObjectReference {
98+
if in == nil {
99+
return nil
100+
}
101+
out := new(TypedClusterObjectReference)
102+
in.DeepCopyInto(out)
103+
return out
104+
}
105+
106+
// ApplicationSelector specifies which application types a strategy applies to.
107+
type ApplicationSelector struct {
108+
// APIGroup is the API group of the application.
109+
// If not specified, defaults to "apps.cozystack.io".
110+
// +optional
111+
APIGroup *string `json:"apiGroup,omitempty"`
112+
113+
// Kind is the kind of the application (e.g., VirtualMachine, MySQL).
114+
Kind string `json:"kind"`
115+
}
116+
117+
// BackupClassStatus defines the observed state of a BackupClass.
118+
type BackupClassStatus struct {
119+
// Conditions represents the latest available observations of a BackupClass's state.
120+
// +optional
121+
Conditions []metav1.Condition `json:"conditions,omitempty"`
122+
}

0 commit comments

Comments
 (0)