CNTRLPLANE-2685, CNTRLPLANE-2707: integrate HCPEtcdBackup lifecycle into OADP backup flow (#238)

* fix(deps): update hypershift API to latest main

Update github.com/openshift/hypershift/api to v0.0.0-20260406110001-bcf6adaf131f.
This brings in the HCPEtcdBackup CRD types, HCPEtcdBackupConfig in
ManagedEtcdSpec.Backup, and related condition/reason constants needed
for CNTRLPLANE-2685 integration.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Juan Manuel Parrilla Madrid <jparrill@redhat.com>

* feat(backup): integrate HCPEtcdBackup lifecycle into OADP backup flow

Add etcdSnapshot backup method that creates and monitors HCPEtcdBackup CRs
during Velero backup. When etcdBackupMethod=etcdSnapshot is configured in the
plugin ConfigMap, the plugin:

- Creates an HCPEtcdBackup CR in the HCP namespace using BSL storage config
- Copies BSL credentials to the HO namespace (remapping key for controller)
- Polls the CR until backup completes or fails
- Excludes etcd pods and PVCs from Velero backup (no CSI/FS backup needed)
- Stores the etcd snapshot alongside the Velero backup data in the BSL

The default method remains volumeSnapshot (unchanged behavior).

Also cleans up dead config parameters (readoptNodes, managedServices,
awsRegenPrivateLink) and registers apiextensionsv1 in the scheme for
CRD existence checks.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Juan Manuel Parrilla Madrid <jparrill@redhat.com>

* docs: add HCPEtcdBackup implementation reference

Document the full HCPEtcdBackup integration including architecture,
backup/restore flows, configuration, credential handling, storage layout,
dependency chain (PRs #8139, #8010, #8017, #8040, #8114, enhancement #1945),
and troubleshooting guide.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Juan Manuel Parrilla Madrid <jparrill@redhat.com>

* test: add comprehensive unit tests for etcd backup orchestrator and validation

Cover Execute paths for all item kinds, orchestrator lifecycle
(CreateEtcdBackup, VerifyInProgress, WaitForCompletion), and
platform validation for both backup and restore validators.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Juan Manuel Parrilla Madrid <jparrill@redhat.com>

---------

Signed-off-by: Juan Manuel Parrilla Madrid <jparrill@redhat.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: jparrill

docs/references/HCPEtcdBackup/HCPEtcdBackup-implementation.md

@@ -8,7 +8,7 @@ require (
 	github.com/kubernetes-csi/external-snapshotter/client/v8 v8.4.0
 	github.com/onsi/gomega v1.39.1
 	github.com/openshift/hive/apis v0.0.0-20241220022629-3f49f26197ff
-	github.com/openshift/hypershift/api v0.0.0-20260317154635-8eaac177f1b0
+	github.com/openshift/hypershift/api v0.0.0-20260410203959-783f7956d4f9
 	github.com/sirupsen/logrus v1.9.4
 	github.com/vmware-tanzu/velero v1.14.0
 	k8s.io/api v0.35.3
@@ -26,7 +26,7 @@ require (
 	github.com/google/gnostic-models v0.7.0 // indirect
 	github.com/google/go-cmp v0.7.0 // indirect
 	github.com/google/uuid v1.6.0 // indirect
-	github.com/openshift/api v0.0.0-20260120150926-4c643a652d54 // indirect
+	github.com/openshift/api v0.0.0-20260304122341-cf5d8996109f // indirect
 	github.com/openshift/custom-resource-status v1.1.3-0.20220503160415-f2fdb4999d87 // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
 	github.com/prometheus/client_golang v1.23.2 // indirect

go.mod

@@ -192,23 +192,23 @@ github.com/onsi/ginkgo v1.14.0/go.mod h1:iSB4RoI2tjJc9BBv4NKIKWKya62Rps+oPG/Lv9k
 github.com/onsi/ginkgo v1.16.4 h1:29JGrr5oVBm5ulCWet69zQkzWipVXIol6ygQUe/EzNc=
 github.com/onsi/ginkgo v1.16.4/go.mod h1:dX+/inL/fNMqNlz0e9LfyB9TswhZpCVdJM/Z6Vvnwo0=
 github.com/onsi/ginkgo/v2 v2.0.0/go.mod h1:vw5CSIxN1JObi/U8gcbwft7ZxR2dgaR70JSE3/PpL4c=
-github.com/onsi/ginkgo/v2 v2.28.0 h1:Rrf+lVLmtlBIKv6KrIGJCjyY8N36vDVcutbGJkyqjJc=
-github.com/onsi/ginkgo/v2 v2.28.0/go.mod h1:ArE1D/XhNXBXCBkKOLkbsb2c81dQHCRcF5zwn/ykDRo=
+github.com/onsi/ginkgo/v2 v2.28.1 h1:S4hj+HbZp40fNKuLUQOYLDgZLwNUVn19N3Atb98NCyI=
+github.com/onsi/ginkgo/v2 v2.28.1/go.mod h1:CLtbVInNckU3/+gC8LzkGUb9oF+e8W8TdUsxPwvdOgE=
 github.com/onsi/gomega v0.0.0-20170829124025-dcabb60a477c/go.mod h1:C1qb7wdrVGGVU+Z6iS04AVkA3Q65CEZX59MT0QO5uiA=
 github.com/onsi/gomega v1.7.1/go.mod h1:XdKZgCCFLUoM/7CFJVPcG8C1xQ1AJ0vpAezJrB7JYyY=
 github.com/onsi/gomega v1.10.1/go.mod h1:iN09h71vgCQne3DLsj+A5owkum+a2tYe+TOCB1ybHNo=
 github.com/onsi/gomega v1.17.0/go.mod h1:HnhC7FXeEQY45zxNK3PPoIUhzk/80Xly9PcubAlGdZY=
 github.com/onsi/gomega v1.18.1/go.mod h1:0q+aL8jAiMXy9hbwj2mr5GziHiwhAIQpFmmtT5hitRs=
 github.com/onsi/gomega v1.39.1 h1:1IJLAad4zjPn2PsnhH70V4DKRFlrCzGBNrNaru+Vf28=
 github.com/onsi/gomega v1.39.1/go.mod h1:hL6yVALoTOxeWudERyfppUcZXjMwIMLnuSfruD2lcfg=
-github.com/openshift/api v0.0.0-20260120150926-4c643a652d54 h1:Gm81lfkiXFgg/N0x90WsplERGF2NqYjK0vd8YY/aFpU=
-github.com/openshift/api v0.0.0-20260120150926-4c643a652d54/go.mod h1:d5uzF0YN2nQQFA0jIEWzzOZ+edmo6wzlGLvx5Fhz4uY=
+github.com/openshift/api v0.0.0-20260304122341-cf5d8996109f h1:M8y0oBq/KRkuSNFlUMQRAn2MrXJh1mzTCFgbLpPWQbM=
+github.com/openshift/api v0.0.0-20260304122341-cf5d8996109f/go.mod h1:d5uzF0YN2nQQFA0jIEWzzOZ+edmo6wzlGLvx5Fhz4uY=
 github.com/openshift/custom-resource-status v1.1.3-0.20220503160415-f2fdb4999d87 h1:cHyxR+Y8rAMT6m1jQCaYGRwikqahI0OjjUDhFNf3ySQ=
 github.com/openshift/custom-resource-status v1.1.3-0.20220503160415-f2fdb4999d87/go.mod h1:DB/Mf2oTeiAmVVX1gN+NEqweonAPY0TKUwADizj8+ZA=
 github.com/openshift/hive/apis v0.0.0-20241220022629-3f49f26197ff h1:6C1z4xMAruyeiTFGqahxNDpI1cXPCjpaFeIeIodty08=
 github.com/openshift/hive/apis v0.0.0-20241220022629-3f49f26197ff/go.mod h1:1vBNCcWNpQyFCz83PWYT/lHUFJ9ost2t5FijHElh6gQ=
-github.com/openshift/hypershift/api v0.0.0-20260317154635-8eaac177f1b0 h1:x5DgHyFXF9zpgTH4JYDpBhQnASEIj6z1WXdeHl1DGAI=
-github.com/openshift/hypershift/api v0.0.0-20260317154635-8eaac177f1b0/go.mod h1:eYDwJzXCU+0HO9DdvhBAA143z7woIJ5dV71TaJXIkgk=
+github.com/openshift/hypershift/api v0.0.0-20260410203959-783f7956d4f9 h1:mVzLud8ewZi1W8dnV37L+eY9IJsoFfpkASgPvDRM61Q=
+github.com/openshift/hypershift/api v0.0.0-20260410203959-783f7956d4f9/go.mod h1:mC9+bqb81FmG924VOO+7P0ofKQgvY1SdPhFp0oJ9U44=
 github.com/openshift/velero v0.10.2-0.20260323170432-5ef912f438f6 h1:nWv9+tEi34VMFMOziVZLOKvn3yXDqk68ODXlzpYU2S0=
 github.com/openshift/velero v0.10.2-0.20260323170432-5ef912f438f6/go.mod h1:YKHPM2FpS+5WrcciMi5j4bo/JMnXXrR1M+j1DoTA26U=
 github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=

go.sum

@@ -7,6 +7,7 @@ import (
 	veleroapiv1 "github.com/vmware-tanzu/velero/pkg/apis/velero/v1"
 	veleroapiv2alpha1 "github.com/vmware-tanzu/velero/pkg/apis/velero/v2alpha1"
 	corev1 "k8s.io/api/core/v1"
+	apiextensionsv1 "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1"
 	"k8s.io/apimachinery/pkg/runtime"
 )
 
@@ -35,6 +36,9 @@ func init() {
 	if err := hive.AddToScheme(CustomScheme); err != nil {
 		errs = append(errs, err)
 	}
+	if err := apiextensionsv1.AddToScheme(CustomScheme); err != nil {
+		errs = append(errs, err)
+	}
 
 	if len(errs) > 0 {
 		panic(errs)

pkg/common/scheme.go

@@ -16,6 +16,9 @@ const (
 
 	// Integration with Hypershift, more info here: https://github.com/openshift/hypershift/pull/6195
 	HostedClusterRestoredFromBackupAnnotation string = "hypershift.openshift.io/restored-from-backup"
+	// Etcd snapshot URL annotation: set during backup so the restore plugin can read it
+	// (Velero strips status from items during restore, so we persist it as an annotation)
+	EtcdSnapshotURLAnnotation string = "hypershift.openshift.io/etcd-snapshot-url"
 
 	// hypershift/cluster-api kinds
 	HostedClusterKind         string = "HostedCluster"
@@ -25,6 +28,25 @@ const (
 	PersistentVolumeClaimKind string = "PersistentVolumeClaim"
 	ClusterDeploymentKind     string = "ClusterDeployment"
 	DataVolumeKind            string = "DataVolume"
+	HCPEtcdBackupKind         string = "HCPEtcdBackup"
+
+	// Default HyperShift Operator namespace
+	DefaultHONamespace string = "hypershift"
+	// ConfigMap key to override the HO namespace
+	ConfigKeyHONamespace string = "hoNamespace"
+
+	// Etcd backup method configuration
+	ConfigKeyEtcdBackupMethod    string = "etcdBackupMethod"
+	EtcdBackupMethodVolume       string = "volumeSnapshot"
+	EtcdBackupMethodEtcdSnapshot string = "etcdSnapshot"
+
+	// Velero annotation to exclude specific volumes from backup
+	BackupVolumesExcludesAnnotation string = "backup.velero.io/backup-volumes-excludes"
+	// Etcd data volume name in the StatefulSet pod
+	EtcdDataVolumeName string = "data"
+	// Etcd PVC name prefix (StatefulSet pattern: {volumeName}-{stsName}-{index})
+	EtcdPVCPrefix string = "data-etcd-"
+
 )
 
 var (

pkg/common/types.go

@@ -2,6 +2,7 @@ package common
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -163,6 +164,32 @@ func GetHCPNamespace(name, namespace string) string {
 	return fmt.Sprintf("%s-%s", namespace, name)
 }
 
+// GetHostedCluster finds the HostedCluster that owns the HCP by deriving
+// its namespace and name from the HCP namespace convention: {hc-namespace}-{hc-name}.
+func GetHostedCluster(ctx context.Context, c crclient.Client, includedNamespaces []string, hcpNamespace string) (*hyperv1.HostedCluster, error) {
+	var errs []error
+	for _, ns := range includedNamespaces {
+		if ns == hcpNamespace {
+			continue
+		}
+		hcList := &hyperv1.HostedClusterList{}
+		if err := c.List(ctx, hcList, crclient.InNamespace(ns)); err != nil {
+			errs = append(errs, fmt.Errorf("list HostedClusters in namespace %s: %w", ns, err))
+			continue
+		}
+		for i := range hcList.Items {
+			hc := &hcList.Items[i]
+			if GetHCPNamespace(hc.Name, hc.Namespace) == hcpNamespace {
+				return hc, nil
+			}
+		}
+	}
+	if len(errs) > 0 {
+		return nil, errors.Join(errs...)
+	}
+	return nil, nil
+}
+
 // ShouldEndPluginExecution checks if the plugin should end execution by verifying if the required
 // Hypershift resources (HostedControlPlane and HostedCluster) exist in the cluster.
 // Returns true if the plugin should end execution (i.e., if this is not a Hypershift cluster).

pkg/common/utils.go

@@ -573,6 +573,34 @@ func TestShouldEndPluginExecution(t *testing.T) {
 	}
 }
 
+func TestGetHostedCluster(t *testing.T) {
+	scheme := runtime.NewScheme()
+	_ = hyperv1.AddToScheme(scheme)
+
+	t.Run("When GetHostedCluster runs with a HostedCluster matching HCP namespace, It Should return that cluster", func(t *testing.T) {
+		g := NewWithT(t)
+		hc := &hyperv1.HostedCluster{
+			ObjectMeta: metav1.ObjectMeta{Name: "my-cluster", Namespace: "clusters"},
+		}
+		c := fake.NewClientBuilder().WithScheme(scheme).WithObjects(hc).Build()
+
+		result, err := GetHostedCluster(context.TODO(), c, []string{"clusters", "clusters-my-cluster"}, "clusters-my-cluster")
+		g.Expect(err).NotTo(HaveOccurred())
+		g.Expect(result).NotTo(BeNil())
+		g.Expect(result.Name).To(Equal("my-cluster"))
+		g.Expect(result.Namespace).To(Equal("clusters"))
+	})
+
+	t.Run("When GetHostedCluster runs with no HostedClusters in client, It Should return nil", func(t *testing.T) {
+		g := NewWithT(t)
+		c := fake.NewClientBuilder().WithScheme(scheme).Build()
+
+		result, err := GetHostedCluster(context.TODO(), c, []string{"clusters", "clusters-my-cluster"}, "clusters-my-cluster")
+		g.Expect(err).NotTo(HaveOccurred())
+		g.Expect(result).To(BeNil())
+	})
+}
+
 func TestCRDExists(t *testing.T) {
 	scheme := runtime.NewScheme()
 	_ = hyperv1.AddToScheme(scheme)