sequenceDiagram
    participant Controller as BackupJobReconciler
    participant BackupAPI as BackupStatus<br/>(API Object)
    participant Serializer as Runtime<br/>Serialization
    participant Velero as Velero<br/>Backup System

    rect rgba(100,150,200,0.5)
    Note over Controller,Velero: Backup Phase
    Controller->>Controller: collectUnderlyingResources()
    Controller->>Controller: build vmInstanceResources (DataVolumes, IP, MAC) + TypeMeta
    Controller->>Serializer: marshalUnderlyingResources() -> JSON
    Serializer-->>Controller: runtime.RawExtension (opaque)
    Controller->>BackupAPI: store UnderlyingResources = RawExtension
    Controller->>Velero: create Velero Backup (annotation = RawExtension JSON)
    end

    rect rgba(150,200,150,0.5)
    Note over Controller,Velero: Restore Phase
    Controller->>BackupAPI: read Backup.status.UnderlyingResources (RawExtension)
    Controller->>Serializer: getVMInstanceResources(RawExtension) -> vmInstanceResources
    Serializer-->>Controller: VM fields (DataVolumes, IP, MAC)
    Controller->>Controller: createResourceModifiersConfigMap(..., ur)
    Controller->>Velero: create Velero Restore (resource modifiers)
    end

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Suggestion: simplify UnderlyingResources from map[string]runtime.RawExtension to *runtime.RawExtension

Looking at the changes in api/backups/v1alpha1/backup_types.go and how UnderlyingResources is consumed in internal/backupcontroller/velerostrategy_controller.go, the map-based design seems like unnecessary indirection. A single *runtime.RawExtension with an inlined TypeMeta would be cleaner.

Current design

UnderlyingResources map[string]runtime.RawExtension `json:"underlyingResources,omitempty"`

• The map key is always applicationRef.Kind — which is already available in spec.applicationRef.kind. This makes the key redundant (a third copy of the same information).
• In practice there is only ever one entry in the map (vmInstanceKind). A map-of-one is unnecessary indirection.
• Consumer code (getVMInstanceResources) does ur[vmInstanceKind] — a stringly-typed dispatch on a key that duplicates information already present elsewhere in the object.

Proposed design

// +optional
// +kubebuilder:pruning:PreserveUnknownFields
UnderlyingResources *runtime.RawExtension `json:"underlyingResources,omitempty"`

The JSON payload would carry its own type information via an inlined TypeMeta:

{
  "kind": "VMInstance",
  "apiVersion": "apps.cozystack.io/v1alpha1",
  "dataVolumes": [...],
  "ip": "10.0.0.5",
  "mac": "00:11:22:33:44:55"
}

Consumer code would first peek at the type, then unmarshal into the correct struct:

// Step 1: peek at the type
type typedResource struct {
    metav1.TypeMeta `json:",inline"`
}
var tr typedResource
json.Unmarshal(backup.Status.UnderlyingResources.Raw, &tr)

// Step 2: dispatch on tr.Kind
switch tr.Kind {
case "VMInstance":
    var res vmInstanceResources
    json.Unmarshal(backup.Status.UnderlyingResources.Raw, &res)
    // ...
}

Advantages

1. No redundancy — the kind is self-described in the payload and already on spec.applicationRef.kind. The map key was a third copy of the same information.
2. Simpler schema — a nullable opaque blob is easier to reason about (and to validate / document) than a map of opaque blobs.
3. Extensible — adding a new application kind just means defining a new struct with TypeMeta embedded; no map-key convention to document or enforce.
4. Kubernetes-idiomatic — this mirrors how runtime.RawExtension is used elsewhere in the K8s ecosystem (e.g., AdmissionReview.request.object, webhook configurations, etc.).

Trade-off to consider

The map technically allows multiple underlying resource kinds per backup. However, applicationRef already points to a single kind, and collectUnderlyingResources only ever produces one entry, so this capability is unused. If composite apps ever need multiple resource kinds, a []runtime.RawExtension list (each element self-typed) would be a better fit than a map[string]runtime.RawExtension anyway.

Impact on marshalUnderlyingResources / getVMInstanceResources

Both helpers become simpler — marshalUnderlyingResources just serializes the struct directly (with TypeMeta set), and getVMInstanceResources peeks at the kind before unmarshaling. The fallback path in resolveUnderlyingResourcesForRestore (annotation-based) would also be simplified since the annotation would store a single JSON object instead of a map.