velero/design/Implemented/resource-status-restore.md

Allow Object-Level Resource Status Restore in Velero

Abstract

This design proposes a way to enhance Velero’s restore functionality by enabling object-level resource status restoration through annotations. Currently, Velero allows restoring resource statuses only at a resource type level, which lacks granularity of restoring the status of specific resources. By introducing an annotation that controllers can set on individual resource objects, this design aims to improve flexibility and autonomy for users/resource-controllers, providing a more way to enable resource status restore.

Background

Velero provides the restoreStatus field in the Restore API to specify resource types for status restoration. However, this feature is limited to resource types as a whole, lacking the granularity needed to restore specific objects of a resource type. Resource controllers, especially those managing custom resources with external dependencies, may need to restore status on a per-object basis based on internal logic and dependencies.

This design adds an annotation-based approach to allow controllers to specify status restoration at the object level, enabling Velero to handle status restores more flexibly.

Goals

• Provide a mechanism to specify the restoration of a resource’s status at an object level.
• Maintain backwards compatibility with existing functionality, allowing gradual adoption of this feature.
• Integrate the new annotation-based objects-level status restore with Velero’s existing resource-type-level restoreStatus configuration.

Non-Goals

• Alter Velero’s existing resource type-level status restoration mechanism for resources without annotations.

Use-Cases/Scenarios

1. Controller managing specific Resources

• A resource controller identifies that a specific object of a resource should have its status restored due to particular dependencies
• The controller automatically sets the velero.io/restore-status: true annotation on the resource.
• During restore, Velero restores the status of this object, while leaving other resources unaffected.
• The status for the annotated object will be restored regardless of its inclusion/exclusion in restoreStatus.includedResources

2. A specific object must not have its status restored even if its included in restoreStatus.includedResources

• A user specifies a resource type in the restoreStatus.includedResources field within the Restore custom resource.
• A particular object of that resource type is annotated with velero.io/restore-status: false by the user.
• The status of the annotated object will not restored even though its included in restoreStatus.includedResources because annotation is false and it takes precedence.

4. Default Behavior for objects Without the Annotation

• Objects without the velero.io/restore-status annotation behave as they currently do: Velero skips their status restoration unless the resource type is specified in the restoreStatus.includedResources field.

High-Level Design

• Object-Level Status Restore Annotation: We are introducing the velero.io/restore-status annotation at the resource object level to mark specific objects for status restoration.

  • true: Indicates that the status should be restored for this object
  • false: Skip restoring status for this specific object
  • Invalid or missing annotations defer to the meaning of existing resource type-level logic.

• Restore logic precedence:

  • Annotations take precedence when they exist with valid values (true or false).
  • Restore spec restoreStatus.includedResources is only used when annotations are invalid or missing.

• Velero Restore Logic Update: During a restore operation, Velero will:

  • Extend the existing restore logic to parse and prioritize annotations introduced in this design.
  • Update resource objects accordingly based on their annotation values or fallback configuration.

Detailed Design

• Annotation for object-Level Status Restore: The velero.io/restore-status annotation will be set on individual resource objects by users/controllers as needed:

metadata:
  annotations:
    velero.io/restore-status: "true"

• Restore Logic Modifications: During the restore operation, the restore controller will follow these steps:
  • Parse the restoreStatus.includedResources spec to determine resource types eligible for status restoration.
  • For each resource object:
    • Check for the velero.io/restore-status annotation.
    • If the annotation value is:
      • true: Restore the status of the object
      • false: Skip restoring the status of the object
    • If the annotation is invalid or missing:
      • Default to the restoreStatus.includedResources configuration

Implementation

We are targeting the implementation of this design for Velero 1.16 release.

Current restoreStatus logic resides here: 32a8c62920/pkg/restore/restore.go (L1652)

The modified logic would look somewhat like:

// Determine whether to restore status from resource type configuration
shouldRestoreStatus := ctx.resourceStatusIncludesExcludes != nil && ctx.resourceStatusIncludesExcludes.ShouldInclude(groupResource.String())

// Check for object-level annotation
annotations := obj.GetAnnotations()
objectAnnotation := annotations["velero.io/restore-status"]
annotationValid := objectAnnotation == "true" || objectAnnotation == "false"

// Determine restore behavior based on annotation precedence
shouldRestoreStatus = (annotationValid && objectAnnotation == "true") || (!annotationValid && shouldRestoreStatus)

ctx.log.Debugf("status field for %s: exists: %v, should restore: %v (by annotation: %v)", newGR, statusFieldExists, shouldRestoreStatus, annotationValid)

if shouldRestoreStatus && statusFieldExists {
    if err := unstructured.SetNestedField(obj.Object, objStatus, "status"); err != nil {
        ctx.log.Errorf("Could not set status field %s: %v", kube.NamespaceAndName(obj), err)
        errs.Add(namespace, err)
        return warnings, errs, itemExists
    }
    obj.SetResourceVersion(createdObj.GetResourceVersion())
    updated, err := resourceClient.UpdateStatus(obj, metav1.UpdateOptions{})
    if err != nil {
        ctx.log.Infof("Status field update failed %s: %v", kube.NamespaceAndName(obj), err)
        warnings.Add(namespace, err)
	} else {
        createdObj = updated
    }
}