From 8f00fbd076835c1054afc0f711c47f854893106d Mon Sep 17 00:00:00 2001 From: Todd Short Date: Tue, 10 Nov 2026 14:44:24 -0500 Subject: [PATCH 01/10] refactor: require COD for operator migration Remove direct COS creation and CRD-based mode selection. Require an established, non-deleting COD CRD during readiness and migration preflight, failing before OLMv0 mutations when support is missing or unreadable. Always stage resources through a COD and wait for its rollout before creating the ClusterExtension. Update dry-run output, recovery tests, E2E ownership assertions, and specifications for the COD-only path while preserving existing public method names. Validation: unit coverage, lint, E2E compilation, and fresh-kind adoption and COD rollback tests passed. Signed-off-by: Todd Short --- .../cmd/migrate-operators-v0-to-v1/convert.go | 19 +-- .../convert_test.go | 2 +- .../dryrun_eligibility_test.go | 4 +- .../pkg/migration/create_rejection_test.go | 96 +++++------ migration/pkg/migration/deployment.go | 30 ++-- migration/pkg/migration/deployment_test.go | 81 ++++++---- migration/pkg/migration/migration.go | 139 +++++----------- migration/pkg/migration/readiness.go | 27 ++-- migration/pkg/migration/revision_schema.go | 56 +------ .../pkg/migration/revision_schema_test.go | 4 +- migration/pkg/migration/scan.go | 4 +- .../pkg/migration/system_namespace_test.go | 5 +- migration/pkg/migration/types.go | 29 ++-- migration/pkg/migration/unit_test.go | 152 ++++++++++-------- specs/20260821-migration-v0-to-v1/e2e.md | 29 ++-- specs/20260821-migration-v0-to-v1/plan.md | 20 +-- .../requirements.md | 23 ++- .../20260821-migration-v0-to-v1/validation.md | 28 ++-- test/e2e/migration/e2e_test.go | 60 ++++--- 19 files changed, 343 insertions(+), 465 deletions(-) diff --git a/migration/examples/cmd/migrate-operators-v0-to-v1/convert.go b/migration/examples/cmd/migrate-operators-v0-to-v1/convert.go index c4c1b02..5c1339a 100644 --- a/migration/examples/cmd/migrate-operators-v0-to-v1/convert.go +++ b/migration/examples/cmd/migrate-operators-v0-to-v1/convert.go @@ -245,20 +245,17 @@ func runConvertDryRun(cmd *cobra.Command, m *migration.Migrator, opts migration. return output.dryRunPreview(opts, resourceOpts, info) } +// dryRunRecord describes planned COD staging and resource changes without mutating the cluster. func dryRunRecord(opts, resourceOpts migration.Options, info *migration.MigrationInfo) outputRecord { kindCounts := make(map[string]int) for _, obj := range info.CollectedObjects { kindCounts[obj.GetKind()]++ } - cosName, codName := opts.ClusterExtensionName+"-1", "" - if info.UseClusterObjectDeployment { - cosName, codName = "", opts.ClusterExtensionName - } return outputRecord{ Type: "dry-run", Command: "convert", Target: opts.SubscriptionNamespace + "/" + opts.SubscriptionName, Data: dryRunData{ Package: info.PackageName, Version: info.Version, Channel: info.Channel, - ClusterObjectSet: cosName, ClusterObjectDeployment: codName, ClusterExtension: opts.ClusterExtensionName, + ClusterObjectDeployment: opts.ClusterExtensionName, ClusterExtension: opts.ClusterExtensionName, InstallNamespace: resourceOpts.InstallNamespace, SystemNamespace: info.SystemNamespace, ManualApproval: info.ManualApproval, KindCounts: kindCounts, CleanupActions: dryRunCleanupPlan(opts, resourceOpts, info), BackupDirectory: opts.BackupDirectory, @@ -269,17 +266,12 @@ func dryRunRecord(opts, resourceOpts migration.Options, info *migration.Migratio // printDryRunPreview summarizes the planned migration without printing collected resource contents. // Resource kinds are sorted so repeated previews present the same order. func printDryRunPreview(opts, resourceOpts migration.Options, info *migration.MigrationInfo) error { - success(fmt.Sprintf("ClusterObjectSet API established; using operator-controller namespace %s", info.SystemNamespace)) + success(fmt.Sprintf("ClusterObjectDeployment and ClusterObjectSet APIs established; using operator-controller namespace %s", info.SystemNamespace)) success(fmt.Sprintf("Package: %s Version: %s Channel: %s", info.PackageName, info.Version, valueOrDefault(info.Channel, "(default)"))) fmt.Printf("\n Resources that would be created:\n") - if info.UseClusterObjectDeployment { - detail("ClusterObjectDeployment:", fmt.Sprintf("%s (wait for rollout completion and availability before creating the ClusterExtension)", opts.ClusterExtensionName)) - fmt.Printf("\n Resources that would be placed into its template and controller-created COS revisions:\n") - } else { - detail("ClusterObjectSet:", fmt.Sprintf("%s-1 (wait for completion before creating the ClusterExtension)", opts.ClusterExtensionName)) - fmt.Printf("\n Resources that would be placed into ClusterObjectSet %s-1:\n", opts.ClusterExtensionName) - } + detail("ClusterObjectDeployment:", fmt.Sprintf("%s (wait for rollout completion and availability before creating the ClusterExtension)", opts.ClusterExtensionName)) + fmt.Printf("\n Resources that would be placed into its template and controller-created COS revisions:\n") kindCounts := make(map[string]int) for _, obj := range info.CollectedObjects { @@ -326,7 +318,6 @@ type dryRunData struct { Package string `json:"package"` Version string `json:"version"` Channel string `json:"channel,omitempty"` - ClusterObjectSet string `json:"cluster_object_set,omitempty"` ClusterObjectDeployment string `json:"cluster_object_deployment,omitempty"` ClusterExtension string `json:"cluster_extension"` InstallNamespace string `json:"install_namespace"` diff --git a/migration/examples/cmd/migrate-operators-v0-to-v1/convert_test.go b/migration/examples/cmd/migrate-operators-v0-to-v1/convert_test.go index a19a69f..6de209e 100644 --- a/migration/examples/cmd/migrate-operators-v0-to-v1/convert_test.go +++ b/migration/examples/cmd/migrate-operators-v0-to-v1/convert_test.go @@ -56,7 +56,7 @@ func TestDryRunPreviewSortsResourceKinds(t *testing.T) { if result.err != nil { t.Fatal(result.err) } - sections := strings.Split(string(result.output), "Resources that would be placed into ClusterObjectSet widget-1:") + sections := strings.Split(string(result.output), "Resources that would be placed into its template and controller-created COS revisions:") if len(sections) != 6 { t.Fatalf("got %d preview sections, want 5", len(sections)-1) } diff --git a/migration/examples/cmd/migrate-operators-v0-to-v1/dryrun_eligibility_test.go b/migration/examples/cmd/migrate-operators-v0-to-v1/dryrun_eligibility_test.go index 8b9ea0b..9b952ad 100644 --- a/migration/examples/cmd/migrate-operators-v0-to-v1/dryrun_eligibility_test.go +++ b/migration/examples/cmd/migrate-operators-v0-to-v1/dryrun_eligibility_test.go @@ -131,7 +131,9 @@ func TestDryRunRejectsSystemManagedSourceNamespace(t *testing.T) { Status: apiextensionsv1.ConditionTrue, }}}, } - c := fake.NewClientBuilder().WithScheme(scheme).WithObjects(sub, csv, catalog, operatorGroup, cosCRD, ceCRD).Build() + codCRD := cosCRD.DeepCopy() + codCRD.Name = "clusterobjectdeployments.olm.operatorframework.io" + c := fake.NewClientBuilder().WithScheme(scheme).WithObjects(sub, csv, catalog, operatorGroup, cosCRD, codCRD, ceCRD).Build() m := migration.NewMigrator(c, nil) cmd := &cobra.Command{} cmd.SetContext(t.Context()) diff --git a/migration/pkg/migration/create_rejection_test.go b/migration/pkg/migration/create_rejection_test.go index f9850ad..105f446 100644 --- a/migration/pkg/migration/create_rejection_test.go +++ b/migration/pkg/migration/create_rejection_test.go @@ -16,59 +16,51 @@ import ( // TestMigrationCreateRejectionRecovery distinguishes definitive create rejection from ambiguous outcomes before restoring OLMv0. func TestMigrationCreateRejectionRecovery(t *testing.T) { - for _, mode := range []string{"COS", "COD"} { - for _, tc := range []struct { - name string - err error - ambiguous bool - }{ - {name: "forbidden", err: apierrors.NewForbidden(schema.GroupResource{Group: ocv1.GroupVersion.Group, Resource: "revisions"}, "example", errors.New("create denied"))}, - {name: "invalid", err: apierrors.NewInvalid(schema.GroupKind{Group: ocv1.GroupVersion.Group, Kind: mode}, "example", nil)}, - {name: "bad request", err: apierrors.NewBadRequest("rejected")}, - {name: "unauthorized", err: apierrors.NewUnauthorized("rejected")}, - {name: "timeout", err: apierrors.NewTimeoutError("unknown result", 1), ambiguous: true}, - {name: "transport failure", err: errors.New("connection reset"), ambiguous: true}, - } { - t.Run(mode+"/"+tc.name, func(t *testing.T) { - ctx := context.Background() - m := migrationTestClient(t) - if mode == "COD" { - crd := establishedClusterObjectDeploymentCRD() - if err := m.Client.Create(ctx, crd); err != nil { - t.Fatal(err) + for _, tc := range []struct { + name string + err error + ambiguous bool + }{ + {name: "forbidden", err: apierrors.NewForbidden(schema.GroupResource{Group: ocv1.GroupVersion.Group, Resource: "revisions"}, "example", errors.New("create denied"))}, + {name: "invalid", err: apierrors.NewInvalid(schema.GroupKind{Group: ocv1.GroupVersion.Group, Kind: ocv1.ClusterObjectDeploymentKind}, "example", nil)}, + {name: "bad request", err: apierrors.NewBadRequest("rejected")}, + {name: "unauthorized", err: apierrors.NewUnauthorized("rejected")}, + {name: "timeout", err: apierrors.NewTimeoutError("unknown result", 1), ambiguous: true}, + {name: "transport failure", err: errors.New("connection reset"), ambiguous: true}, + } { + t.Run(tc.name, func(t *testing.T) { + ctx := context.Background() + m := migrationTestClient(t, establishedClusterObjectDeploymentCRD()) + attempted := false + m.Client = interceptor.NewClient(m.Client.(client.WithWatch), interceptor.Funcs{ + Create: func(ctx context.Context, c client.WithWatch, obj client.Object, opts ...client.CreateOption) error { + switch obj.(type) { + case *ocv1.ClusterObjectDeployment: + attempted = true + return tc.err + default: + return c.Create(ctx, obj, opts...) } - } - attempted := false - m.Client = interceptor.NewClient(m.Client.(client.WithWatch), interceptor.Funcs{ - Create: func(ctx context.Context, c client.WithWatch, obj client.Object, opts ...client.CreateOption) error { - switch obj.(type) { - case *ocv1.ClusterObjectSet, *ocv1.ClusterObjectDeployment: - attempted = true - return tc.err - default: - return c.Create(ctx, obj, opts...) - } - }, - }) - m.Client = reconcilingSubscriptionClient{Client: m.Client} - sub, _ := healthySubscriptionFixtures() - result, err := m.CreateMigrationResources(ctx, Options{ClusterExtensionName: "example", SubscriptionName: sub.Name, SubscriptionNamespace: sub.Namespace}, &MigrationInfo{}, &Backup{Subscription: sub}) - if !attempted || !errors.Is(err, tc.err) { - t.Fatalf("expected create rejection %v, got %v (attempted: %v)", tc.err, err, attempted) - } - if result.TargetMayBeActive != tc.ambiguous { - t.Fatalf("TargetMayBeActive = %v, want %v", result.TargetMayBeActive, tc.ambiguous) - } - var restored operatorsv1alpha1.Subscription - getErr := m.Client.Get(ctx, client.ObjectKeyFromObject(sub), &restored) - if tc.ambiguous { - if !apierrors.IsNotFound(getErr) { - t.Fatalf("ambiguous create restored OLMv0: %v", getErr) - } - } else if getErr != nil || restored.Status.State != operatorsv1alpha1.SubscriptionStateAtLatest { - t.Fatalf("definitive rejection did not restore OLMv0: %v, state %s", getErr, restored.Status.State) - } + }, }) - } + m.Client = reconcilingSubscriptionClient{Client: m.Client} + sub, _ := healthySubscriptionFixtures() + result, err := m.CreateMigrationResources(ctx, Options{ClusterExtensionName: "example", SubscriptionName: sub.Name, SubscriptionNamespace: sub.Namespace}, &MigrationInfo{}, &Backup{Subscription: sub}) + if !attempted || !errors.Is(err, tc.err) { + t.Fatalf("expected create rejection %v, got %v (attempted: %v)", tc.err, err, attempted) + } + if result.TargetMayBeActive != tc.ambiguous { + t.Fatalf("TargetMayBeActive = %v, want %v", result.TargetMayBeActive, tc.ambiguous) + } + var restored operatorsv1alpha1.Subscription + getErr := m.Client.Get(ctx, client.ObjectKeyFromObject(sub), &restored) + if tc.ambiguous { + if !apierrors.IsNotFound(getErr) { + t.Fatalf("ambiguous create restored OLMv0: %v", getErr) + } + } else if getErr != nil || restored.Status.State != operatorsv1alpha1.SubscriptionStateAtLatest { + t.Fatalf("definitive rejection did not restore OLMv0: %v, state %s", getErr, restored.Status.State) + } + }) } } diff --git a/migration/pkg/migration/deployment.go b/migration/pkg/migration/deployment.go index c0098e3..6a9f28f 100644 --- a/migration/pkg/migration/deployment.go +++ b/migration/pkg/migration/deployment.go @@ -26,23 +26,8 @@ const rollbackDeploymentUIDsAnnotation = "olm.operatorframework.io/rollback-depl var deploymentNamePattern = regexp.MustCompile(`^[a-z]([a-z0-9-]*[a-z0-9])?$`) -func (m *Migrator) hasClusterObjectDeploymentCRD(ctx context.Context) (bool, error) { - var crd apiextensionsv1.CustomResourceDefinition - err := m.Client.Get(ctx, client.ObjectKey{Name: clusterObjectDeploymentCRDName}, &crd) - if apierrors.IsNotFound(err) { - return false, nil - } - if err != nil { - return false, fmt.Errorf("discover ClusterObjectDeployment CRD: %w", err) - } - return true, nil -} - -// prepareClusterObjectDeployment rejects incompatible APIs and occupied revision groups before migration. -func (m *Migrator) prepareClusterObjectDeployment(ctx context.Context, name string) error { - if len(name) > 52 || !deploymentNamePattern.MatchString(name) { - return fmt.Errorf("ClusterObjectDeployment name %q must be 1–52 lowercase letters, digits or hyphens, starting with a letter and ending with a letter or digit", name) - } +// ensureClusterObjectDeploymentCRD requires a ready, non-deleting COD API with compatible revision entries. +func (m *Migrator) ensureClusterObjectDeploymentCRD(ctx context.Context) error { var crd apiextensionsv1.CustomResourceDefinition if err := m.Client.Get(ctx, client.ObjectKey{Name: clusterObjectDeploymentCRDName}, &crd); err != nil { return fmt.Errorf("ClusterObjectDeployment CRD is required for COD migration: %w", err) @@ -54,6 +39,17 @@ func (m *Migrator) prepareClusterObjectDeployment(ctx context.Context, name stri if !established || crd.DeletionTimestamp != nil { return fmt.Errorf("ClusterObjectDeployment CRD is not established or is being deleted") } + return nil +} + +// prepareClusterObjectDeployment validates names and rejects occupied revision groups. +func (m *Migrator) prepareClusterObjectDeployment(ctx context.Context, name string) error { + if len(name) > 52 || !deploymentNamePattern.MatchString(name) { + return fmt.Errorf("ClusterObjectDeployment name %q must be 1–52 lowercase letters, digits or hyphens, starting with a letter and ending with a letter or digit", name) + } + if err := m.ensureClusterObjectDeploymentCRD(ctx); err != nil { + return err + } var cod ocv1.ClusterObjectDeployment if err := m.Client.Get(ctx, client.ObjectKey{Name: name}, &cod); err == nil { return fmt.Errorf("ClusterObjectDeployment %s already exists", name) diff --git a/migration/pkg/migration/deployment_test.go b/migration/pkg/migration/deployment_test.go index 8272402..f8effc8 100644 --- a/migration/pkg/migration/deployment_test.go +++ b/migration/pkg/migration/deployment_test.go @@ -73,7 +73,7 @@ func TestDeploymentReadiness(t *testing.T) { // TestPrepareDeployment covers invalid names, unavailable APIs, and occupied deployment identities. func TestPrepareDeployment(t *testing.T) { - crd := establishedClusterObjectDeploymentCRD() + crd := &apiextensionsv1.CustomResourceDefinition{ObjectMeta: metav1.ObjectMeta{Name: clusterObjectDeploymentCRDName}, Spec: apiextensionsv1.CustomResourceDefinitionSpec{Versions: []apiextensionsv1.CustomResourceDefinitionVersion{{Name: "v1", Served: true, Schema: testRevisionSchema(true)}}}, Status: apiextensionsv1.CustomResourceDefinitionStatus{Conditions: []apiextensionsv1.CustomResourceDefinitionCondition{{Type: apiextensionsv1.Established, Status: apiextensionsv1.ConditionTrue}}}} ctx := context.Background() if err := migrationTestClient(t).prepareClusterObjectDeployment(ctx, "example"); err == nil { t.Fatal("accepted missing CRD") @@ -153,13 +153,13 @@ func TestDeploymentTerminalRevisionFailures(t *testing.T) { } } -// TestAutomaticDeploymentSelection verifies API discovery selects the manager without unsafe fallback. -func TestAutomaticDeploymentSelection(t *testing.T) { +// TestRequiredDeploymentPrerequisite rejects absent or unavailable COD support without falling back to direct COS creation. +func TestRequiredDeploymentPrerequisite(t *testing.T) { for _, tc := range []struct { name string present, established, failDiscovery bool }{ - {name: "absent uses COS"}, + {name: "absent blocks migration"}, {name: "present uses COD", present: true, established: true}, {name: "unready does not fall back", present: true}, {name: "discovery failure does not fall back", failDiscovery: true}, @@ -186,15 +186,12 @@ func TestAutomaticDeploymentSelection(t *testing.T) { return c.Get(ctx, key, obj, opts...) }}) } - // An input value must not override automatic selection. - opts, err := m.PrepareClusterObjectSet(context.Background(), Options{SubscriptionName: "example", SystemNamespace: "controller", UseClusterObjectDeployment: !tc.present}) - wantError := tc.failDiscovery || tc.present && !tc.established + // Missing or unreadable COD support must never fall back to direct COS creation. + _, err := m.PrepareClusterObjectSet(context.Background(), Options{SubscriptionName: "example", SystemNamespace: "controller"}) + wantError := tc.failDiscovery || !tc.present || !tc.established if (err != nil) != wantError { t.Fatalf("error = %v, want error %v", err, wantError) } - if err == nil && opts.UseClusterObjectDeployment != tc.present { - t.Fatalf("COD selected = %v, want %v", opts.UseClusterObjectDeployment, tc.present) - } }) } } @@ -230,6 +227,7 @@ func TestRollbackDeploymentOwnership(t *testing.T) { type completingDeploymentClient struct{ client.Client } +// Create simulates controller completion for deployment creation tests. func (c completingDeploymentClient) Create(ctx context.Context, obj client.Object, opts ...client.CreateOption) error { if cod, ok := obj.(*ocv1.ClusterObjectDeployment); ok { ready := readyDeployment() @@ -238,28 +236,6 @@ func (c completingDeploymentClient) Create(ctx context.Context, obj client.Objec return c.Client.Create(ctx, obj, opts...) } -func TestCreateClusterObjectSetAdoptionLabel(t *testing.T) { - m := migrationTestClient(t) - m.Client = failingMigrationClient{Client: m.Client, succeedCOS: true} - resources, err := m.createClusterObjectSet(context.Background(), Options{ClusterExtensionName: "example", SubscriptionNamespace: "ns", SubscriptionName: "sub"}, &MigrationInfo{}) - if err != nil { - t.Fatal(err) - } - if resources.cos == nil || resources.cod != nil { - t.Fatal("expected a directly created COS when the COD CRD is absent") - } - var cos ocv1.ClusterObjectSet - if err := m.Client.Get(context.Background(), client.ObjectKeyFromObject(resources.cos), &cos); err != nil { - t.Fatal(err) - } - if cos.Labels["apps.kubernetes.io/managed-by"] != "object-controller" { - t.Fatal("migration COS lacks the object-controller adoption label") - } - if metav1.GetControllerOf(&cos) != nil || cos.Spec.Group != "example" || cos.Spec.CollisionProtection != ocv1.CollisionProtectionNone { - t.Fatalf("unexpected staging COS identity or collision protection: %#v", cos) - } -} - func TestCreateDeploymentTemplate(t *testing.T) { m := migrationTestClient(t) m.Client = completingDeploymentClient{m.Client} @@ -502,3 +478,44 @@ func establishedClusterObjectDeploymentCRD() *apiextensionsv1.CustomResourceDefi crd.Name = clusterObjectDeploymentCRDName return crd } + +// TestMissingCODBlocksMigrationBeforeMutation checks that missing COD support prevents destructive migration work. +func TestMissingCODBlocksMigrationBeforeMutation(t *testing.T) { + sub, csv := healthySubscriptionFixtures() + m := migrationTestClient(t, sub, csv, establishedClusterObjectSetCRD()) + m.Client = interceptor.NewClient(m.Client.(client.WithWatch), interceptor.Funcs{ + Create: func(context.Context, client.WithWatch, client.Object, ...client.CreateOption) error { + t.Fatal("created a resource without COD support") + return nil + }, + Update: func(context.Context, client.WithWatch, client.Object, ...client.UpdateOption) error { + t.Fatal("updated a resource without COD support") + return nil + }, + Delete: func(context.Context, client.WithWatch, client.Object, ...client.DeleteOption) error { + t.Fatal("deleted a resource without COD support") + return nil + }, + }) + ctx := context.Background() + opts := Options{SubscriptionName: sub.Name, SubscriptionNamespace: sub.Namespace} + report, err := m.CheckReadiness(ctx, opts) + if err != nil { + t.Fatal(err) + } + found := false + for _, check := range report.Checks { + if check.Name == "ClusterObjectDeployment API" && !check.Passed && strings.Contains(check.Message, clusterObjectDeploymentCRDName) { + found = true + } + } + if !found { + t.Fatalf("readiness did not report missing COD support: %+v", report) + } + if _, err := m.Gather(ctx, opts); err == nil || !strings.Contains(err.Error(), clusterObjectDeploymentCRDName) { + t.Fatalf("dry-run Gather did not reject missing COD: %v", err) + } + if err := m.Migrate(ctx, opts); err == nil { + t.Fatal("migration accepted missing COD support") + } +} diff --git a/migration/pkg/migration/migration.go b/migration/pkg/migration/migration.go index 0e41f4a..e0b8e19 100644 --- a/migration/pkg/migration/migration.go +++ b/migration/pkg/migration/migration.go @@ -41,7 +41,6 @@ var annotationPrefixesToStrip = []string{ // Recovery must never infer ownership from predictable names or labels: another // migration may have created objects with the same values after this one started. type createdMigrationResources struct { - cos *ocv1.ClusterObjectSet cod *ocv1.ClusterObjectDeployment secrets []corev1.Secret ce *ocv1.ClusterExtension @@ -61,7 +60,7 @@ const migrationInvocationAnnotation = "olm.operatorframework.io/migration-invoca // readiness, compatibility, catalog availability, and target prerequisites // before removing OLMv0 management. It backs up the Subscription spec in the // ClusterExtension annotations, creates and waits for the migration -// ClusterObjectSet, creates and waits for the ClusterExtension, then cleans up +// ClusterObjectDeployment, creates and waits for the ClusterExtension, then cleans up // OLMv0 artifacts. An optional disk backup is best-effort; failure to write it // is reported through Progress when configured but does not stop migration. // @@ -87,6 +86,7 @@ func (m *Migrator) Migrate(ctx context.Context, opts Options) error { return err } +// migrate runs preflight, backup, staging, handoff, and cleanup while reporting progress. func (m *Migrator) migrate(ctx context.Context, opts Options, nextStep func(ProgressStep, string)) error { _, csv, ip, err := m.GetCSVAndInstallPlan(ctx, opts) if err != nil { @@ -160,8 +160,8 @@ func (m *Migrator) migrate(ctx context.Context, opts Options, nextStep func(Prog return err } info.CollectedObjects = objects - // The migration COS is applied before the CE. Bootstrap the metadata-derived - // namespace so its namespaced objects can succeed, then include it in the COS + // The migration COD rolls out before the CE. Bootstrap the metadata-derived + // namespace so its namespaced objects can succeed, then include it in the template // so the controller's catalog-derived revision can take over its ownership. if err := m.PrepareInstallNamespace(ctx, resourceOpts); err != nil { return err @@ -228,7 +228,7 @@ func (m *Migrator) migrate(ctx context.Context, opts Options, nextStep func(Prog result, err := m.CreateMigrationResources(ctx, opts, info, backup) if err != nil { if result.TargetMayBeActive { - return fmt.Errorf("create migration resources: %w; target ClusterObjectSet may be active, so source Deployments remain scaled to zero", err) + return fmt.Errorf("create migration resources: %w; target ClusterObjectDeployment may be active, so source Deployments remain scaled to zero", err) } restoreCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 30*time.Second) defer cancel() @@ -252,25 +252,17 @@ func (m *Migrator) migrate(ctx context.Context, opts Options, nextStep func(Prog return nil } -// PrepareClusterObjectSet checks target ownership, selects the revision manager, +// PrepareClusterObjectSet checks target ownership and required COD availability, // and resolves where SecretPacker data belongs. Gather and Migrate validate the -// prepared revision with a server-side dry run. Preparation must run before -// PrepareForMigration, which deletes OLMv0 management objects. +// prepared revision through server-side dry run before removing OLMv0 management. func (m *Migrator) PrepareClusterObjectSet(ctx context.Context, opts Options) (Options, error) { opts.ApplyDefaults() if err := m.ensureClusterExtensionAbsent(ctx, opts.ClusterExtensionName); err != nil { return opts, err } - useCOD, err := m.hasClusterObjectDeploymentCRD(ctx) - if err != nil { + if err := m.prepareClusterObjectDeployment(ctx, opts.ClusterExtensionName); err != nil { return opts, err } - opts.UseClusterObjectDeployment = useCOD - if useCOD { - if err := m.prepareClusterObjectDeployment(ctx, opts.ClusterExtensionName); err != nil { - return opts, err - } - } if opts.SystemManagedInstallNamespace { if opts.InstallNamespace != "" { return opts, fmt.Errorf("system-managed install namespace cannot be combined with an explicit install namespace") @@ -525,15 +517,15 @@ func (m *Migrator) RecoverFromBackup(ctx context.Context, opts Options, backup * } // RecoverBeforeCE restores the Subscription after a failure before a migration -// resource was created. It deliberately does not delete a predictably named COS +// resource was created. It deliberately does not delete a predictably named COD // or Secret because this invocation cannot establish ownership of such objects. func (m *Migrator) RecoverBeforeCE(ctx context.Context, opts Options, backup *Backup) error { return m.RecoverFromBackup(ctx, opts, backup) } // recoverCreatedMigrationResources restores OLMv0 only while no target -// ClusterObjectSet can be active. Once a COS may have reconciled, it preserves -// the COS, its Secrets, and the ClusterExtension (including its backup +// ClusterObjectDeployment can be active. Once a COD may have reconciled, it preserves +// the COD, its revisions, Secrets, and the ClusterExtension (including its backup // annotations) for explicit operator recovery rather than deleting evidence // needed to roll the migration back safely. func (m *Migrator) recoverCreatedMigrationResources(ctx context.Context, opts Options, backup *Backup, resources *createdMigrationResources) error { @@ -548,9 +540,6 @@ func (m *Migrator) recoverCreatedMigrationResources(ctx context.Context, opts Op if resources.cod != nil { return fmt.Errorf("target ClusterObjectDeployment may have reconciled; preserving migration resources and refusing automatic OLMv0 recovery") } - if resources.cos != nil { - return fmt.Errorf("target ClusterObjectSet may have reconciled; preserving migration resources and refusing automatic OLMv0 recovery") - } if resources.ce != nil { if err := m.deleteTrackedResource(recoveryCtx, resources.ce); err != nil && client.IgnoreNotFound(err) != nil { return fmt.Errorf("delete created ClusterExtension during recovery: %w", err) @@ -608,38 +597,35 @@ func (m *Migrator) ensureClusterExtensionAbsent(ctx context.Context, name string return nil } -// CreateClusterObjectSet builds and creates a COS from the collected resources. -// It uses CollisionProtection=None; the controller creates the subsequent catalog-derived revision. -// The COS is annotated with the source Subscription reference. -// -// With UseClusterObjectDeployment, it creates a COD and waits for the controller -// to create and complete the migration revision instead. +// CreateClusterObjectSet stages collected resources through a ClusterObjectDeployment +// and waits for its rollout to complete. The COD controller creates the COS revisions. +// The method retains its original name for callers; it never creates a COS directly. func (m *Migrator) CreateClusterObjectSet(ctx context.Context, opts Options, info *MigrationInfo) error { var err error opts, err = m.PrepareClusterObjectSet(ctx, opts) if err != nil { return err } - resources, err := m.createClusterObjectSet(ctx, opts, info) + resources, err := m.createMigrationDeployment(ctx, opts, info) if err != nil { - if cleanupErr := m.cleanupCreatedClusterObjectSet(ctx, resources); cleanupErr != nil { + if cleanupErr := m.cleanupCreatedDeployment(ctx, resources); cleanupErr != nil { return errors.Join(err, cleanupErr) } } return err } -// CreateMigrationResources creates the ClusterObjectSet and its ClusterExtension -// as one recoverable operation. Its result reports whether a target COS may have +// CreateMigrationResources creates the ClusterObjectDeployment and its ClusterExtension +// as one recoverable operation. Its result reports whether a target COD may have // started reconciling, including when cleanup was requested after a failure. func (m *Migrator) CreateMigrationResources(ctx context.Context, opts Options, info *MigrationInfo, backup *Backup) (MigrationResourcesResult, error) { - resources, err := m.createClusterObjectSet(ctx, opts, info) + resources, err := m.createMigrationDeployment(ctx, opts, info) if err != nil { - result := MigrationResourcesResult{TargetMayBeActive: resources.cos != nil || resources.cod != nil || resources.ownershipUnknown} + result := MigrationResourcesResult{TargetMayBeActive: resources.cod != nil || resources.ownershipUnknown} if recoverErr := m.recoverCreatedMigrationResources(ctx, opts, backup, resources); recoverErr != nil { - return result, fmt.Errorf("COS creation failed: %w; recovery also failed: %v", err, recoverErr) + return result, fmt.Errorf("COD creation failed: %w; recovery also failed: %v", err, recoverErr) } - return result, fmt.Errorf("COS creation failed (recovered): %w", err) + return result, fmt.Errorf("COD creation failed (recovered): %w", err) } ce, ownershipUnknown, err := m.createClusterExtension(ctx, opts, info) @@ -648,7 +634,7 @@ func (m *Migrator) CreateMigrationResources(ctx context.Context, opts Options, i } resources.ownershipUnknown = resources.ownershipUnknown || ownershipUnknown if err != nil { - result := MigrationResourcesResult{TargetMayBeActive: resources.cos != nil || resources.cod != nil || resources.ownershipUnknown} + result := MigrationResourcesResult{TargetMayBeActive: resources.cod != nil || resources.ownershipUnknown} if recoverErr := m.recoverCreatedMigrationResources(ctx, opts, backup, resources); recoverErr != nil { return result, fmt.Errorf("ClusterExtension creation failed: %w; recovery also failed: %v", err, recoverErr) } @@ -657,27 +643,16 @@ func (m *Migrator) CreateMigrationResources(ctx context.Context, opts Options, i return MigrationResourcesResult{}, nil } -// createClusterObjectSet stages resources through the selected manager and records identities for recovery. -func (m *Migrator) createClusterObjectSet(ctx context.Context, opts Options, info *MigrationInfo) (*createdMigrationResources, error) { +// createMigrationDeployment stages resources through a COD and records creation identities for recovery. +func (m *Migrator) createMigrationDeployment(ctx context.Context, opts Options, info *MigrationInfo) (*createdMigrationResources, error) { resources := &createdMigrationResources{} - useCOD, err := m.hasClusterObjectDeploymentCRD(ctx) - if err != nil { + opts.ApplyDefaults() + if err := m.prepareClusterObjectDeployment(ctx, opts.ClusterExtensionName); err != nil { return resources, err } - opts.UseClusterObjectDeployment = useCOD - if useCOD { - if err := m.prepareClusterObjectDeployment(ctx, opts.ClusterExtensionName); err != nil { - return resources, err - } - } invocationMarker := string(uuid.NewUUID()) - cosName := fmt.Sprintf("%s-1", opts.ClusterExtensionName) - packingName := cosName - if opts.UseClusterObjectDeployment { - packingName = opts.ClusterExtensionName - } - phases, packed, err := buildMigrationPhases(opts, info, packingName) + phases, packed, err := buildMigrationPhases(opts, info, opts.ClusterExtensionName) if err != nil { return resources, err } @@ -696,12 +671,10 @@ func (m *Migrator) createClusterObjectSet(ctx context.Context, opts Options, inf return err } - // Create ref Secrets before the COS so the COS controller can find them immediately. + // Create ref Secrets before the COD so its revisions can resolve them immediately. for i := range packed.Secrets { secret := &packed.Secrets[i] - if opts.UseClusterObjectDeployment { - delete(secret.Labels, LabelRevisionName) - } + delete(secret.Labels, LabelRevisionName) if secret.Annotations == nil { secret.Annotations = map[string]string{} } @@ -721,50 +694,15 @@ func (m *Migrator) createClusterObjectSet(ctx context.Context, opts Options, inf resources.secrets = append(resources.secrets, *secret) } - if opts.UseClusterObjectDeployment { - err := m.createClusterObjectDeployment(ctx, opts, info, phases, invocationMarker, resources) - if err != nil && resources.cod == nil { - return resources, failWithSecretCleanup(err) - } - return resources, err - } - - cosObj, err := buildClusterObjectSet(opts, info, phases, invocationMarker) - if err != nil { + err = m.createClusterObjectDeployment(ctx, opts, info, phases, invocationMarker, resources) + if err != nil && resources.cod == nil { return resources, failWithSecretCleanup(err) } - - // A migration owns only a newly created revision. Applying an existing COS - // can overwrite its ownership or fail on immutable phases, making recovery - // and Secret cleanup unsafe. - if err := m.Client.Create(ctx, cosObj); err != nil { - if createWasRejected(err) { - return resources, failWithSecretCleanup(fmt.Errorf("failed to create ClusterObjectSet: %w", err)) - } - if apierrors.IsAlreadyExists(err) { - resources.ownershipUnknown = true - return resources, failWithSecretCleanup(fmt.Errorf("failed to create ClusterObjectSet: %w", err)) - } - if m.resolveCreatedObject(context.WithoutCancel(ctx), cosObj, invocationMarker) { - resources.cos = cosObj - return resources, fmt.Errorf("failed to create ClusterObjectSet: %w", err) - } - resources.ownershipUnknown = true - return resources, fmt.Errorf("failed to create ClusterObjectSet: %w", err) - } - resources.cos = cosObj - - if err := m.WaitForCOSSucceeded(ctx, cosName); err != nil { - return resources, err - } - if err := m.WaitForClusterObjectSetAvailable(ctx, cosName); err != nil { - return resources, err - } - return resources, nil + return resources, err } -// cleanupCreatedClusterObjectSet cleans staged resources using their recorded creation identities. -func (m *Migrator) cleanupCreatedClusterObjectSet(ctx context.Context, resources *createdMigrationResources) error { +// cleanupCreatedDeployment cleans staged resources only when their recorded identities permit safe recovery. +func (m *Migrator) cleanupCreatedDeployment(ctx context.Context, resources *createdMigrationResources) error { if resources == nil { return nil } @@ -772,15 +710,10 @@ func (m *Migrator) cleanupCreatedClusterObjectSet(ctx context.Context, resources return fmt.Errorf("ClusterObjectDeployment may have reconciled; preserving its revisions and Secrets for explicit recovery") } if resources.ownershipUnknown { - return fmt.Errorf("ClusterObjectSet creation outcome is unknown; refusing automatic cleanup") + return fmt.Errorf("ClusterObjectDeployment creation outcome is unknown; refusing automatic cleanup") } cleanupCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 30*time.Second) defer cancel() - if resources.cos != nil { - if err := m.deleteTrackedResource(cleanupCtx, resources.cos, client.PropagationPolicy(metav1.DeletePropagationOrphan)); err != nil && client.IgnoreNotFound(err) != nil { - return fmt.Errorf("delete created ClusterObjectSet: %w", err) - } - } return m.cleanupCreatedSecrets(cleanupCtx, resources.secrets) } diff --git a/migration/pkg/migration/readiness.go b/migration/pkg/migration/readiness.go index 89b4c7a..9545125 100644 --- a/migration/pkg/migration/readiness.go +++ b/migration/pkg/migration/readiness.go @@ -10,24 +10,25 @@ import ( ) // CheckReadiness checks Subscription state, CSV health, package uniqueness, -// dependency ownership, and the ClusterObjectSet API without modifying the +// dependency ownership, and the ClusterObjectDeployment/ClusterObjectSet APIs without modifying the // cluster. Failed prerequisites appear in the returned report; a returned // error means the check itself could not be completed. Compatibility and // catalog availability are checked separately. func (m *Migrator) CheckReadiness(ctx context.Context, opts Options) (*PreMigrationReport, error) { report := &PreMigrationReport{} - if err := m.ensureClusterObjectSetCRD(ctx); err != nil { - report.Checks = append(report.Checks, CheckResult{ - Name: "ClusterObjectSet API", - Passed: false, - Message: err.Error(), - }) - } else { - report.Checks = append(report.Checks, CheckResult{ - Name: "ClusterObjectSet API", - Passed: true, - Message: "ClusterObjectSet CRD is established", - }) + for _, prerequisite := range []struct { + name string + check func(context.Context) error + }{ + {"ClusterObjectSet API", m.ensureClusterObjectSetCRD}, + {"ClusterObjectDeployment API", m.ensureClusterObjectDeploymentCRD}, + } { + check := CheckResult{Name: prerequisite.name, Passed: true, Message: "CRD is established"} + if err := prerequisite.check(ctx); err != nil { + check.Passed = false + check.Message = err.Error() + } + report.Checks = append(report.Checks, check) } var sub operatorsv1alpha1.Subscription diff --git a/migration/pkg/migration/revision_schema.go b/migration/pkg/migration/revision_schema.go index fee0ced..9e4f736 100644 --- a/migration/pkg/migration/revision_schema.go +++ b/migration/pkg/migration/revision_schema.go @@ -2,7 +2,6 @@ package migration import ( "context" - "encoding/json" "fmt" metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" @@ -18,21 +17,11 @@ import ( // instead of silently pruning revision entries. This does not execute controllers // or validate the contents of the referenced Secrets as Kubernetes resources. func (m *Migrator) validateMigrationRevision(ctx context.Context, opts Options, info *MigrationInfo) error { - packingName := opts.ClusterExtensionName + "-1" - if opts.UseClusterObjectDeployment { - packingName = opts.ClusterExtensionName - } - phases, _, err := buildMigrationPhases(opts, info, packingName) + phases, _, err := buildMigrationPhases(opts, info, opts.ClusterExtensionName) if err != nil { return err } - marker := string(uuid.NewUUID()) - var candidate client.Object - if opts.UseClusterObjectDeployment { - candidate, err = buildClusterObjectDeployment(opts, info, phases, marker) - } else { - candidate, err = buildClusterObjectSet(opts, info, phases, marker) - } + candidate, err := buildClusterObjectDeployment(opts, info, phases, string(uuid.NewUUID())) if err != nil { return err } @@ -83,44 +72,3 @@ func buildMigrationPhases(opts Options, info *MigrationInfo, packingName string) return phases, packed, nil } - -// buildClusterObjectSet constructs the same candidate for validation and creation. -func buildClusterObjectSet(opts Options, info *MigrationInfo, phases []*ocv1ac.ClusterObjectSetPhaseApplyConfiguration, marker string) (*ocv1.ClusterObjectSet, error) { - cosSpec := ocv1ac.ClusterObjectSetSpec(). - WithGroup(opts.ClusterExtensionName). - WithRevision(1). - WithCollisionProtection(ocv1.CollisionProtectionNone). - WithLifecycleState(ocv1.ClusterObjectSetLifecycleStateActive). - WithPhases(phases...) - - cosAnnotations := map[string]string{ - MigratedFromSubscriptionAnnotation: fmt.Sprintf("%s/%s", opts.SubscriptionNamespace, opts.SubscriptionName), - LabelPackageName: info.PackageName, - LabelBundleName: info.BundleName, - LabelBundleVersion: info.Version, - migrationInvocationAnnotation: marker, - } - if info.BundleImage != "" { - cosAnnotations[LabelBundleReference] = info.BundleImage - } - - cos := ocv1ac.ClusterObjectSet(opts.ClusterExtensionName + "-1"). - WithSpec(cosSpec). - WithLabels(map[string]string{ - LabelOwnerKind: ocv1.ClusterExtensionKind, - LabelOwnerName: opts.ClusterExtensionName, - controllerManagedByLabel: "object-controller", - }). - WithAnnotations(cosAnnotations) - - cosData, err := json.Marshal(cos) - if err != nil { - return nil, fmt.Errorf("failed to marshal COS: %w", err) - } - cosObj := &ocv1.ClusterObjectSet{} - if err := json.Unmarshal(cosData, cosObj); err != nil { - return nil, fmt.Errorf("failed to decode COS: %w", err) - } - - return cosObj, nil -} diff --git a/migration/pkg/migration/revision_schema_test.go b/migration/pkg/migration/revision_schema_test.go index 4fd5634..b112360 100644 --- a/migration/pkg/migration/revision_schema_test.go +++ b/migration/pkg/migration/revision_schema_test.go @@ -19,7 +19,7 @@ import ( // request options, and preserves server validation and authorization failures. func TestRevisionServerDryRun(t *testing.T) { rejection := errors.New("API server rejected candidate") - for _, deployment := range []bool{false, true} { + for _, deployment := range []bool{true} { for _, serverErr := range []error{nil, rejection} { name := "COS" if deployment { @@ -67,7 +67,7 @@ func TestRevisionServerDryRun(t *testing.T) { return nil }, }) - opts := Options{ClusterExtensionName: "example", SystemNamespace: "controller", UseClusterObjectDeployment: deployment} + opts := Options{ClusterExtensionName: "example", SystemNamespace: "controller"} info := &MigrationInfo{CollectedObjects: []unstructured.Unstructured{{Object: map[string]interface{}{"apiVersion": "v1", "kind": "ConfigMap", "metadata": map[string]interface{}{"name": "config", "namespace": "operators"}, "data": map[string]interface{}{"key": "value"}}}}} err := m.validateMigrationRevision(t.Context(), opts, info) if !errors.Is(err, serverErr) || calls != 1 { diff --git a/migration/pkg/migration/scan.go b/migration/pkg/migration/scan.go index 76c1c95..4b8f560 100644 --- a/migration/pkg/migration/scan.go +++ b/migration/pkg/migration/scan.go @@ -765,11 +765,12 @@ func (m *Migrator) findDependents(ctx context.Context, packageName string) []str return dependents } +// dependentsWarning formats package-dependent conflicts for scan results. func dependentsWarning(packageName string, dependents []string) string { return fmt.Sprintf("other operator(s) may depend on package %q: %v — verify they remain functional after migration", packageName, dependents) } -// Gather checks the target COS prerequisites and collects everything that would +// Gather checks the target COD/COS prerequisites and collects everything that would // be migrated without making cluster mutations — backs convert --dry-run (R1.1). func (m *Migrator) Gather(ctx context.Context, opts Options) (*MigrationInfo, error) { opts.ApplyDefaults() @@ -785,7 +786,6 @@ func (m *Migrator) Gather(ctx context.Context, opts Options) (*MigrationInfo, er return nil, err } info.SystemNamespace = prepared.SystemNamespace - info.UseClusterObjectDeployment = prepared.UseClusterObjectDeployment return info, nil } diff --git a/migration/pkg/migration/system_namespace_test.go b/migration/pkg/migration/system_namespace_test.go index bcee439..6c98a5d 100644 --- a/migration/pkg/migration/system_namespace_test.go +++ b/migration/pkg/migration/system_namespace_test.go @@ -65,6 +65,7 @@ func TestEffectiveInstallNamespaceRejectsInvalidTemplate(t *testing.T) { } } +// TestPrepareClusterObjectSetSystemManagedNamespaceCapability requires compatible namespace and COD APIs before omitting the install namespace. func TestPrepareClusterObjectSetSystemManagedNamespaceCapability(t *testing.T) { ctx := context.Background() opts := Options{ @@ -74,12 +75,12 @@ func TestPrepareClusterObjectSetSystemManagedNamespaceCapability(t *testing.T) { SystemNamespace: "operator-controller", } - m := migrationTestClient(t, establishedClusterObjectSetCRD(), establishedClusterExtensionCRD(false)) + m := migrationTestClient(t, establishedClusterObjectSetCRD(), establishedClusterObjectDeploymentCRD(), establishedClusterExtensionCRD(false)) if _, err := m.PrepareClusterObjectSet(ctx, opts); err != nil { t.Fatalf("PrepareClusterObjectSet() optional namespace error = %v", err) } - m = migrationTestClient(t, establishedClusterObjectSetCRD(), establishedClusterExtensionCRD(true)) + m = migrationTestClient(t, establishedClusterObjectSetCRD(), establishedClusterObjectDeploymentCRD(), establishedClusterExtensionCRD(true)) if _, err := m.PrepareClusterObjectSet(ctx, opts); err == nil || !strings.Contains(err.Error(), "optional spec.namespace") { t.Fatalf("PrepareClusterObjectSet() required namespace error = %v, want capability error", err) } diff --git a/migration/pkg/migration/types.go b/migration/pkg/migration/types.go index c55f017..a5cc8aa 100644 --- a/migration/pkg/migration/types.go +++ b/migration/pkg/migration/types.go @@ -41,11 +41,6 @@ type Options struct { // opt-in: an unset InstallNamespace otherwise means SubscriptionNamespace. SystemManagedInstallNamespace bool - // UseClusterObjectDeployment is populated by PrepareClusterObjectSet from - // COD CRD presence, not a caller-selected override. A present COD CRD - // requires a controller with COD-backed ClusterExtension reconciliation. - UseClusterObjectDeployment bool - // BackupDirectory, when non-empty, writes OLM objects to disk before deletions (R2.6). BackupDirectory string @@ -87,19 +82,17 @@ func (o *Options) ApplyDefaults() { // MigrationInfo holds the profiled operator information gathered during the migration. type MigrationInfo struct { - // UseClusterObjectDeployment reports the CRD-selected revision manager from Gather. - UseClusterObjectDeployment bool - PackageName string - Version string - BundleName string - BundleImage string - Channel string - ManualApproval bool // true if the Subscription had Manual install plan approval - CatalogSourceRef types.NamespacedName - CatalogSourceImage string // tag-based image from CatalogSource.Spec.Image - ResolvedCatalogName string - SystemNamespace string // operator-controller namespace for COS reference Secrets - CollectedObjects []unstructured.Unstructured + PackageName string + Version string + BundleName string + BundleImage string + Channel string + ManualApproval bool // true if the Subscription had Manual install plan approval + CatalogSourceRef types.NamespacedName + CatalogSourceImage string // tag-based image from CatalogSource.Spec.Image + ResolvedCatalogName string + SystemNamespace string // operator-controller namespace for COS reference Secrets + CollectedObjects []unstructured.Unstructured // SubscriptionConfig holds spec.config from the Subscription for mapping to CE (R4). // spec.config.selector is dropped (never honored in OLMv0; no CE equivalent). diff --git a/migration/pkg/migration/unit_test.go b/migration/pkg/migration/unit_test.go index f1e5d30..1d3dc6e 100644 --- a/migration/pkg/migration/unit_test.go +++ b/migration/pkg/migration/unit_test.go @@ -39,12 +39,12 @@ import ( type failingMigrationClient struct { client.Client - failCOSCreate bool - unknownCOSCreate bool + failCODCreate bool + unknownCODCreate bool failCECreate bool failCEAfterCreate bool - invalidCOS bool - succeedCOS bool + invalidCOD bool + succeedCOD bool } // canceledScaleClient cancels the caller's context while failing one scale-down @@ -67,14 +67,14 @@ func (c canceledScaleClient) Update(ctx context.Context, obj client.Object, opts // Create injects configured creation failures for migration recovery tests. func (c failingMigrationClient) Create(ctx context.Context, obj client.Object, opts ...client.CreateOption) error { - if c.failCOSCreate { - if _, ok := obj.(*ocv1.ClusterObjectSet); ok { - return apierrors.NewAlreadyExists(ocv1.GroupVersion.WithResource("clusterobjectsets").GroupResource(), obj.GetName()) + if c.failCODCreate { + if _, ok := obj.(*ocv1.ClusterObjectDeployment); ok { + return apierrors.NewAlreadyExists(ocv1.GroupVersion.WithResource("clusterobjectdeployments").GroupResource(), obj.GetName()) } } - if c.unknownCOSCreate { - if _, ok := obj.(*ocv1.ClusterObjectSet); ok { - return errors.New("simulated ClusterObjectSet create transport failure") + if c.unknownCODCreate { + if _, ok := obj.(*ocv1.ClusterObjectDeployment); ok { + return errors.New("simulated ClusterObjectDeployment create transport failure") } } if c.failCECreate { @@ -90,11 +90,11 @@ func (c failingMigrationClient) Create(ctx context.Context, obj client.Object, o return errors.New("simulated ClusterExtension create transport failure") } } - if c.succeedCOS { - if cos, ok := obj.(*ocv1.ClusterObjectSet); ok { - cos.Status.CompletedAt = metav1.Now() + if c.succeedCOD { + if cos, ok := obj.(*ocv1.ClusterObjectDeployment); ok { cos.Status.Conditions = []metav1.Condition{ - {Type: ocv1.ClusterObjectSetTypeReady, Status: metav1.ConditionTrue}, + {Type: ocv1.ClusterObjectDeploymentTypeProgressing, Status: metav1.ConditionFalse, Reason: ocv1.ClusterObjectDeploymentReasonNewClusterObjectSetProgressed}, + {Type: ocv1.ClusterObjectDeploymentTypeAvailable, Status: metav1.ConditionTrue}, } } } @@ -103,9 +103,12 @@ func (c failingMigrationClient) Create(ctx context.Context, obj client.Object, o // Get injects configured read failures for migration recovery tests. func (c failingMigrationClient) Get(ctx context.Context, key client.ObjectKey, obj client.Object, opts ...client.GetOption) error { - if c.invalidCOS { - if cos, ok := obj.(*ocv1.ClusterObjectSet); ok { - cos.Status.Conditions = []metav1.Condition{{Type: ocv1.ClusterObjectSetTypeReady, Status: metav1.ConditionFalse, Reason: ocv1.ClusterObjectSetReasonInvalidSpecification}} + if c.invalidCOD { + if cos, ok := obj.(*ocv1.ClusterObjectDeployment); ok { + if err := c.Client.Get(ctx, key, obj, opts...); err != nil { + return err + } + cos.Status.Conditions = []metav1.Condition{{Type: ocv1.ClusterObjectDeploymentTypeProgressing, Status: metav1.ConditionFalse, Reason: ocv1.ClusterObjectDeploymentReasonInvalidSpecification}} return nil } } @@ -186,9 +189,10 @@ func establishedClusterExtensionCRD(namespaceRequired bool) *apiextensionsv1.Cus } } +// TestCheckReadiness covers controller and revision-API readiness prerequisites. func TestCheckReadiness(t *testing.T) { sub, csv := healthySubscriptionFixtures() - m := migrationTestClient(t, sub, csv, establishedClusterObjectSetCRD()) + m := migrationTestClient(t, sub, csv, establishedClusterObjectSetCRD(), establishedClusterObjectDeploymentCRD()) report, err := m.CheckReadiness(context.Background(), Options{SubscriptionName: "sub", SubscriptionNamespace: "ns"}) if err != nil || !report.Passed() { t.Fatalf("healthy report=%#v err=%v", report, err) @@ -197,7 +201,7 @@ func TestCheckReadiness(t *testing.T) { busySub, busyCSV := healthySubscriptionFixtures() busySub.Status.State = operatorsv1alpha1.SubscriptionStateUpgradeAvailable busyCSV.Status.Phase = operatorsv1alpha1.CSVPhaseFailed - m = migrationTestClient(t, busySub, busyCSV, establishedClusterObjectSetCRD()) + m = migrationTestClient(t, busySub, busyCSV, establishedClusterObjectSetCRD(), establishedClusterObjectDeploymentCRD()) report, err = m.CheckReadiness(context.Background(), Options{SubscriptionName: "sub", SubscriptionNamespace: "ns"}) if err != nil || report.Passed() || len(report.FailedChecks()) != 2 { t.Fatalf("unacknowledged report=%#v err=%v", report, err) @@ -209,7 +213,7 @@ func TestCheckReadiness(t *testing.T) { depSub, depCSV := healthySubscriptionFixtures() depSub.Annotations = map[string]string{"olm.generated-by": "parent"} - m = migrationTestClient(t, depSub, depCSV, establishedClusterObjectSetCRD(), &operatorsv1alpha1.Subscription{ObjectMeta: metav1.ObjectMeta{Name: "other", Namespace: "other"}, Spec: &operatorsv1alpha1.SubscriptionSpec{Package: "widgets"}}) + m = migrationTestClient(t, depSub, depCSV, establishedClusterObjectSetCRD(), establishedClusterObjectDeploymentCRD(), &operatorsv1alpha1.Subscription{ObjectMeta: metav1.ObjectMeta{Name: "other", Namespace: "other"}, Spec: &operatorsv1alpha1.SubscriptionSpec{Package: "widgets"}}) report, err = m.CheckReadiness(context.Background(), Options{SubscriptionName: "sub", SubscriptionNamespace: "ns"}) if err != nil || report.Passed() || len(report.FailedChecks()) != 2 { t.Fatalf("dependency/duplicate report=%#v err=%v", report, err) @@ -914,7 +918,7 @@ func TestPrepareClusterObjectSet(t *testing.T) { Labels: map[string]string{"app.kubernetes.io/name": "operator-controller"}, }, } - m := migrationTestClient(t, establishedCRD, controller) + m := migrationTestClient(t, establishedCRD, establishedClusterObjectDeploymentCRD(), controller) got, err := m.PrepareClusterObjectSet(context.Background(), Options{SubscriptionName: "sub", SubscriptionNamespace: "operators"}) if err != nil { @@ -924,7 +928,7 @@ func TestPrepareClusterObjectSet(t *testing.T) { t.Fatalf("SystemNamespace = %q, want discovered operator-controller namespace", got.SystemNamespace) } - got, err = m.PrepareClusterObjectSet(context.Background(), Options{SystemNamespace: "chosen"}) + got, err = m.PrepareClusterObjectSet(context.Background(), Options{SubscriptionName: "sub", SystemNamespace: "chosen"}) if err != nil { t.Fatalf("PrepareClusterObjectSet() with override error = %v", err) } @@ -966,7 +970,7 @@ func TestPrepareClusterObjectSetRejectsDeletingOperatorControllerNamespace(t *te }, } { t.Run(name, func(t *testing.T) { - m := migrationTestClient(t, establishedCRD, controller) + m := migrationTestClient(t, establishedCRD, establishedClusterObjectDeploymentCRD(), controller) _, err := m.PrepareClusterObjectSet(context.Background(), opts) if err == nil || !strings.Contains(err.Error(), "cannot delete source namespace \"operator-controller\"") { t.Fatalf("PrepareClusterObjectSet() error = %v, want source operator-controller namespace deletion rejection", err) @@ -1135,10 +1139,11 @@ func TestScanStatesAndPublicHelpers(t *testing.T) { } } +// TestCheckReturnsPassingAndFailingChecks verifies checks report both satisfied and failed prerequisites. func TestCheckReturnsPassingAndFailingChecks(t *testing.T) { sub, csv := healthySubscriptionFixtures() sub.Status.State = operatorsv1alpha1.SubscriptionStateUpgradeAvailable - m := migrationTestClient(t, sub, csv, establishedClusterObjectSetCRD()) + m := migrationTestClient(t, sub, csv, establishedClusterObjectSetCRD(), establishedClusterObjectDeploymentCRD()) result, err := m.Check(context.Background(), Options{SubscriptionName: sub.Name, SubscriptionNamespace: sub.Namespace}) if err != nil { @@ -1194,6 +1199,7 @@ func TestScanAllKeepsMixedUnsafeOperatorsOutOfEligibleResults(t *testing.T) { } } +// TestScanAllSubscriptionsWithOptionsAppliesAcknowledgments checks scan eligibility honors the supplied acknowledgments. func TestScanAllSubscriptionsWithOptionsAppliesAcknowledgments(t *testing.T) { ctx := context.Background() sub, csv := healthySubscriptionFixtures() @@ -1202,7 +1208,7 @@ func TestScanAllSubscriptionsWithOptionsAppliesAcknowledgments(t *testing.T) { ObjectMeta: metav1.ObjectMeta{Name: "scoped", Namespace: sub.Namespace}, Spec: operatorsv1.OperatorGroupSpec{TargetNamespaces: []string{sub.Namespace}}, } - m := migrationTestClient(t, sub, csv, og, establishedClusterObjectSetCRD()) + m := migrationTestClient(t, sub, csv, og, establishedClusterObjectSetCRD(), establishedClusterObjectDeploymentCRD()) without, err := m.ScanAllSubscriptions(ctx) if err != nil || len(without) != 1 { @@ -1252,10 +1258,11 @@ func TestMigrateEmitsStructuredProgressOnFailure(t *testing.T) { } } +// TestPrerequisitesAndRecoveryErrors covers errors reported by prerequisite and recovery APIs. func TestPrerequisitesAndRecoveryErrors(t *testing.T) { ctx := context.Background() sub, csv := healthySubscriptionFixtures() - m := migrationTestClient(t, sub, csv, establishedClusterObjectSetCRD()) + m := migrationTestClient(t, sub, csv, establishedClusterObjectSetCRD(), establishedClusterObjectDeploymentCRD()) gotCSV, ip, readiness, compatibility, err := m.EnsurePrerequisites(ctx, Options{SubscriptionName: "sub", SubscriptionNamespace: "ns"}) if err != nil || gotCSV.Name != csv.Name || ip != nil || !readiness.Passed() || compatibility == nil { t.Fatalf("EnsurePrerequisites() = csv=%#v ip=%#v readiness=%#v compatibility=%#v err=%v", gotCSV, ip, readiness, compatibility, err) @@ -1336,6 +1343,7 @@ func TestMigrateRejectsUnsafeOperatorsWithoutMutation(t *testing.T) { } } +// TestNonImageCatalogSourceRejectsOperatorMigration rejects catalog sources that cannot be represented in OLMv1. func TestNonImageCatalogSourceRejectsOperatorMigration(t *testing.T) { ctx := context.Background() for _, tt := range []struct { @@ -1359,7 +1367,7 @@ func TestNonImageCatalogSourceRejectsOperatorMigration(t *testing.T) { ObjectMeta: metav1.ObjectMeta{Name: "source", Namespace: "catalogs"}, Spec: operatorsv1alpha1.CatalogSourceSpec{SourceType: tt.sourceType, Image: tt.image}, } - objects := []runtime.Object{sub, csv, establishedClusterObjectSetCRD()} + objects := []runtime.Object{sub, csv, establishedClusterObjectSetCRD(), establishedClusterObjectDeploymentCRD()} if !tt.missing { objects = append(objects, cs) } @@ -1444,6 +1452,7 @@ func TestSubscriptionCatalogSourceMustExistAndBeImageBacked(t *testing.T) { } } +// TestMigrationOperationsRejectInvalidInstallPlanCatalogSource checks unsupported catalog sources are rejected across migration entry points. func TestMigrationOperationsRejectInvalidInstallPlanCatalogSource(t *testing.T) { ctx := context.Background() for _, tt := range []struct { @@ -1481,7 +1490,7 @@ func TestMigrationOperationsRejectInvalidInstallPlanCatalogSource(t *testing.T) Image: "registry.example/subscription:latest", }, } - objects := []runtime.Object{sub, csv, ip, subscriptionCatalog, establishedClusterObjectSetCRD()} + objects := []runtime.Object{sub, csv, ip, subscriptionCatalog, establishedClusterObjectSetCRD(), establishedClusterObjectDeploymentCRD()} if tt.effectiveCatalog != nil { objects = append(objects, tt.effectiveCatalog) } @@ -1578,10 +1587,11 @@ func TestRollbackAndCleanupRejectInvalidInputWithoutMutation(t *testing.T) { } } +// TestCreateClusterObjectSetPreservesTemporarySecretsOnCollision protects Secret artifacts when an existing target prevents staging. func TestCreateClusterObjectSetPreservesTemporarySecretsOnCollision(t *testing.T) { ctx := context.Background() - m := migrationTestClient(t, establishedClusterObjectSetCRD()) - m.Client = failingMigrationClient{Client: m.Client, failCOSCreate: true} + m := migrationTestClient(t, establishedClusterObjectSetCRD(), establishedClusterObjectDeploymentCRD()) + m.Client = failingMigrationClient{Client: m.Client, failCODCreate: true} object := unstructured.Unstructured{Object: map[string]interface{}{ "apiVersion": "v1", "kind": "ConfigMap", "metadata": map[string]interface{}{"name": "operator-config", "namespace": "ns"}, }} @@ -1596,17 +1606,18 @@ func TestCreateClusterObjectSetPreservesTemporarySecretsOnCollision(t *testing.T t.Fatal(err) } if len(secrets.Items) == 0 { - t.Fatal("COS collision removed temporary Secret(s) despite unknown ownership") + t.Fatal("COD collision removed temporary Secret(s) despite unknown ownership") } - if err := m.Client.Get(ctx, client.ObjectKey{Name: "sub-1"}, &ocv1.ClusterObjectSet{}); err == nil { - t.Fatal("COS collision created a ClusterObjectSet") + if err := m.Client.Get(ctx, client.ObjectKey{Name: "sub"}, &ocv1.ClusterObjectDeployment{}); err == nil { + t.Fatal("COD collision created a ClusterObjectSet") } } -func TestCreateMigrationResourcesTreatsCOSCollisionAsPotentiallyActive(t *testing.T) { +// TestCreateMigrationResourcesTreatsCODCollisionAsPotentiallyActive ensures a colliding deployment cannot trigger unsafe automatic recovery. +func TestCreateMigrationResourcesTreatsCODCollisionAsPotentiallyActive(t *testing.T) { ctx := context.Background() - m := migrationTestClient(t, establishedClusterObjectSetCRD()) - m.Client = failingMigrationClient{Client: m.Client, failCOSCreate: true} + m := migrationTestClient(t, establishedClusterObjectSetCRD(), establishedClusterObjectDeploymentCRD()) + m.Client = failingMigrationClient{Client: m.Client, failCODCreate: true} object := unstructured.Unstructured{Object: map[string]interface{}{ "apiVersion": "v1", "kind": "ConfigMap", "metadata": map[string]interface{}{"name": "operator-config", "namespace": "ns"}, }} @@ -1614,17 +1625,18 @@ func TestCreateMigrationResourcesTreatsCOSCollisionAsPotentiallyActive(t *testin PackageName: "widgets", BundleName: "widgets.v1", Version: "1.0.0", CollectedObjects: []unstructured.Unstructured{object}, }, nil) if err == nil || !apierrors.IsAlreadyExists(err) { - t.Fatalf("CreateMigrationResources() error = %v, want COS collision", err) + t.Fatalf("CreateMigrationResources() error = %v, want COD collision", err) } if !result.TargetMayBeActive { - t.Fatal("CreateMigrationResources() TargetMayBeActive = false, want true after COS collision") + t.Fatal("CreateMigrationResources() TargetMayBeActive = false, want true after COD collision") } } +// TestCreateClusterObjectSetPreservesSecretsAfterUnknownCreateOutcome preserves artifacts when deployment creation may have succeeded. func TestCreateClusterObjectSetPreservesSecretsAfterUnknownCreateOutcome(t *testing.T) { ctx := context.Background() - m := migrationTestClient(t, establishedClusterObjectSetCRD()) - m.Client = failingMigrationClient{Client: m.Client, unknownCOSCreate: true} + m := migrationTestClient(t, establishedClusterObjectSetCRD(), establishedClusterObjectDeploymentCRD()) + m.Client = failingMigrationClient{Client: m.Client, unknownCODCreate: true} object := unstructured.Unstructured{Object: map[string]interface{}{ "apiVersion": "v1", "kind": "ConfigMap", "metadata": map[string]interface{}{"name": "operator-config", "namespace": "ns"}, }} @@ -1639,7 +1651,7 @@ func TestCreateClusterObjectSetPreservesSecretsAfterUnknownCreateOutcome(t *test t.Fatal(err) } if len(secrets.Items) == 0 { - t.Fatal("unknown COS creation outcome removed Secret references") + t.Fatal("unknown COD creation outcome removed Secret references") } } @@ -1678,11 +1690,12 @@ func TestCreateClusterExtensionRecordsNamespaceDeletionAcknowledgement(t *testin } } -func TestCreateMigrationResourcesPreservesTrackedCOSAfterClusterExtensionFailure(t *testing.T) { +// TestCreateMigrationResourcesPreservesTrackedCODAfterClusterExtensionFailure retains an active deployment when extension creation fails. +func TestCreateMigrationResourcesPreservesTrackedCODAfterClusterExtensionFailure(t *testing.T) { ctx := context.Background() - m := migrationTestClient(t) + m := migrationTestClient(t, establishedClusterObjectDeploymentCRD()) baseClient := m.Client - m.Client = failingMigrationClient{Client: baseClient, succeedCOS: true, failCECreate: true} + m.Client = failingMigrationClient{Client: baseClient, succeedCOD: true, failCECreate: true} object := unstructured.Unstructured{Object: map[string]interface{}{ "apiVersion": "v1", "kind": "ConfigMap", "metadata": map[string]interface{}{"name": "operator-config", "namespace": "ns"}, }} @@ -1693,20 +1706,20 @@ func TestCreateMigrationResourcesPreservesTrackedCOSAfterClusterExtensionFailure t.Fatalf("CreateMigrationResources() error = %v, want ClusterExtension creation failure", err) } if !result.TargetMayBeActive { - t.Fatal("CreateMigrationResources() TargetMayBeActive = false, want true after COS success") + t.Fatal("CreateMigrationResources() TargetMayBeActive = false, want true after COD success") } m.Client = baseClient - if err := m.Client.Get(ctx, client.ObjectKey{Name: "sub-1"}, &ocv1.ClusterObjectSet{}); err != nil { + if err := m.Client.Get(ctx, client.ObjectKey{Name: "sub"}, &ocv1.ClusterObjectDeployment{}); err != nil { t.Fatalf("ClusterExtension failure deleted the ClusterObjectSet needed for explicit recovery: %v", err) } } -// TestCreateClusterObjectSetCleansSecretsAfterReadinessFailure checks failed staging cleans its owned Secret artifacts. -func TestCreateClusterObjectSetCleansSecretsAfterReadinessFailure(t *testing.T) { +// TestCreateClusterObjectSetPreservesSecretsAfterReadinessFailure keeps artifacts needed by a deployment that may already be reconciling. +func TestCreateClusterObjectSetPreservesSecretsAfterReadinessFailure(t *testing.T) { ctx := context.Background() - m := migrationTestClient(t, establishedClusterObjectSetCRD()) + m := migrationTestClient(t, establishedClusterObjectSetCRD(), establishedClusterObjectDeploymentCRD()) baseClient := m.Client - m.Client = failingMigrationClient{Client: baseClient, invalidCOS: true} + m.Client = failingMigrationClient{Client: baseClient, invalidCOD: true} object := unstructured.Unstructured{Object: map[string]interface{}{ "apiVersion": "v1", "kind": "ConfigMap", "metadata": map[string]interface{}{"name": "operator-config", "namespace": "ns"}, }} @@ -1714,18 +1727,18 @@ func TestCreateClusterObjectSetCleansSecretsAfterReadinessFailure(t *testing.T) PackageName: "widgets", BundleName: "widgets.v1", Version: "1.0.0", CollectedObjects: []unstructured.Unstructured{object}, }) if err == nil { - t.Fatal("CreateClusterObjectSet() unexpectedly completed without COS status") + t.Fatal("CreateClusterObjectSet() unexpectedly completed without COD status") } m.Client = baseClient var secrets corev1.SecretList if err := m.Client.List(ctx, &secrets, client.InNamespace("olmv1-system")); err != nil { t.Fatal(err) } - if len(secrets.Items) != 0 { - t.Fatalf("COS readiness failure left Secret references: %#v", secrets.Items) + if len(secrets.Items) == 0 { + t.Fatalf("COD readiness failure removed Secret references: %#v", secrets.Items) } - if err := m.Client.Get(ctx, client.ObjectKey{Name: "sub-1"}, &ocv1.ClusterObjectSet{}); err == nil { - t.Fatal("COS readiness failure left ClusterObjectSet") + if err := m.Client.Get(ctx, client.ObjectKey{Name: "sub"}, &ocv1.ClusterObjectDeployment{}); err != nil { + t.Fatal("COD readiness failure removed ClusterObjectDeployment") } } @@ -1748,18 +1761,19 @@ func TestRecoverBeforeCEPreservesResourcesItDidNotCreate(t *testing.T) { } } +// TestRecoverCreatedMigrationResourcesPreservesActiveTargetResources refuses recovery that could destroy an active migration target. func TestRecoverCreatedMigrationResourcesPreservesActiveTargetResources(t *testing.T) { ctx := context.Background() createdSecret := corev1.Secret{ObjectMeta: metav1.ObjectMeta{Name: "created-ref", Namespace: "olmv1-system"}} otherSecret := &corev1.Secret{ObjectMeta: metav1.ObjectMeta{Name: "other-ref", Namespace: "olmv1-system"}} - createdCOS := &ocv1.ClusterObjectSet{ObjectMeta: metav1.ObjectMeta{Name: "created-1"}} - otherCOS := &ocv1.ClusterObjectSet{ObjectMeta: metav1.ObjectMeta{Name: "other-1"}} + createdCOD := &ocv1.ClusterObjectDeployment{ObjectMeta: metav1.ObjectMeta{Name: "created-1"}} + otherCOD := &ocv1.ClusterObjectDeployment{ObjectMeta: metav1.ObjectMeta{Name: "other-1"}} createdCE := &ocv1.ClusterExtension{ObjectMeta: metav1.ObjectMeta{Name: "created"}} - m := migrationTestClient(t, &createdSecret, otherSecret, createdCOS, otherCOS, createdCE) + m := migrationTestClient(t, &createdSecret, otherSecret, createdCOD, otherCOD, createdCE) sub, _ := healthySubscriptionFixtures() err := m.recoverCreatedMigrationResources(ctx, Options{SubscriptionName: sub.Name, SubscriptionNamespace: sub.Namespace}, &Backup{Subscription: sub}, &createdMigrationResources{ - cos: createdCOS, + cod: createdCOD, secrets: []corev1.Secret{createdSecret}, ce: createdCE, }) @@ -1767,14 +1781,14 @@ func TestRecoverCreatedMigrationResourcesPreservesActiveTargetResources(t *testi t.Fatalf("recovery error = %v, want preserved target resources", err) } if err := m.Client.Get(ctx, client.ObjectKeyFromObject(sub), &operatorsv1alpha1.Subscription{}); !apierrors.IsNotFound(err) { - t.Fatalf("recovery restored OLMv0 despite a potentially active COS: %v", err) + t.Fatalf("recovery restored OLMv0 despite a potentially active COD: %v", err) } - for _, object := range []client.Object{&createdSecret, createdCOS, createdCE} { + for _, object := range []client.Object{&createdSecret, createdCOD, createdCE} { if err := m.Client.Get(ctx, client.ObjectKeyFromObject(object), object); err != nil { t.Fatalf("recovery deleted created %T %q: %v", object, object.GetName(), err) } } - for _, object := range []client.Object{otherSecret, otherCOS} { + for _, object := range []client.Object{otherSecret, otherCOD} { if err := m.Client.Get(ctx, client.ObjectKeyFromObject(object), object); err != nil { t.Fatalf("recovery deleted untracked %T %q: %v", object, object.GetName(), err) } @@ -1793,18 +1807,19 @@ func TestWaitForClusterObjectSetAvailable(t *testing.T) { } } +// TestRecoverCreatedMigrationResourcesRefusesUnknownOwnership fails closed when target ownership cannot be established. func TestRecoverCreatedMigrationResourcesRefusesUnknownOwnership(t *testing.T) { ctx := context.Background() - cos := &ocv1.ClusterObjectSet{ObjectMeta: metav1.ObjectMeta{Name: "possibly-foreign-1"}} + cos := &ocv1.ClusterObjectDeployment{ObjectMeta: metav1.ObjectMeta{Name: "possibly-foreign-1"}} m := migrationTestClient(t, cos) err := m.recoverCreatedMigrationResources(ctx, Options{}, nil, &createdMigrationResources{ - cos: cos, + cod: cos, ownershipUnknown: true, }) if err == nil || !strings.Contains(err.Error(), "outcome is unknown") { t.Fatalf("recovery error = %v, want unknown ownership", err) } - if err := m.Client.Get(ctx, client.ObjectKeyFromObject(cos), &ocv1.ClusterObjectSet{}); err != nil { + if err := m.Client.Get(ctx, client.ObjectKeyFromObject(cos), &ocv1.ClusterObjectDeployment{}); err != nil { t.Fatalf("recovery deleted a resource with unknown ownership: %v", err) } } @@ -1912,19 +1927,16 @@ func TestRollbackRejectsMissingSourceNamespaceWithoutMutation(t *testing.T) { func TestPrepareDefersCOSAPIValidation(t *testing.T) { for _, present := range []bool{false, true} { t.Run(fmt.Sprintf("unestablished CRD present=%t", present), func(t *testing.T) { - m := migrationTestClient(t) + m := migrationTestClient(t, establishedClusterObjectDeploymentCRD()) if present { if err := m.Client.Create(t.Context(), &apiextensionsv1.CustomResourceDefinition{ObjectMeta: metav1.ObjectMeta{Name: clusterObjectSetCRDName}}); err != nil { t.Fatal(err) } } - opts, err := m.PrepareClusterObjectSet(t.Context(), Options{ClusterExtensionName: "example", SystemNamespace: "controller"}) + _, err := m.PrepareClusterObjectSet(t.Context(), Options{ClusterExtensionName: "example", SystemNamespace: "controller"}) if err != nil { t.Fatal(err) } - if opts.UseClusterObjectDeployment { - t.Fatal("selected COD without a COD API") - } }) } } diff --git a/specs/20260821-migration-v0-to-v1/e2e.md b/specs/20260821-migration-v0-to-v1/e2e.md index 3fdb630..0147471 100644 --- a/specs/20260821-migration-v0-to-v1/e2e.md +++ b/specs/20260821-migration-v0-to-v1/e2e.md @@ -5,7 +5,7 @@ This document tracks the implemented portion of the Phase 8 E2E plan from rejection paths, real-operator smoke scenarios, COS supersession, and an in-cluster Job that verifies ServiceAccount authentication. -The suites install experimental OLMv1 because migration requires its COS API. The +The suites install experimental OLMv1 because migration requires its COD and COS APIs. The system-managed namespace scenario uses the same profile, so standard-profile availability is not a migration gap. Dependency and APIService fixtures verify intentional compatibility refusals, not features this library is expected to implement. @@ -19,15 +19,13 @@ The handoff test checks that the ownerless migration COD has `apps.kubernetes.io/managed-by: operator-controller` before CE creation and retains the label and COD UID after adoption. Migration COS revisions carry `apps.kubernetes.io/managed-by: object-controller`. -The handoff test checks this value on the initial revision in both modes and on -the COD-generated catalog revision. Unit tests cover direct COS creation, while -the COD controller stamps its own generated revisions. +The handoff test checks this value on the initial revision and on +the COD-generated catalog revision. Unit tests reject missing COD prerequisites; the COD controller stamps its own generated revisions. Unit regressions cover definitive create rejection recovery, terminal rollout diagnostics, and rollback retries with dangling references to verified COD UIDs. -Migration automatically creates a COD named after the CE when the COD CRD exists; -otherwise it directly creates a COS using the current API definitions. -A present but unready COD CRD or a discovery error blocks migration rather than falling back. +Migration always creates a COD named after the CE. Missing, deleting, unestablished, +or unreadable COD CRDs block migration before OLMv0 mutations. No direct-COS fallback exists. COD migration requires the COD API/controller and the COD-backed CE applier merged in operator-controller PR #3058. The library's pinned API dependency alone does not install that controller. Unit tests exercise creation, preflight, readiness and @@ -43,12 +41,19 @@ pinned commit `dae9b613163a8fc5df36e3b9ad5a770a64c0048c`, then runs the handoff rollback targets. Default suites also build this pinned controller from source, using upstream build targets and the experimental installer. Docker, Git, Python 3, and `envsubst` must be available locally. Setup loads the built images into the -existing kind cluster without recreating it. +existing kind cluster without recreating it. Live setup also installs upstream's +`operatorhubio` ClusterCatalog and waits for it to serve; the catalog-migration +test uses its resolved image digest. Every live setup reapplies the catalog, including retries after partial installation. +Fixture setup skips that public catalog +and uses the locally built fixture catalog. COS/COD are experimental: only the current typed `inlineManifest`/`secretRef` entries are supported. There is no conversion of older experimental resource -schemas. Recreate clusters installed with older definitions before running these -suites. Fixture rollback verifies restoration, not OLMv0 reconciliation, because +schemas. Setup validates existing COS/COD schemas and rejects incompatible clusters +with instructions to recreate them. When all required CRDs and controller deployments exist, +setup skips the controller build and image loading; even a compatible cluster may +therefore run an older commit. Recreate the cluster to change the installed controller +commit. Fixture rollback verifies restoration, not OLMv0 reconciliation, because fixture clusters have no OLMv0 controllers. The covered targets verify revision encoding, COD adoption, and workload-preserving @@ -134,7 +139,7 @@ The currently implemented coverage is described in the Fixtures and CI sections. | Validation IDs | Scenario | Required assertions | |---|---|---| -| V1.1, V1.2, V1.3, V3.1–V3.7 | Baseline fixture migration | `check`, dry-run, COS `status.completedAt` and `Ready=True` before CE creation, CE `Installed=True`, field mappings, CE backups/audit, Sub/CSV cleanup. | +| V1.1, V1.2, V1.3, V3.1–V3.7 | Baseline fixture migration | `check`, dry-run, COD rollout completion and availability before CE creation, CE `Installed=True`, field mappings, CE backups/audit, Sub/CSV cleanup. | | V4.7 | Cross-namespace fixture migration | Target namespace is created with copied PSA/SCC labels; source Deployments are scaled to zero before target creation; CE and rendered Deployment use the target; collected source Deployment is removed while the source namespace remains. | | V4.7 | Acknowledged live namespace deletion | A real OLMv0 installation is converted with `--acknowledge-namespace-delete`; after CE installation in the target namespace, OLMv0 finalizes the CSV and the source namespace is deleted. | | V4.8 | System-managed namespace fixture migration | Against the experimental controller profile, verify the explicit opt-in omits `spec.namespace`, migration imports the prepared bundle-metadata namespace into its COS, the catalog COS takes ownership, OLMv1 manages the target Deployment there, and source copies are removed. Unit tests verify unsupported CRDs reject the mode before mutation. | @@ -380,7 +385,7 @@ make migration/test-e2e-in-cluster-job E2E_CLUSTER_NAME=library-olm-fixture-e2e make migration/e2e-teardown ``` -Readiness reporting includes a lightweight COS API availability check; this is diagnostic, not a guarantee that a later write will succeed. Preparation does not repeat that COS CRD check. COD discovery remains necessary to select the revision manager. Gather (including CLI dry-run) and migration validate the prepared revision with a strict server-side dry-run create before removing OLMv0 management. Validation and creation share the same revision and Secret-reference builders; dry-run does not persist revisions or packed Secrets. The API server validates schema, admission, and permissions, but does not run controller-level validation of referenced workloads. Rollback permits verified newer sibling handoffs while retaining resource-UID, owner, and management-label checks. +Readiness reporting includes lightweight COS and COD API availability checks; these are diagnostic, not a guarantee that a later write will succeed. Operator migration uses COD and requires the experimental COD API. Gather (including CLI dry-run) and migration validate the prepared revision with a strict server-side dry-run create before removing OLMv0 management. Validation and creation share the same revision and Secret-reference builders; dry-run does not persist revisions or packed Secrets. The API server validates schema, admission, and permissions, but does not run controller-level validation of referenced workloads. Rollback permits verified newer sibling handoffs while retaining resource-UID, owner, and management-label checks. Setup refuses existing OLM namespaces or APIs, including partial installations. Run `E2E_CLUSTER_NAME= make migration/e2e-teardown` before repeating setup. It installs the pinned controller from scratch and waits for the revision APIs, object-controller, operator-controller, and catalogd. Test targets reuse the prepared cluster without invoking setup. diff --git a/specs/20260821-migration-v0-to-v1/plan.md b/specs/20260821-migration-v0-to-v1/plan.md index f6df942..cfee0ab 100644 --- a/specs/20260821-migration-v0-to-v1/plan.md +++ b/specs/20260821-migration-v0-to-v1/plan.md @@ -42,14 +42,11 @@ revision 2 with `Prevent`, which also reaches `Succeeded=True`. Track boxcutter `ClusterObjectDeployment` (R2.7). *Exit:* documented, automated confirmation of this handoff. Verified during Phase 8 E2E. -**COD transition (R2.7), in progress:** the library selects COD creation when its CRD exists, -current-generation rollout checks, and COD-aware rollback. API types are pinned to +**COD transition (R2.7), in progress:** the library always creates a COD, checks its current-generation rollout, and performs COD-aware rollback. COD CRD presence and establishment are mandatory prerequisites for check, dry-run, and migration. API types are pinned to operator-controller commit `dae9b613163a`, matching the COD CI controller and including the adoption label requirement. Migration stamps `apps.kubernetes.io/managed-by: operator-controller` on the ownerless COD before handoff; unit and E2E assertions -check this label and preservation of the original COD identity. Directly created -COS revisions use the same key with value `object-controller` for COD adoption; -the object-controller labels COD-generated revisions itself. Rollback persists +check this label and preservation of the original COD identity. The object-controller labels COD-generated revisions with the same key and value `object-controller`; the library never creates COS revisions directly. Rollback persists verified COD UIDs before deletion to support dangling revision references on retries. Definitive API create rejections permit recovery; ambiguous failures remain conservative. The COD-backed CE applier merged in upstream @@ -65,10 +62,9 @@ passed locally on 2026-10-29. Both covered targets passed again on 2026-11-05 against `bbe43971eadd` on kind Kubernetes 1.37, verifying labeled COD adoption and rollback. The covered handoff and rollback targets also pass against `77754d81ea01`, -including COS manager-label assertions. Direct COS creation and the -`UnmanagedRevision` terminal condition are covered by unit regressions. +including COS manager-label assertions. Missing-COD rejection and the `UnmanagedRevision` terminal condition are covered by unit regressions. The current API uses typed `inlineManifest`/`secretRef` entries for creation and -rollback. Older experimental COS/COD schemas are not supported; the controller +rollback. Preflight validates the served revision-entry schemas. Revision preflight verifies opaque inline manifest preservation and string Secret-reference fields for both COS and COD. E2E setup waits for object-controller on reused clusters. Live catalogs track upstream published content; fixture catalogs provide reproducibility. Older experimental COS/COD schemas are not supported; the controller and library must use matching definitions. --- @@ -131,8 +127,8 @@ flag is set; CE carries the matching annotation. specs to CE annotations (R2.5) → optional `--backup ` of the profiled and CSV-associated InstallPlans (R2.6; deduplicate by namespace/name) → collect (primary: `Operator` CR `status.components.refs`; supplementary: `olm.owner` label query, - ownerRef query, InstallPlan steps; dedup by GVK+ns+name — see R5) → create COS (wait - `status.completedAt` and `Ready=True`) → create CE → cleanup. + ownerRef query, InstallPlan steps; dedup by GVK+ns+name — see R5) → create COD (wait + for current-generation rollout completion and availability) → create CE → cleanup. `--dry-run` previews without mutation. `--all` prints the four-section summary, then converts each Eligible operator; `--continue-on-error` to keep going. Batch classification uses the requested acknowledgment overrides; `-n` and `--ce-name` are rejected with `--all`. @@ -176,7 +172,7 @@ an explicitly selected OLMv1 system-managed namespace mode. - Move collected namespace-scoped resources to the target namespace in the migration COS and, after the target CE is installed, remove their source copies. - Delete the source namespace only with `--acknowledge-namespace-delete`; retain it by default. -- `--system-managed-install-namespace` uses the pinned operator-controller experimental +- `--system-managed-install-namespace` uses the pinned operator-controller revision's experimental optional-namespace CRD. It capability-gates the mode and omits the CE field. Migration prepares the bundle-metadata namespace before its COS and imports it for the catalog revision's ownership handoff, after which OLMv1 manages it. Unit tests @@ -236,7 +232,7 @@ Phase 1 (4717) ──► Phase 2 (4718) ──► Phase 3 (4719) ──► Phase Phase 7 (4723, operator-controller): APIService-owning operators remain unsupported; C3 is permanent ``` -Readiness reporting includes a lightweight COS API availability check; this is diagnostic, not a guarantee that a later write will succeed. Preparation does not repeat that COS CRD check. COD discovery remains necessary to select the revision manager. Gather (including CLI dry-run) and migration validate the prepared revision with a strict server-side dry-run create before removing OLMv0 management. Validation and creation share the same revision and Secret-reference builders; dry-run does not persist revisions or packed Secrets. The API server validates schema, admission, and permissions, but does not run controller-level validation of referenced workloads. Rollback permits verified newer sibling handoffs while retaining resource-UID, owner, and management-label checks. +Readiness reporting includes lightweight COS and COD API availability checks; these are diagnostic, not a guarantee that a later write will succeed. Operator migration uses COD and requires the experimental COD API. Gather (including CLI dry-run) and migration validate the prepared revision with a strict server-side dry-run create before removing OLMv0 management. Validation and creation share the same revision and Secret-reference builders; dry-run does not persist revisions or packed Secrets. The API server validates schema, admission, and permissions, but does not run controller-level validation of referenced workloads. Rollback permits verified newer sibling handoffs while retaining resource-UID, owner, and management-label checks. ## Follow-ups from the COS/COD compatibility review diff --git a/specs/20260821-migration-v0-to-v1/requirements.md b/specs/20260821-migration-v0-to-v1/requirements.md index 66d4f38..6fa6602 100644 --- a/specs/20260821-migration-v0-to-v1/requirements.md +++ b/specs/20260821-migration-v0-to-v1/requirements.md @@ -121,12 +121,11 @@ breaking API changes permitted while `v0`. Two binaries. Prow + GitHub Actions C old `ClusterExtensionRevision` name throughout; all references must be updated to `ClusterObjectSet` / `ClusterObjectSetList`. -**R2.3** — The migration tool **creates** the COS, then **waits** for the COS controller -to set `status.completedAt`, then creates the `ClusterExtension`. -the controller creates a subsequent catalog-derived COS revision rather than adopting the -migration COS. The tool **must not** write -status on any OLMv1 API. No operator-controller changes are required (verified — see -[plan.md](plan.md) prerequisite). +**R2.3** — The migration tool creates a COD and waits for its current-generation +rollout to complete and become available before creating the ClusterExtension. +The COD controller creates migration COS revisions; the library never creates a +COS directly. The CE adopts the same COD and its catalog template produces a new +revision. The tool must not write status on any OLMv1 API. **R2.4** — Collected objects are stored via boxcutter's **SecretPacker** (Secret-backed, not inline in the COS spec) to support large bundles, with @@ -151,9 +150,7 @@ The CE also carries: The directory is created if it does not exist. Failure to list associated plans warns and retains the profiled current plan. Backup does not gate migration — it is informational and aids manual recovery if the CE annotation backup is insufficient. If the directory write fails, `convert` warns and continues (the CE annotation backup is the authoritative recovery path). **R2.7 — Boxcutter phase 2.** Support one `ClusterObjectDeployment` (COD) per -ClusterExtension, with controller-managed COS revisions. The initial implementation is -selected automatically when the COD CRD exists; when absent, the direct COS -workflow uses the current COS definitions. Discovery errors must fail rather than silently fall back. COD migration requires an established +ClusterExtension, with controller-managed COS revisions. COD is the only migration path. Missing, deleting, unestablished, or unreadable COD CRDs block check, dry-run, and migration before OLMv0 resources change. COD migration requires an established COD CRD and operator-controller's COD-backed ClusterExtension applier (upstream PR #3058). Create the deployment with collision protection `None`, wait for current-generation rollout completion and availability, then create the CE to hand management to operator-controller. @@ -162,14 +159,14 @@ operator-controller retains its rollout data and can adopt it while ownerless. Preserve the same COD UID through adoption; owner-kind and owner-name metadata alone do not authorize adoption. The adoption label is not required on the COS template or operator workload objects. -Directly created migration COS revisions carry `apps.kubernetes.io/managed-by: -object-controller` so a COD can adopt an ownerless revision in its group. +Controller-created migration COS revisions carry `apps.kubernetes.io/managed-by: +object-controller`. COD-generated COS revisions receive this label from object-controller. The two manager values apply to different resources and must not be interchanged. Use the current revision object union (`type: InlineManifest` with `inlineManifest`, or `type: SecretReference` with `secretRef`). COS and COD are experimental APIs; compatibility with older COS/COD schemas and COS `Succeeded`/`Available` conditions is not supported. COS completion uses `status.completedAt`, and workload readiness uses `Ready=True`. Install a controller -with matching API definitions before migration. +with matching API definitions before migration. The COS and COD prerequisites must reject deleting CRDs and schemas that prune inline manifests or Secret-reference name, namespace, and key fields. Check the served COS/COD schemas for typed revision entries during readiness and preflight; reject incompatible definitions before any OLMv0 mutation. Reject existing deployments/revision groups before destructive work. Rollback must stop the deployment with orphan deletion before removing revisions and restoring OLMv0 management. Persist verified deployment UIDs on the CE before deletion so late revisions with @@ -379,6 +376,6 @@ unreferenced source would be deleted without changing it. - Binary packaging / `oc` plugin / container images — deferred to the downstream TP phase ([OCPSTRAT-2692](https://redhat.atlassian.net/browse/OCPSTRAT-2692)). - Console UI. -Readiness reporting includes a lightweight COS API availability check; this is diagnostic, not a guarantee that a later write will succeed. Preparation does not repeat that COS CRD check. COD discovery remains necessary to select the revision manager. Gather (including CLI dry-run) and migration validate the prepared revision with a strict server-side dry-run create before removing OLMv0 management. Validation and creation share the same revision and Secret-reference builders; dry-run does not persist revisions or packed Secrets. The API server validates schema, admission, and permissions, but does not run controller-level validation of referenced workloads. Rollback permits verified newer sibling handoffs while retaining resource-UID, owner, and management-label checks. +Readiness reporting includes lightweight COS and COD API availability checks; these are diagnostic, not a guarantee that a later write will succeed. Operator migration uses COD and requires the experimental COD API. Gather (including CLI dry-run) and migration validate the prepared revision with a strict server-side dry-run create before removing OLMv0 management. Validation and creation share the same revision and Secret-reference builders; dry-run does not persist revisions or packed Secrets. The API server validates schema, admission, and permissions, but does not run controller-level validation of referenced workloads. Rollback permits verified newer sibling handoffs while retaining resource-UID, owner, and management-label checks. Rollback persists verified resource identities and UIDs on the restored Subscription before deleting the CE backup. Remigration includes still-unowned retained resources (including catalog-generated RBAC) omitted from the OLMv0 inventory; missing resources are skipped, replacements and newly controlled resources are rejected, and normal collection is deduplicated. diff --git a/specs/20260821-migration-v0-to-v1/validation.md b/specs/20260821-migration-v0-to-v1/validation.md index 43a328b..0f8df95 100644 --- a/specs/20260821-migration-v0-to-v1/validation.md +++ b/specs/20260821-migration-v0-to-v1/validation.md @@ -12,29 +12,29 @@ kind cluster with both OLMv0 and OLMv1 installed. ## V1. Per-command behavior - **V1.1** `check -n ` on a healthy AllNamespaces operator with an available catalog reports all checks green and exits 0; makes no cluster changes. -- **V1.2** `convert -n --dry-run` lists every resource that would be migrated (grouped by kind), including CRDs, and reports the detected COS or COD manager with `CollisionProtection: None` on the COS or COD template; makes no cluster changes. -- **V1.3** `convert -n ` results in a `ClusterExtension` reaching `Installed=True`; the `Subscription` and `CSV` are deleted; CRDs remain and are adopted by OLMv1. In direct COS mode, the COS sets `status.completedAt` before the CE is created. In COD mode, the COD's current-generation rollout completes and becomes available before the CE is created; the CE then owns the same COD and its catalog revision uses `CollisionProtection: Prevent`. +- **V1.2** `convert -n --dry-run` lists every resource that would be migrated (grouped by kind), including CRDs, and reports the COD with `CollisionProtection: None` on its template; makes no cluster changes. +- **V1.3** `convert -n ` results in a `ClusterExtension` reaching `Installed=True`; the `Subscription` and `CSV` are deleted; CRDs remain and are adopted by OLMv1. Migration always uses COD: the COD's current-generation rollout completes and becomes available before the CE is created; the CE then owns the same COD and its catalog revision uses `CollisionProtection: Prevent`. - **V1.4** `rollback --acknowledge-installed` starts CE orphan deletion with a rollback finalizer to stop new revisions, records verified ownership from in-flight replacement revisions before deleting them, waits for orphaned resources to lose COS controller references, removes their OLMv1 revision metadata, restores the `Subscription` from the backup annotation, then removes the CE finalizer. A matching Subscription from a prior attempt permits retry; a conflicting Subscription or failed restoration retains the CE backup. The operator returns to OLMv0 management (`AtLatestKnown`/`UpgradePending`), and a subsequent migration can adopt preserved resources. Without `--acknowledge-installed` on an `Installed=True` CE, rollback refuses and exits non-zero. - In COD mode, verify CE-to-COD and COD-to-COS ownership and stop the COD with orphan deletion before removing its COS revisions, preventing replacement revisions during rollback. Before deletion and during subsequent revision discovery, reject controlled COS revisions unless the controller's API version, kind, name, and UID match the CE or its verified COD. Require the current `spec.group` identity even for unowned staging or orphaned revisions; a name or owner label alone cannot authorize deletion. Preserve workloads and retain the CE backup if cleanup or restoration fails. + Verify CE-to-COD and COD-to-COS ownership and stop the COD with orphan deletion before removing its COS revisions, preventing replacement revisions during rollback. Before deletion and during subsequent revision discovery, reject controlled COS revisions unless the controller's API version, kind, name, and UID match the CE or its verified COD. Require the current `spec.group` identity even for unowned staging or orphaned revisions; a name or owner label alone cannot authorize deletion. Preserve workloads and retain the CE backup if cleanup or restoration fails. - **V1.5** `cleanup ` on a Conflict state deletes the `Subscription` and OLMv0 artifacts (Operator CR, OperatorCondition, copied CSVs, OperatorGroup if last) and leaves the CE intact. - **V1.6** `check --all` and `convert --all` print sections in order Conflict → Ineligible → AlreadyMigrated → Eligible; Conflicts are never auto-migrated; `convert --all` migrates only the Eligible operators. Batch acknowledgment flags affect classification before selection; `convert --all` rejects `-n` and `--ce-name` rather than ignoring them. - **V1.7** `convert --all` stops on the first failure by default; with `--continue-on-error` it logs the failure and continues, exiting non-zero if any operator failed. - **V1.8** No command ever blocks on interactive input. An operator whose name collides with a verb (e.g. `check`) is migratable as a positional argument (`convert check -n `). -- **V1.9** Manager detection selects direct COS when the COD CRD is absent and COD when it is present and established. Discovery errors and unmet prerequisites fail before deleting OLMv0 resources. Validate COD name/group constraints and reject an existing COD rather than overwriting it. CRD presence is the supported capability signal; controller-version detection is not required. +- **V1.9** COD is mandatory. Missing, deleting, or unestablished COD CRDs fail readiness, dry-run, and migration without mutating cluster resources; no COS is created directly. Discovery errors and unmet prerequisites fail before deleting OLMv0 resources. Validate COD name/group constraints and reject an existing COD rather than overwriting it. CRD presence is the supported capability signal; controller-version detection is not required. Preflight regression cases cover deleting COS/COD CRDs, pruned inline manifests, nested pruning, missing Secret-reference fields, incorrect field types, and valid unknown-field preservation, without creating or deleting migration resources. - **V1.10** The COD template preserves migration labels, annotations, packed Secret references, and `CollisionProtection: None`. Readiness requires completion and availability for the current generation; stale status cannot satisfy the wait. Invalid-specification and deadline failures report actionable errors. Once a COD may have reconciled, failure preserves migration resources and refuses automatic OLMv0 recovery. The COD itself carries `apps.kubernetes.io/managed-by: operator-controller` before CE creation and after adoption. It has no controller owner during staging, then gains the CE controller reference while retaining its UID. The template continues to carry extension identity metadata without copying this COD-specific adoption label onto operator workloads. - Directly created migration COS revisions carry `apps.kubernetes.io/managed-by: - object-controller` and remain ownerless during staging. COD-generated migration + COD-generated migration COS revisions carry `apps.kubernetes.io/managed-by: + object-controller` and are owned by their COD during staging. COD-generated migration and catalog revisions carry the same COS label, while the COD retains its distinct `operator-controller` value. Assert inline and Secret-backed object encodings using the current COS/COD definitions, including workload preservation during rollback. Older experimental schemas are outside the compatibility requirements. - Assert prompt failures for all current-generation terminal `Progressing=False` reasons except successful completion, including revision collisions and invalid revisions; preserve the controller's reason and message. Definitive COS/COD create rejections restore OLMv0 and report that the target cannot be active; timeouts and transport failures refuse automatic recovery. + Assert prompt failures for all current-generation terminal `Progressing=False` reasons except successful completion, including revision collisions and invalid revisions; preserve the controller's reason and message. Definitive COD create rejections restore OLMv0 and report that the target cannot be active; timeouts and transport failures refuse automatic recovery. Rollback persists verified COD UIDs before deletion and accepts matching dangling references even after restarting rollback. Unknown UIDs remain rejected, and failure to persist verified identity prevents COD deletion. ## V2. Eligibility matrix (one case per check, R3) @@ -87,10 +87,10 @@ flag flips it to `Eligible`: - **V4.4** Dependency operator (`olm.generated-by` present / declares requirements) → flagged; an operator others depend on migrates but emits a dependents warning. - **V4.5** OperatorCondition disambiguation: an operator with OLMv0-stamped OperatorCondition RBAC but **empty** `status.conditions` is **Eligible** (RBAC is not treated as usage). - **V4.6** Large bundle exceeding inline size limits migrates successfully via SecretPacker. -- **V4.7** Namespace change copies `pod-security.kubernetes.io/*` and `security.openshift.io/scc.podSecurityLabelSync` to the new namespace. An existing target with no explicit PSA `enforce` label is rejected when the source sets one, because its cluster default is not observable. Collected source Deployments scale to zero before target creation so two controllers do not overlap. They return to their original replica count only when target COS creation failed before it may have reconciled; otherwise migration reports that the target may be active, leaves the source scaled down, and refuses automatic OLMv0 recovery. The target operator resources are present and their collected source copies are removed. The fixture scenario retains the old namespace by default; the live scenario passes `--acknowledge-namespace-delete` and verifies the source namespace is deleted after OLMv0 finalizes its CSV. -- **V4.8** System-managed namespace: against the pinned operator-controller experimental CRD, +- **V4.7** Namespace change copies `pod-security.kubernetes.io/*` and `security.openshift.io/scc.podSecurityLabelSync` to the new namespace. An existing target with no explicit PSA `enforce` label is rejected when the source sets one, because its cluster default is not observable. Collected source Deployments scale to zero before target creation so two controllers do not overlap. They return to their original replica count only when target COD creation failed before it may have reconciled; otherwise migration reports that the target may be active, leaves the source scaled down, and refuses automatic OLMv0 recovery. The target operator resources are present and their collected source copies are removed. The fixture scenario retains the old namespace by default; the live scenario passes `--acknowledge-namespace-delete` and verifies the source namespace is deleted after OLMv0 finalizes its CSV. +- **V4.8** System-managed namespace: against the pinned experimental operator-controller revision, explicit system-managed conversion omits `ClusterExtension.spec.namespace`, prepares the - bundle-metadata namespace for the preceding COS, includes it in the migration revision, + bundle-metadata namespace for the COD rollout, includes it in the migration revision, and verifies the catalog revision takes Namespace ownership while OLMv1 manages the installation there. The same invocation against a CRD that requires the field is rejected before mutation with an actionable error. A conversion with neither namespace flag continues to use the Subscription @@ -106,7 +106,7 @@ flag flips it to `Eligible`: - **V5.6** `convert -n ` → CE `Installed=True`; Subscription/CSV deleted; CRDs adopted (demonstrates close-to-zero downtime with namespace unchanged). - **V5.7** Upgrade via OLMv1 → CRDs updated through the normal bundle lifecycle. - **V5.8** `rollback --acknowledge-installed` → Subscription restored, CE and COS revisions deleted, preserved Deployments released from OLMv1 ownership; a second `convert` creates new CE/COS UIDs, installs successfully, and adopts the same Deployment UIDs. - In COD mode, also verify the COD is deleted and no COS remains in its group, while the Deployment UID and availability are preserved. Fixture tests assert restored Subscription state; OLMv0 reconciliation requires the live environment. + Also verify the COD is deleted and no COS remains in its group, while the Deployment UID and availability are preserved. Fixture tests assert restored Subscription state; OLMv0 reconciliation requires the live environment. - **V5.9** Fresh cluster with operators in all four states → `check --all` → correct four-section output; `convert --all` warns on Conflicts and migrates only Eligible. - **V5.10** On a COD-capable controller, fixture migration creates one COD named for the CE. Catalog handoff retains that COD's UID, establishes CE ownership of the COD and COD ownership of successive COS revisions in the same group, and retains the migration revision (`None`) alongside a new catalog revision (`Prevent`). Verify the migration COS retains its UID and both revisions retain their respective collision-protection settings. Run handoff and fixture conversion/rollback (V5.8) in the dedicated COD CI job, collecting coverage separately from the other fixture tests. @@ -140,8 +140,8 @@ flag flips it to `Eligible`: | R1.7 Downtime posture | V5.6 (namespace unchanged), V4.7 (namespace change) | | R1.8 Recovery | V1.4, V1.5 | | R2.1 v0 module + CI | V7.1, V7.3 | -| R2.2 ClusterObjectSet rename | V1.3 (COS created), V4.6 | -| R2.3 Wait for COS Succeeded; no status writes | V1.3 | +| R2.2 ClusterObjectSet rename | V1.3 (COD creates COS revisions), V4.6 | +| R2.3 Wait for COD rollout; no status writes | V1.3 | | R2.4 SecretPacker + collision handling | V1.2, V4.2, V4.6 | | R2.5 CE annotations | V3.6 | | R2.6 `--backup ` flag | V3.18 | @@ -155,6 +155,6 @@ flag flips it to `Eligible`: | R9 Edge cases | V4.1–V4.8 | | R10 Non-goals | V6.4, V6.5 | -Readiness reporting includes a lightweight COS API availability check; this is diagnostic, not a guarantee that a later write will succeed. Preparation does not repeat that COS CRD check. COD discovery remains necessary to select the revision manager. Gather (including CLI dry-run) and migration validate the prepared revision with a strict server-side dry-run create before removing OLMv0 management. Validation and creation share the same revision and Secret-reference builders; dry-run does not persist revisions or packed Secrets. The API server validates schema, admission, and permissions, but does not run controller-level validation of referenced workloads. Rollback permits verified newer sibling handoffs while retaining resource-UID, owner, and management-label checks. +Readiness reporting includes lightweight COS and COD API availability checks; these are diagnostic, not a guarantee that a later write will succeed. Operator migration uses COD and requires the experimental COD API. Gather (including CLI dry-run) and migration validate the prepared revision with a strict server-side dry-run create before removing OLMv0 management. Validation and creation share the same revision and Secret-reference builders; dry-run does not persist revisions or packed Secrets. The API server validates schema, admission, and permissions, but does not run controller-level validation of referenced workloads. Rollback permits verified newer sibling handoffs while retaining resource-UID, owner, and management-label checks. Rollback persists verified resource identities and UIDs on the restored Subscription before deleting the CE backup. Remigration includes still-unowned retained resources (including catalog-generated RBAC) omitted from the OLMv0 inventory; missing resources are skipped, replacements and newly controlled resources are rejected, and normal collection is deduplicated. diff --git a/test/e2e/migration/e2e_test.go b/test/e2e/migration/e2e_test.go index be5cd4f..abfc413 100644 --- a/test/e2e/migration/e2e_test.go +++ b/test/e2e/migration/e2e_test.go @@ -334,16 +334,14 @@ func TestPrecreatedClusterObjectSetSupersession(t *testing.T) { } precreatedUID := before.Items[0].UID var originalCOD ocv1.ClusterObjectDeployment - if opts.UseClusterObjectDeployment { - if err := kubeClient.Get(ctx, client.ObjectKey{Name: subscription}, &originalCOD); err != nil { - t.Fatal(err) - } - if !metav1.IsControlledBy(&before.Items[0], &originalCOD) || before.Items[0].Spec.Group != subscription { - t.Fatal("migration revision is not controlled by its COD") - } - if originalCOD.Labels["apps.kubernetes.io/managed-by"] != "operator-controller" || metav1.GetControllerOf(&originalCOD) != nil { - t.Fatal("staging COD must be ownerless and carry the operator-controller adoption label") - } + if err := kubeClient.Get(ctx, client.ObjectKey{Name: subscription}, &originalCOD); err != nil { + t.Fatal(err) + } + if !metav1.IsControlledBy(&before.Items[0], &originalCOD) || before.Items[0].Spec.Group != subscription { + t.Fatal("migration revision is not controlled by its COD") + } + if originalCOD.Labels["apps.kubernetes.io/managed-by"] != "operator-controller" || metav1.GetControllerOf(&originalCOD) != nil { + t.Fatal("staging COD must be ownerless and carry the operator-controller adoption label") } if precreatedUID == "" { t.Fatal("pre-existing COS has no UID") @@ -394,29 +392,25 @@ func TestPrecreatedClusterObjectSetSupersession(t *testing.T) { if catalogCOS.Spec.CollisionProtection != ocv1.CollisionProtectionPrevent { t.Fatalf("catalog COS collisionProtection = %q, want %q", catalogCOS.Spec.CollisionProtection, ocv1.CollisionProtectionPrevent) } - if opts.UseClusterObjectDeployment { - var currentCOD ocv1.ClusterObjectDeployment - var ce ocv1.ClusterExtension - if err := kubeClient.Get(ctx, client.ObjectKey{Name: subscription}, ¤tCOD); err != nil { - t.Fatal(err) - } - if err := kubeClient.Get(ctx, client.ObjectKey{Name: subscription}, &ce); err != nil { - t.Fatal(err) - } - if currentCOD.UID != originalCOD.UID || !metav1.IsControlledBy(¤tCOD, &ce) { - t.Fatal("CE did not take ownership of the original COD") - } - if currentCOD.Labels["apps.kubernetes.io/managed-by"] != "operator-controller" { - t.Fatal("adopted COD lost its operator-controller management label") - } - if !metav1.IsControlledBy(catalogCOS, ¤tCOD) || catalogCOS.Spec.Group != subscription { - t.Fatal("catalog revision is not controlled by the original COD") - } - if catalogCOS.Labels["apps.kubernetes.io/managed-by"] != "object-controller" { - t.Fatal("COD-generated catalog revision lacks the object-controller label") - } - } else if len(catalogCOS.OwnerReferences) != 1 || catalogCOS.OwnerReferences[0].Name != subscription { - t.Fatalf("catalog COS ownerReferences = %#v, want ClusterExtension %q", catalogCOS.OwnerReferences, subscription) + var currentCOD ocv1.ClusterObjectDeployment + var ce ocv1.ClusterExtension + if err := kubeClient.Get(ctx, client.ObjectKey{Name: subscription}, ¤tCOD); err != nil { + t.Fatal(err) + } + if err := kubeClient.Get(ctx, client.ObjectKey{Name: subscription}, &ce); err != nil { + t.Fatal(err) + } + if currentCOD.UID != originalCOD.UID || !metav1.IsControlledBy(¤tCOD, &ce) { + t.Fatal("CE did not take ownership of the original COD") + } + if currentCOD.Labels["apps.kubernetes.io/managed-by"] != "operator-controller" { + t.Fatal("adopted COD lost its operator-controller management label") + } + if !metav1.IsControlledBy(catalogCOS, ¤tCOD) || catalogCOS.Spec.Group != subscription { + t.Fatal("catalog revision is not controlled by the original COD") + } + if catalogCOS.Labels["apps.kubernetes.io/managed-by"] != "object-controller" { + t.Fatal("COD-generated catalog revision lacks the object-controller label") } if err := m.WaitForCOSSucceeded(ctx, catalogCOS.Name); err != nil { t.Fatalf("catalog revision did not complete: %v", err) From 4a2a687bac83112f760150818bc9a459692ddd53 Mon Sep 17 00:00:00 2001 From: Todd Short Date: Wed, 11 Nov 2026 14:04:11 -0500 Subject: [PATCH 02/10] fix: share migration defaults and clarify COD preview Apply defaults before creating either migration resource so unnamed requests use the same COD and ClusterExtension name. Cover default and explicit names, and report collision protection under the COD template in dry-run output. Signed-off-by: Todd Short --- .../cmd/migrate-operators-v0-to-v1/convert.go | 2 +- .../convert_test.go | 7 +++ migration/pkg/migration/deployment_test.go | 44 +++++++++++++++++++ migration/pkg/migration/migration.go | 1 + 4 files changed, 53 insertions(+), 1 deletion(-) diff --git a/migration/examples/cmd/migrate-operators-v0-to-v1/convert.go b/migration/examples/cmd/migrate-operators-v0-to-v1/convert.go index 5c1339a..fcd11cf 100644 --- a/migration/examples/cmd/migrate-operators-v0-to-v1/convert.go +++ b/migration/examples/cmd/migrate-operators-v0-to-v1/convert.go @@ -271,6 +271,7 @@ func printDryRunPreview(opts, resourceOpts migration.Options, info *migration.Mi success(fmt.Sprintf("Package: %s Version: %s Channel: %s", info.PackageName, info.Version, valueOrDefault(info.Channel, "(default)"))) fmt.Printf("\n Resources that would be created:\n") detail("ClusterObjectDeployment:", fmt.Sprintf("%s (wait for rollout completion and availability before creating the ClusterExtension)", opts.ClusterExtensionName)) + detail("Template CollisionProtection:", "None") fmt.Printf("\n Resources that would be placed into its template and controller-created COS revisions:\n") kindCounts := make(map[string]int) @@ -295,7 +296,6 @@ func printDryRunPreview(opts, resourceOpts migration.Options, info *migration.Mi detail("Version:", "(unset — automatic channel-based upgrades)") } detail("Channel:", valueOrDefault(info.Channel, "(none set)")) - detail("CollisionProtection:", "None") fmt.Printf("\n OLMv0 resources that would be deleted or changed:\n") for _, line := range dryRunCleanupPlan(opts, resourceOpts, info) { diff --git a/migration/examples/cmd/migrate-operators-v0-to-v1/convert_test.go b/migration/examples/cmd/migrate-operators-v0-to-v1/convert_test.go index 6de209e..aac7d72 100644 --- a/migration/examples/cmd/migrate-operators-v0-to-v1/convert_test.go +++ b/migration/examples/cmd/migrate-operators-v0-to-v1/convert_test.go @@ -56,6 +56,13 @@ func TestDryRunPreviewSortsResourceKinds(t *testing.T) { if result.err != nil { t.Fatal(result.err) } + for _, preview := range strings.Split(string(result.output), "Resources that would be created:")[1:] { + protection := strings.Index(preview, "Template CollisionProtection:") + extension := strings.Index(preview, "ClusterExtension that would be created:") + if protection < 0 || extension <= protection || strings.Count(preview, "CollisionProtection:") != 1 { + t.Fatalf("collision protection must appear only with the COD template: %s", preview) + } + } sections := strings.Split(string(result.output), "Resources that would be placed into its template and controller-created COS revisions:") if len(sections) != 6 { t.Fatalf("got %d preview sections, want 5", len(sections)-1) diff --git a/migration/pkg/migration/deployment_test.go b/migration/pkg/migration/deployment_test.go index f8effc8..5364ec1 100644 --- a/migration/pkg/migration/deployment_test.go +++ b/migration/pkg/migration/deployment_test.go @@ -519,3 +519,47 @@ func TestMissingCODBlocksMigrationBeforeMutation(t *testing.T) { t.Fatal("migration accepted missing COD support") } } + +// TestCreateMigrationResourcesSharesDefaults verifies COD and CE creation use the +// same defaulted identity and namespace, while retaining explicit CE names. +func TestCreateMigrationResourcesSharesDefaults(t *testing.T) { + for _, name := range []string{"", "custom"} { + t.Run("name="+name, func(t *testing.T) { + m := migrationTestClient(t, establishedClusterObjectDeploymentCRD()) + m.Client = interceptor.NewClient(m.Client.(client.WithWatch), interceptor.Funcs{ + Create: func(ctx context.Context, c client.WithWatch, obj client.Object, opts ...client.CreateOption) error { + switch resource := obj.(type) { + case *ocv1.ClusterObjectDeployment: + ready := readyDeployment() + resource.UID, resource.Generation, resource.Status = ready.UID, ready.Generation, ready.Status + case *ocv1.ClusterExtension: + resource.UID = "extension" + resource.Status.Conditions = []metav1.Condition{{Type: ocv1.TypeInstalled, Status: metav1.ConditionTrue}} + } + return c.Create(ctx, obj, opts...) + }, + }) + ctx, cancel := context.WithTimeout(t.Context(), time.Second) + defer cancel() + opts := Options{SubscriptionName: "subscription", SubscriptionNamespace: "source", ClusterExtensionName: name, SystemNamespace: "controller"} + if _, err := m.CreateMigrationResources(ctx, opts, &MigrationInfo{PackageName: "package", Channel: "stable"}, &Backup{}); err != nil { + t.Fatal(err) + } + expected := name + if expected == "" { + expected = "subscription" + } + var cod ocv1.ClusterObjectDeployment + if err := m.Client.Get(ctx, client.ObjectKey{Name: expected}, &cod); err != nil { + t.Fatal(err) + } + var ce ocv1.ClusterExtension + if err := m.Client.Get(ctx, client.ObjectKey{Name: expected}, &ce); err != nil { + t.Fatal(err) + } + if cod.Spec.Template.Metadata.Labels[LabelOwnerName] != expected || ce.Spec.Namespace != "source" { + t.Fatalf("inconsistent defaults: COD owner label=%q CE namespace=%q", cod.Spec.Template.Metadata.Labels[LabelOwnerName], ce.Spec.Namespace) + } + }) + } +} diff --git a/migration/pkg/migration/migration.go b/migration/pkg/migration/migration.go index e0b8e19..377a247 100644 --- a/migration/pkg/migration/migration.go +++ b/migration/pkg/migration/migration.go @@ -619,6 +619,7 @@ func (m *Migrator) CreateClusterObjectSet(ctx context.Context, opts Options, inf // as one recoverable operation. Its result reports whether a target COD may have // started reconciling, including when cleanup was requested after a failure. func (m *Migrator) CreateMigrationResources(ctx context.Context, opts Options, info *MigrationInfo, backup *Backup) (MigrationResourcesResult, error) { + opts.ApplyDefaults() resources, err := m.createMigrationDeployment(ctx, opts, info) if err != nil { result := MigrationResourcesResult{TargetMayBeActive: resources.cod != nil || resources.ownershipUnknown} From 2f04cedd9e01a5172c32d72075ed209dd86d7dac Mon Sep 17 00:00:00 2001 From: Todd Short Date: Wed, 11 Nov 2026 15:58:08 -0500 Subject: [PATCH 03/10] test: exercise the missing COD migration readiness gate Provide a valid image-backed CatalogSource so Migrate reaches readiness validation. Assert that missing COD support is the only failed check and that migration returns the readiness error without mutating resources. Signed-off-by: Todd Short --- migration/pkg/migration/deployment_test.go | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/migration/pkg/migration/deployment_test.go b/migration/pkg/migration/deployment_test.go index 5364ec1..88f8cbd 100644 --- a/migration/pkg/migration/deployment_test.go +++ b/migration/pkg/migration/deployment_test.go @@ -482,7 +482,16 @@ func establishedClusterObjectDeploymentCRD() *apiextensionsv1.CustomResourceDefi // TestMissingCODBlocksMigrationBeforeMutation checks that missing COD support prevents destructive migration work. func TestMissingCODBlocksMigrationBeforeMutation(t *testing.T) { sub, csv := healthySubscriptionFixtures() - m := migrationTestClient(t, sub, csv, establishedClusterObjectSetCRD()) + sub.Spec.CatalogSource = "catalog" + sub.Spec.CatalogSourceNamespace = "catalogs" + catalog := &operatorsv1alpha1.CatalogSource{ + ObjectMeta: metav1.ObjectMeta{Name: "catalog", Namespace: "catalogs"}, + Spec: operatorsv1alpha1.CatalogSourceSpec{ + SourceType: operatorsv1alpha1.SourceTypeGrpc, + Image: "registry.example/catalog:latest", + }, + } + m := migrationTestClient(t, sub, csv, catalog, establishedClusterObjectSetCRD()) m.Client = interceptor.NewClient(m.Client.(client.WithWatch), interceptor.Funcs{ Create: func(context.Context, client.WithWatch, client.Object, ...client.CreateOption) error { t.Fatal("created a resource without COD support") @@ -509,14 +518,14 @@ func TestMissingCODBlocksMigrationBeforeMutation(t *testing.T) { found = true } } - if !found { + if !found || len(report.FailedChecks()) != 1 { t.Fatalf("readiness did not report missing COD support: %+v", report) } if _, err := m.Gather(ctx, opts); err == nil || !strings.Contains(err.Error(), clusterObjectDeploymentCRDName) { t.Fatalf("dry-run Gather did not reject missing COD: %v", err) } - if err := m.Migrate(ctx, opts); err == nil { - t.Fatal("migration accepted missing COD support") + if err := m.Migrate(ctx, opts); err == nil || !strings.Contains(err.Error(), "readiness checks failed (1 issues)") { + t.Fatalf("migration did not reject missing COD at readiness: %v", err) } } From 5d2464a18aee4f1dd87a649cc62027a23f4c2f70 Mon Sep 17 00:00:00 2001 From: Todd Short Date: Wed, 11 Nov 2026 16:09:53 -0500 Subject: [PATCH 04/10] fix: protect COD rollouts before enabling CE adoption Stage the COD with None and no adoption label. After initial rollout completion and availability, atomically switch to Prevent, remove permissive phase/object overrides, and enable adoption before creating the CE. Revalidate identity, generation, ownership, and readiness on status conflicts; preserve resources and refuse recovery after failed or uncertain handoffs. Add unit coverage for atomic transition and failure paths, and a coverage-enabled negative E2E test proving later rollouts reject unrelated existing objects. Validate all subsequent revision protection without assuming a fixed revision count. Update dry-run output and migration specifications. Signed-off-by: Todd Short --- migration.mk | 2 +- .../cmd/migrate-operators-v0-to-v1/convert.go | 2 +- migration/pkg/migration/deployment.go | 48 ++++- migration/pkg/migration/deployment_test.go | 180 +++++++++++++++++- specs/20260821-migration-v0-to-v1/e2e.md | 27 ++- specs/20260821-migration-v0-to-v1/plan.md | 14 ++ .../requirements.md | 12 +- .../20260821-migration-v0-to-v1/validation.md | 16 +- test/e2e/migration/cod_collision_test.go | 104 ++++++++++ test/e2e/migration/e2e_test.go | 39 +++- 10 files changed, 416 insertions(+), 28 deletions(-) create mode 100644 test/e2e/migration/cod_collision_test.go diff --git a/migration.mk b/migration.mk index 9d565b3..ea67d46 100644 --- a/migration.mk +++ b/migration.mk @@ -264,7 +264,7 @@ migration/test-e2e-cos-supersession: migration/build ## Verify migration COS is mkdir -p "$$(dirname "$$coverage_profile")"; \ KUBECONFIG="$(E2E_FIXTURE_KUBECONFIG)" ./hack/e2e/migration/delete-v1.sh "$$package"; \ KUBECONFIG="$(E2E_FIXTURE_KUBECONFIG)" ./hack/e2e/migration/install-fixture-v0.sh "$$package"; \ - KUBECONFIG="$(E2E_FIXTURE_KUBECONFIG)" E2E_ARTIFACTS="$(E2E_ARTIFACTS)/cos-supersession" E2E_SUITE=fixture E2E_COS_SUPERSESSION_TEST=true E2E_NAMESPACE=migration-e2e-ecr-secret E2E_SUBSCRIPTION="$$package" go test -count=1 -tags=e2e -covermode=count -coverpkg=./migration/... -coverprofile="$$coverage_profile" ./test/e2e/migration -run '^TestPrecreatedClusterObjectSetSupersession$$' -timeout "$(E2E_TIMEOUT)"; \ + KUBECONFIG="$(E2E_FIXTURE_KUBECONFIG)" E2E_ARTIFACTS="$(E2E_ARTIFACTS)/cos-supersession" E2E_SUITE=fixture E2E_COS_SUPERSESSION_TEST=true E2E_NAMESPACE=migration-e2e-ecr-secret E2E_SUBSCRIPTION="$$package" go test -count=1 -tags=e2e -covermode=count -coverpkg=./migration/... -coverprofile="$$coverage_profile" ./test/e2e/migration -run '^Test(PrecreatedClusterObjectSetSupersession|CODProtectedRolloutCollision)$$' -timeout "$(E2E_TIMEOUT)"; \ if [[ "$(E2E_KEEP_RESOURCES)" != true ]]; then \ KUBECONFIG="$(E2E_FIXTURE_KUBECONFIG)" ./hack/e2e/migration/delete-v1.sh "$$package"; \ else \ diff --git a/migration/examples/cmd/migrate-operators-v0-to-v1/convert.go b/migration/examples/cmd/migrate-operators-v0-to-v1/convert.go index fcd11cf..0177756 100644 --- a/migration/examples/cmd/migrate-operators-v0-to-v1/convert.go +++ b/migration/examples/cmd/migrate-operators-v0-to-v1/convert.go @@ -271,7 +271,7 @@ func printDryRunPreview(opts, resourceOpts migration.Options, info *migration.Mi success(fmt.Sprintf("Package: %s Version: %s Channel: %s", info.PackageName, info.Version, valueOrDefault(info.Channel, "(default)"))) fmt.Printf("\n Resources that would be created:\n") detail("ClusterObjectDeployment:", fmt.Sprintf("%s (wait for rollout completion and availability before creating the ClusterExtension)", opts.ClusterExtensionName)) - detail("Template CollisionProtection:", "None") + detail("Template CollisionProtection:", "None initially; Prevent before enabling ClusterExtension adoption") fmt.Printf("\n Resources that would be placed into its template and controller-created COS revisions:\n") kindCounts := make(map[string]int) diff --git a/migration/pkg/migration/deployment.go b/migration/pkg/migration/deployment.go index 6a9f28f..41d3c47 100644 --- a/migration/pkg/migration/deployment.go +++ b/migration/pkg/migration/deployment.go @@ -89,7 +89,51 @@ func (m *Migrator) createClusterObjectDeployment(ctx context.Context, opts Optio return fmt.Errorf("create ClusterObjectDeployment: %w", err) } resources.cod = cod - return m.waitForDeployment(ctx, cod) + if err := m.waitForDeployment(ctx, cod); err != nil { + return err + } + return m.protectDeploymentForAdoption(ctx, cod) +} + +// protectDeploymentForAdoption atomically enables collision protection and CE +// adoption after initial rollout. Status conflicts retry; template or identity +// changes fail closed. Recovery preserves the potentially active COD rather +// than restoring OLMv0. +func (m *Migrator) protectDeploymentForAdoption(ctx context.Context, created *ocv1.ClusterObjectDeployment) error { + return retry.RetryOnConflict(retry.DefaultRetry, func() error { + var cod ocv1.ClusterObjectDeployment + if err := m.Client.Get(ctx, client.ObjectKeyFromObject(created), &cod); err != nil { + return fmt.Errorf("get COD before protected handoff: %w", err) + } + if cod.UID != created.UID || cod.Generation != created.Generation || cod.DeletionTimestamp != nil || metav1.GetControllerOf(&cod) != nil || cod.Labels[controllerManagedByLabel] != "" || cod.Annotations[migrationInvocationAnnotation] != created.Annotations[migrationInvocationAnnotation] { + return fmt.Errorf("migration ClusterObjectDeployment %s changed before protected handoff", cod.Name) + } + progress := apimeta.FindStatusCondition(cod.Status.Conditions, ocv1.ClusterObjectDeploymentTypeProgressing) + available := apimeta.FindStatusCondition(cod.Status.Conditions, ocv1.ClusterObjectDeploymentTypeAvailable) + if progress == nil || progress.ObservedGeneration != cod.Generation || progress.Status != metav1.ConditionFalse || progress.Reason != ocv1.ClusterObjectDeploymentReasonNewClusterObjectSetProgressed || available == nil || available.ObservedGeneration != cod.Generation || available.Status != metav1.ConditionTrue { + return fmt.Errorf("migration ClusterObjectDeployment %s is not ready for protected handoff", cod.Name) + } + before := cod.DeepCopy() + cod.Spec.Template.Spec.CollisionProtection = ocv1.CollisionProtectionPrevent + // PhaseSort and collected objects use None for initial adoption. Remove all + // overrides so every subsequent object inherits the protected template. + for i := range cod.Spec.Template.Spec.Phases { + phase := &cod.Spec.Template.Spec.Phases[i] + phase.CollisionProtection = "" + for j := range phase.Objects { + phase.Objects[j].CollisionProtection = "" + } + } + if cod.Labels == nil { + cod.Labels = map[string]string{} + } + cod.Labels[controllerManagedByLabel] = "operator-controller" + if err := m.Client.Patch(ctx, &cod, client.MergeFromWithOptions(before, client.MergeFromWithOptimisticLock{})); err != nil { + return fmt.Errorf("protect COD and enable CE adoption: %w", err) + } + *created = cod + return nil + }) } // waitForDeployment waits for the created deployment to complete its current rollout and become available. @@ -287,7 +331,7 @@ func buildClusterObjectDeployment(opts Options, info *MigrationInfo, phases []*o } configuration := ocv1ac.ClusterObjectDeployment(opts.ClusterExtensionName). WithAnnotations(annotations). - WithLabels(map[string]string{LabelOwnerKind: ocv1.ClusterExtensionKind, LabelOwnerName: opts.ClusterExtensionName, controllerManagedByLabel: "operator-controller"}). + WithLabels(map[string]string{LabelOwnerKind: ocv1.ClusterExtensionKind, LabelOwnerName: opts.ClusterExtensionName}). WithSpec(ocv1ac.ClusterObjectDeploymentSpec().WithTemplate( ocv1ac.ClusterObjectDeploymentTemplate(). WithMetadata(ocv1ac.ClusterObjectDeploymentTemplateMetadata(). diff --git a/migration/pkg/migration/deployment_test.go b/migration/pkg/migration/deployment_test.go index 88f8cbd..da5da80 100644 --- a/migration/pkg/migration/deployment_test.go +++ b/migration/pkg/migration/deployment_test.go @@ -3,6 +3,7 @@ package migration import ( "context" "errors" + "fmt" "reflect" "strings" "testing" @@ -12,6 +13,7 @@ import ( apiextensionsv1 "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1" apierrors "k8s.io/apimachinery/pkg/api/errors" metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/runtime/schema" "sigs.k8s.io/controller-runtime/pkg/client" "sigs.k8s.io/controller-runtime/pkg/client/interceptor" @@ -230,6 +232,9 @@ type completingDeploymentClient struct{ client.Client } // Create simulates controller completion for deployment creation tests. func (c completingDeploymentClient) Create(ctx context.Context, obj client.Object, opts ...client.CreateOption) error { if cod, ok := obj.(*ocv1.ClusterObjectDeployment); ok { + if cod.Labels[controllerManagedByLabel] != "" || cod.Spec.Template.Spec.CollisionProtection != ocv1.CollisionProtectionNone { + return errors.New("initial COD must use None without its adoption label") + } ready := readyDeployment() cod.UID, cod.Generation, cod.Status = ready.UID, ready.Generation, ready.Status } @@ -244,7 +249,7 @@ func TestCreateDeploymentTemplate(t *testing.T) { if err != nil { t.Fatal(err) } - if resources.cod == nil || resources.cod.Spec.Template.Spec.CollisionProtection != ocv1.CollisionProtectionNone { + if resources.cod == nil || resources.cod.Spec.Template.Spec.CollisionProtection != ocv1.CollisionProtectionPrevent { t.Fatalf("unexpected deployment: %+v", resources.cod) } if resources.cod.Annotations[migrationInvocationAnnotation] != "invocation" { @@ -572,3 +577,176 @@ func TestCreateMigrationResourcesSharesDefaults(t *testing.T) { }) } } + +// TestProtectedCODHandoff verifies the atomic handoff and refuses stale identity, +// status, ownership, and concurrent-write outcomes without enabling adoption. +func TestProtectedCODHandoff(t *testing.T) { + for _, tc := range []struct { + name string + change func(*ocv1.ClusterObjectDeployment) + patchError error + }{ + {name: "ready"}, + {name: "replacement", change: func(c *ocv1.ClusterObjectDeployment) { c.UID = "replacement" }}, + {name: "changed template", change: func(c *ocv1.ClusterObjectDeployment) { c.Generation++ }}, + {name: "stale progress", change: func(c *ocv1.ClusterObjectDeployment) { c.Status.Conditions[0].ObservedGeneration-- }}, + {name: "unavailable", change: func(c *ocv1.ClusterObjectDeployment) { c.Status.Conditions[1].Status = metav1.ConditionFalse }}, + {name: "already adoptable", change: func(c *ocv1.ClusterObjectDeployment) { + c.Labels = map[string]string{controllerManagedByLabel: "operator-controller"} + }}, + {name: "different invocation", change: func(c *ocv1.ClusterObjectDeployment) { c.Annotations[migrationInvocationAnnotation] = "other" }}, + {name: "controlled", change: func(c *ocv1.ClusterObjectDeployment) { + c.OwnerReferences = []metav1.OwnerReference{*metav1.NewControllerRef(&ocv1.ClusterExtension{ObjectMeta: metav1.ObjectMeta{Name: "foreign", UID: "foreign"}}, ocv1.GroupVersion.WithKind(ocv1.ClusterExtensionKind))} + }}, + {name: "conflict", patchError: apierrors.NewConflict(schema.GroupResource{Resource: "clusterobjectdeployments"}, "example", errors.New("changed"))}, + {name: "transport", patchError: errors.New("connection reset")}, + } { + t.Run(tc.name, func(t *testing.T) { + created := readyDeployment() + created.Annotations = map[string]string{migrationInvocationAnnotation: "invocation"} + created.Spec.Template.Spec.CollisionProtection = ocv1.CollisionProtectionNone + created.Spec.Template.Spec.Phases = []ocv1.ClusterObjectSetPhase{{Name: "deploy", CollisionProtection: ocv1.CollisionProtectionNone, Objects: []ocv1.ClusterObjectSetObject{{CollisionProtection: ocv1.CollisionProtectionNone}}}} + current := created.DeepCopy() + if tc.change != nil { + tc.change(current) + } + m := migrationTestClient(t, current) + patched := false + m.Client = interceptor.NewClient(m.Client.(client.WithWatch), interceptor.Funcs{Patch: func(ctx context.Context, c client.WithWatch, obj client.Object, patch client.Patch, opts ...client.PatchOption) error { + patched = true + cod := obj.(*ocv1.ClusterObjectDeployment) + data, err := patch.Data(obj) + if err != nil { + t.Fatal(err) + } + if !strings.Contains(string(data), "resourceVersion") { + t.Fatal("handoff patch lacks optimistic locking") + } + if cod.Labels[controllerManagedByLabel] != "operator-controller" || cod.Spec.Template.Spec.CollisionProtection != ocv1.CollisionProtectionPrevent || cod.Spec.Template.Spec.Phases[0].CollisionProtection != "" || cod.Spec.Template.Spec.Phases[0].Objects[0].CollisionProtection != "" { + t.Fatal("handoff patch must atomically enable protection and adoption without overrides") + } + if tc.patchError != nil { + return tc.patchError + } + return c.Patch(ctx, obj, patch, opts...) + }}) + err := m.protectDeploymentForAdoption(t.Context(), created) + wantError := tc.change != nil || tc.patchError != nil + if (err != nil) != wantError { + t.Fatalf("error=%v wantError=%v", err, wantError) + } + if tc.change != nil && patched { + t.Fatal("patched changed or unready COD") + } + if tc.patchError != nil && !errors.Is(err, tc.patchError) { + t.Fatalf("lost patch error: %v", err) + } + if wantError { + var preserved ocv1.ClusterObjectDeployment + if err := m.Client.Get(t.Context(), client.ObjectKey{Name: created.Name}, &preserved); err != nil { + t.Fatal(err) + } + if preserved.Spec.Template.Spec.CollisionProtection != ocv1.CollisionProtectionNone { + t.Fatal("failed handoff changed the stored template") + } + } + }) + } +} + +// TestProtectedCODFailurePreservesStaging refuses CE creation and OLMv0 recovery +// after an initial rollout timeout or an uncertain protection-patch outcome. +func TestProtectedCODFailurePreservesStaging(t *testing.T) { + for _, mode := range []string{"wait timeout", "patch rejected", "patch response lost"} { + t.Run(mode, func(t *testing.T) { + m := migrationTestClient(t, establishedClusterObjectDeploymentCRD()) + patchAttempted := false + m.Client = interceptor.NewClient(m.Client.(client.WithWatch), interceptor.Funcs{ + Create: func(ctx context.Context, c client.WithWatch, obj client.Object, opts ...client.CreateOption) error { + cod, ok := obj.(*ocv1.ClusterObjectDeployment) + if !ok { + t.Fatalf("unexpected creation during failed handoff: %T", obj) + } + if cod.Labels[controllerManagedByLabel] != "" { + t.Fatal("initial COD is adoptable") + } + ready := readyDeployment() + cod.UID, cod.Generation = ready.UID, ready.Generation + if mode != "wait timeout" { + cod.Status = ready.Status + } + return c.Create(ctx, obj, opts...) + }, + Patch: func(ctx context.Context, c client.WithWatch, obj client.Object, p client.Patch, opts ...client.PatchOption) error { + patchAttempted = true + if mode == "patch response lost" { + if err := c.Patch(ctx, obj, p, opts...); err != nil { + return err + } + } + return errors.New("handoff patch failed") + }, + }) + ctx, cancel := context.WithTimeout(t.Context(), 100*time.Millisecond) + defer cancel() + result, err := m.CreateMigrationResources(ctx, Options{SubscriptionName: "example", SubscriptionNamespace: "source"}, &MigrationInfo{}, &Backup{}) + if err == nil || !result.TargetMayBeActive { + t.Fatalf("result=%+v error=%v", result, err) + } + if mode == "wait timeout" && patchAttempted { + t.Fatal("enabled adoption before readiness") + } + var cod ocv1.ClusterObjectDeployment + if err := m.Client.Get(t.Context(), client.ObjectKey{Name: "example"}, &cod); err != nil { + t.Fatal(err) + } + if mode != "patch response lost" && cod.Labels[controllerManagedByLabel] != "" { + t.Fatal("failed handoff enabled adoption") + } + if mode == "patch response lost" && (cod.Spec.Template.Spec.CollisionProtection != ocv1.CollisionProtectionPrevent || cod.Labels[controllerManagedByLabel] != "operator-controller") { + t.Fatal("accepted patch did not atomically set protection and adoption") + } + }) + } +} + +// TestProtectedCODRetriesStatusConflict permits status-only races but rejects a +// concurrent template change when re-reading the deployment for the next attempt. +func TestProtectedCODRetriesStatusConflict(t *testing.T) { + for _, changed := range []bool{false, true} { + t.Run(fmt.Sprint("templateChanged=", changed), func(t *testing.T) { + created := readyDeployment() + created.Annotations = map[string]string{migrationInvocationAnnotation: "invocation"} + created.Spec.Template.Spec.CollisionProtection = ocv1.CollisionProtectionNone + m := migrationTestClient(t, created.DeepCopy()) + attempts := 0 + m.Client = interceptor.NewClient(m.Client.(client.WithWatch), interceptor.Funcs{Patch: func(ctx context.Context, c client.WithWatch, obj client.Object, p client.Patch, opts ...client.PatchOption) error { + attempts++ + if attempts == 1 { + var current ocv1.ClusterObjectDeployment + if err := c.Get(ctx, client.ObjectKeyFromObject(obj), ¤t); err != nil { + return err + } + if changed { + current.Generation++ + } else { + current.Annotations["status-writer"] = "updated" + } + if err := c.Update(ctx, ¤t); err != nil { + return err + } + return apierrors.NewConflict(schema.GroupResource{Resource: "clusterobjectdeployments"}, obj.GetName(), errors.New("concurrent update")) + } + return c.Patch(ctx, obj, p, opts...) + }}) + err := m.protectDeploymentForAdoption(t.Context(), created) + if changed { + if err == nil || attempts != 1 { + t.Fatalf("changed template accepted: attempts=%d err=%v", attempts, err) + } + } else if err != nil || attempts != 2 || created.Labels[controllerManagedByLabel] != "operator-controller" { + t.Fatalf("status conflict not retried: attempts=%d err=%v", attempts, err) + } + }) + } +} diff --git a/specs/20260821-migration-v0-to-v1/e2e.md b/specs/20260821-migration-v0-to-v1/e2e.md index 0147471..78b1583 100644 --- a/specs/20260821-migration-v0-to-v1/e2e.md +++ b/specs/20260821-migration-v0-to-v1/e2e.md @@ -30,11 +30,9 @@ COD migration requires the COD API/controller and the COD-backed CE applier merg operator-controller PR #3058. The library's pinned API dependency alone does not install that controller. Unit tests exercise creation, preflight, readiness and rollback ownership and invalid-template diagnostics. The existing handoff scenario -also checks COD identity preservation, CE ownership of the COD, and COD ownership of both -revisions when a COD-capable controller is installed. On 2026-10-29 those assertions -passed against operator-controller main `255a4026` in kind. A separate full CLI fixture -conversion and acknowledged rollback preserved the operator Deployment UID and its one -available replica, restored the Subscription, and removed the COD and both COS revisions. +also checks COD identity preservation, CE ownership of the COD, and COD ownership +of all revisions. Only the initial revision uses `None`; every subsequent revision +must use `Prevent`, including any intermediate revisions during handoff. The `migration/test-e2e-cod-rollback` target now automates those rollback assertions and collects CLI coverage. A separate CI job builds and installs operator-controller from pinned commit `dae9b613163a8fc5df36e3b9ad5a770a64c0048c`, then runs the handoff and @@ -217,8 +215,9 @@ their combined report. The Job intentionally does not upload diagnostics or cove The supersession check is deliberately separate from the conversion matrix. With the pinned experimental controller, migration creates revision 1 with collision protection `None`; -creating the ClusterExtension results in a controller-owned, catalog-derived revision 2 with -collision protection `Prevent`. The check requires both revisions to succeed. +the protected handoff and ClusterExtension creation produce newer revisions with +collision protection `Prevent`. The check requires initial migration and catalog +completion, preserves ownership assertions, and permits intermediate protected revisions. ## CI rollout @@ -392,3 +391,17 @@ Setup refuses existing OLM namespaces or APIs, including partial installations. The live namespace-deletion target uses Redis. The ecr-secret-operator bundle includes a custom-resource sample with `spec.aws_iam_secret`, which is absent from its CRD schema and can block OLMv1 preflight in a new namespace. Ecr-secret-operator remains in the live migration matrix; the focused Redis scenario preserves all source-namespace deletion and label-transfer assertions. Rollback persists verified resource identities and UIDs on the restored Subscription before deleting the CE backup. Remigration includes still-unowned retained resources (including catalog-generated RBAC) omitted from the OLMv0 inventory; missing resources are skipped, replacements and newly controlled resources are rejected, and normal collection is deduplicated. + +### Protected COD-only handoff + +Migration creates a COD with `None` and without its CE-adoption label, waits for +initial rollout completion and availability, then atomically enables `Prevent` +and CE adoption. It clears permissive phase/object overrides in the same guarded +patch before creating the CE. Failed or uncertain handoffs preserve staging resources. +The protection-only template update may create an intermediate protected revision. + +`make migration/test-e2e-cos-supersession` also runs +`TestCODProtectedRolloutCollision`, which verifies that a later COD rollout refuses +an unrelated existing object. Both cases collect package coverage and run in the +existing handoff CI jobs. Unit regressions cover readiness, identity changes, +patch conflicts, uncertain patch outcomes, and refusal to create a CE on failure. diff --git a/specs/20260821-migration-v0-to-v1/plan.md b/specs/20260821-migration-v0-to-v1/plan.md index cfee0ab..0ed8e67 100644 --- a/specs/20260821-migration-v0-to-v1/plan.md +++ b/specs/20260821-migration-v0-to-v1/plan.md @@ -306,3 +306,17 @@ Sources: [shared converter](https://github.com/operator-framework/library-olm/pu [typed construction](https://github.com/operator-framework/library-olm/pull/93#discussion_r4556794570). Rollback persists verified resource identities and UIDs on the restored Subscription before deleting the CE backup. Remigration includes still-unowned retained resources (including catalog-generated RBAC) omitted from the OLMv0 inventory; missing resources are skipped, replacements and newly controlled resources are rejected, and normal collection is deduplicated. + +### Protected COD-only handoff + +Migration creates a COD with `None` and without its CE-adoption label, waits for +initial rollout completion and availability, then atomically enables `Prevent` +and CE adoption. It clears permissive phase/object overrides in the same guarded +patch before creating the CE. Failed or uncertain handoffs preserve staging resources. +The protection-only template update may create an intermediate protected revision. + +`make migration/test-e2e-cos-supersession` also runs +`TestCODProtectedRolloutCollision`, which verifies that a later COD rollout refuses +an unrelated existing object. Both cases collect package coverage and run in the +existing handoff CI jobs. Unit regressions cover readiness, identity changes, +patch conflicts, uncertain patch outcomes, and refusal to create a CE on failure. diff --git a/specs/20260821-migration-v0-to-v1/requirements.md b/specs/20260821-migration-v0-to-v1/requirements.md index 6fa6602..c7d1618 100644 --- a/specs/20260821-migration-v0-to-v1/requirements.md +++ b/specs/20260821-migration-v0-to-v1/requirements.md @@ -152,10 +152,14 @@ The directory is created if it does not exist. Failure to list associated plans **R2.7 — Boxcutter phase 2.** Support one `ClusterObjectDeployment` (COD) per ClusterExtension, with controller-managed COS revisions. COD is the only migration path. Missing, deleting, unestablished, or unreadable COD CRDs block check, dry-run, and migration before OLMv0 resources change. COD migration requires an established COD CRD and operator-controller's COD-backed ClusterExtension applier (upstream PR #3058). -Create the deployment with collision protection `None`, wait for current-generation rollout -completion and availability, then create the CE to hand management to operator-controller. -Set `apps.kubernetes.io/managed-by: operator-controller` on the COD itself so -operator-controller retains its rollout data and can adopt it while ownerless. +Create the deployment with collision protection `None` and no CE-adoption label. +Wait for current-generation rollout completion and availability, then atomically +change protection to `Prevent` and add `apps.kubernetes.io/managed-by: operator-controller`. +Remove phase/object protection overrides in that same resource-version-guarded patch. +Recheck UID, generation, migration invocation, readiness, and absence of controller +ownership before patching. Only after a successful patch create the CE. Failures +preserve the potentially active COD and its Secrets and refuse automatic OLMv0 recovery. +Later rollouts must reject unrelated existing objects rather than blindly adopt them. Preserve the same COD UID through adoption; owner-kind and owner-name metadata alone do not authorize adoption. The adoption label is not required on the COS template or operator workload objects. diff --git a/specs/20260821-migration-v0-to-v1/validation.md b/specs/20260821-migration-v0-to-v1/validation.md index 0f8df95..4d78a6f 100644 --- a/specs/20260821-migration-v0-to-v1/validation.md +++ b/specs/20260821-migration-v0-to-v1/validation.md @@ -12,7 +12,7 @@ kind cluster with both OLMv0 and OLMv1 installed. ## V1. Per-command behavior - **V1.1** `check -n ` on a healthy AllNamespaces operator with an available catalog reports all checks green and exits 0; makes no cluster changes. -- **V1.2** `convert -n --dry-run` lists every resource that would be migrated (grouped by kind), including CRDs, and reports the COD with `CollisionProtection: None` on its template; makes no cluster changes. +- **V1.2** `convert -n --dry-run` lists every resource that would be migrated (grouped by kind), including CRDs, and reports the COD with an initial `CollisionProtection: None` template followed by `Prevent` before CE adoption; makes no cluster changes. - **V1.3** `convert -n ` results in a `ClusterExtension` reaching `Installed=True`; the `Subscription` and `CSV` are deleted; CRDs remain and are adopted by OLMv1. Migration always uses COD: the COD's current-generation rollout completes and becomes available before the CE is created; the CE then owns the same COD and its catalog revision uses `CollisionProtection: Prevent`. - **V1.4** `rollback --acknowledge-installed` starts CE orphan deletion with a rollback finalizer to stop new revisions, records verified ownership from in-flight replacement revisions before deleting them, waits for orphaned resources to lose COS controller references, removes their OLMv1 revision metadata, restores the `Subscription` from the backup annotation, then removes the CE finalizer. A matching Subscription from a prior attempt permits retry; a conflicting Subscription or failed restoration retains the CE backup. The operator returns to OLMv0 management (`AtLatestKnown`/`UpgradePending`), and a subsequent migration can adopt preserved resources. Without `--acknowledge-installed` on an `Installed=True` CE, rollback refuses and exits non-zero. Verify CE-to-COD and COD-to-COS ownership and stop the COD with orphan deletion before removing its COS revisions, preventing replacement revisions during rollback. Before deletion and during subsequent revision discovery, reject controlled COS revisions unless the controller's API version, kind, name, and UID match the CE or its verified COD. Require the current `spec.group` identity even for unowned staging or orphaned revisions; a name or owner label alone cannot authorize deletion. Preserve workloads and retain the CE backup if cleanup or restoration fails. @@ -21,9 +21,9 @@ kind cluster with both OLMv0 and OLMv1 installed. - **V1.7** `convert --all` stops on the first failure by default; with `--continue-on-error` it logs the failure and continues, exiting non-zero if any operator failed. - **V1.8** No command ever blocks on interactive input. An operator whose name collides with a verb (e.g. `check`) is migratable as a positional argument (`convert check -n `). - **V1.9** COD is mandatory. Missing, deleting, or unestablished COD CRDs fail readiness, dry-run, and migration without mutating cluster resources; no COS is created directly. Discovery errors and unmet prerequisites fail before deleting OLMv0 resources. Validate COD name/group constraints and reject an existing COD rather than overwriting it. CRD presence is the supported capability signal; controller-version detection is not required. Preflight regression cases cover deleting COS/COD CRDs, pruned inline manifests, nested pruning, missing Secret-reference fields, incorrect field types, and valid unknown-field preservation, without creating or deleting migration resources. -- **V1.10** The COD template preserves migration labels, annotations, packed Secret references, and `CollisionProtection: None`. Readiness requires completion and availability for the current generation; stale status cannot satisfy the wait. Invalid-specification and deadline failures report actionable errors. Once a COD may have reconciled, failure preserves migration resources and refuses automatic OLMv0 recovery. +- **V1.10** The COD template preserves migration labels, annotations, packed Secret references, and initially `CollisionProtection: None`. Readiness requires completion and availability for the current generation; stale status cannot satisfy the wait. Invalid-specification and deadline failures report actionable errors. Once a COD may have reconciled, failure preserves migration resources and refuses automatic OLMv0 recovery. The COD itself carries `apps.kubernetes.io/managed-by: operator-controller` - before CE creation and after adoption. It has no controller owner during + only after initial rollout readiness, atomically with `Prevent` and removal of phase/object overrides, before CE creation and after adoption. It has no controller owner during staging, then gains the CE controller reference while retaining its UID. The template continues to carry extension identity metadata without copying this COD-specific adoption label onto operator workloads. @@ -108,7 +108,7 @@ flag flips it to `Eligible`: - **V5.8** `rollback --acknowledge-installed` → Subscription restored, CE and COS revisions deleted, preserved Deployments released from OLMv1 ownership; a second `convert` creates new CE/COS UIDs, installs successfully, and adopts the same Deployment UIDs. Also verify the COD is deleted and no COS remains in its group, while the Deployment UID and availability are preserved. Fixture tests assert restored Subscription state; OLMv0 reconciliation requires the live environment. - **V5.9** Fresh cluster with operators in all four states → `check --all` → correct four-section output; `convert --all` warns on Conflicts and migrates only Eligible. -- **V5.10** On a COD-capable controller, fixture migration creates one COD named for the CE. Catalog handoff retains that COD's UID, establishes CE ownership of the COD and COD ownership of successive COS revisions in the same group, and retains the migration revision (`None`) alongside a new catalog revision (`Prevent`). Verify the migration COS retains its UID and both revisions retain their respective collision-protection settings. Run handoff and fixture conversion/rollback (V5.8) in the dedicated COD CI job, collecting coverage separately from the other fixture tests. +- **V5.10** On a COD-capable controller, fixture migration creates one COD named for the CE. Catalog handoff retains that COD's UID, establishes CE ownership of the COD and COD ownership of successive COS revisions in the same group, and retains the migration revision (`None`) alongside a new catalog revision (`Prevent`). Verify the migration COS retains its UID and all later revisions use Prevent while the initial revision retains None. Run handoff and fixture conversion/rollback (V5.8) in the dedicated COD CI job, collecting coverage separately from the other fixture tests. ## V6. Non-functional (Jira deployment considerations) @@ -158,3 +158,11 @@ flag flips it to `Eligible`: Readiness reporting includes lightweight COS and COD API availability checks; these are diagnostic, not a guarantee that a later write will succeed. Operator migration uses COD and requires the experimental COD API. Gather (including CLI dry-run) and migration validate the prepared revision with a strict server-side dry-run create before removing OLMv0 management. Validation and creation share the same revision and Secret-reference builders; dry-run does not persist revisions or packed Secrets. The API server validates schema, admission, and permissions, but does not run controller-level validation of referenced workloads. Rollback permits verified newer sibling handoffs while retaining resource-UID, owner, and management-label checks. Rollback persists verified resource identities and UIDs on the restored Subscription before deleting the CE backup. Remigration includes still-unowned retained resources (including catalog-generated RBAC) omitted from the OLMv0 inventory; missing resources are skipped, replacements and newly controlled resources are rejected, and normal collection is deduplicated. + +The protected COD handoff must reject stale identity, generation, readiness, ownership, +and concurrent updates. Patch rejection or an uncertain response must not create a CE +or restart OLMv0. A subsequent template containing an unrelated existing ConfigMap +must report `RevisionObjectCollision` without changing its UID, data, labels, or owners. +The protection transition may create an intermediate protected COS before the catalog +revision; tests must validate every later revision uses `Prevent` without assuming +that the catalog revision is always revision 2. diff --git a/test/e2e/migration/cod_collision_test.go b/test/e2e/migration/cod_collision_test.go new file mode 100644 index 0000000..cc832c9 --- /dev/null +++ b/test/e2e/migration/cod_collision_test.go @@ -0,0 +1,104 @@ +//go:build e2e + +package e2e + +import ( + "context" + "os" + "reflect" + "testing" + "time" + + corev1 "k8s.io/api/core/v1" + apimeta "k8s.io/apimachinery/pkg/api/meta" + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/apis/meta/v1/unstructured" + "k8s.io/apimachinery/pkg/util/wait" + "k8s.io/client-go/util/retry" + "sigs.k8s.io/controller-runtime/pkg/client" + + ocv1 "github.com/operator-framework/operator-controller/api/v1" + + "github.com/operator-framework/library-olm/migration/pkg/migration" +) + +// TestCODProtectedRolloutCollision proves only the initial migration objects can +// be adopted blindly; an additional object in a later template must collide. +func TestCODProtectedRolloutCollision(t *testing.T) { + if os.Getenv("E2E_COS_SUPERSESSION_TEST") != "true" { + t.Skip("requires the focused handoff suite") + } + m, c, _ := newMigrator(t) + ctx, cancel := context.WithTimeout(context.Background(), 3*time.Minute) + defer cancel() + ns := &corev1.Namespace{ObjectMeta: metav1.ObjectMeta{GenerateName: "migration-collision-"}} + if err := c.Create(ctx, ns); err != nil { + t.Fatal(err) + } + name := ns.Name + t.Cleanup(func() { + collectArtifacts(t, ns.Name) + run(t, "kubectl", "delete", "clusterobjectdeployment/"+name, "--ignore-not-found", "--wait=true", "--timeout=60s") + run(t, "kubectl", "delete", "clusterobjectset", "-l", migration.LabelOwnerName+"="+name, "--ignore-not-found", "--wait=true", "--timeout=60s") + run(t, "kubectl", "delete", "namespace/"+ns.Name, "--wait=false") + }) + original := &corev1.ConfigMap{ObjectMeta: metav1.ObjectMeta{Name: "migrated", Namespace: ns.Name}, Data: map[string]string{"value": "original"}} + foreign := &corev1.ConfigMap{ObjectMeta: metav1.ObjectMeta{Name: "foreign", Namespace: ns.Name}, Data: map[string]string{"value": "do-not-change"}} + for _, obj := range []client.Object{original, foreign} { + if err := c.Create(ctx, obj); err != nil { + t.Fatal(err) + } + } + manifest := func(name, value string) unstructured.Unstructured { + return unstructured.Unstructured{Object: map[string]interface{}{"apiVersion": "v1", "kind": "ConfigMap", "metadata": map[string]interface{}{"name": name, "namespace": ns.Name}, "data": map[string]interface{}{"value": value}}} + } + opts, err := m.PrepareClusterObjectSet(ctx, migration.Options{SubscriptionName: name, SubscriptionNamespace: ns.Name}) + if err != nil { + t.Fatal(err) + } + if err := m.CreateClusterObjectSet(ctx, opts, &migration.MigrationInfo{CollectedObjects: []unstructured.Unstructured{manifest(original.Name, "original")}}); err != nil { + t.Fatal(err) + } + var cod ocv1.ClusterObjectDeployment + if err := c.Get(ctx, client.ObjectKey{Name: name}, &cod); err != nil { + t.Fatal(err) + } + if cod.Spec.Template.Spec.CollisionProtection != ocv1.CollisionProtectionPrevent { + t.Fatal("COD is not protected") + } + var adopted corev1.ConfigMap + if err := c.Get(ctx, client.ObjectKeyFromObject(original), &adopted); err != nil { + t.Fatal(err) + } + if adopted.UID != original.UID || metav1.GetControllerOf(&adopted) == nil { + t.Fatal("initial object was not adopted in place") + } + if err := retry.RetryOnConflict(retry.DefaultRetry, func() error { + if err := c.Get(ctx, client.ObjectKey{Name: name}, &cod); err != nil { + return err + } + before := cod.DeepCopy() + cod.Spec.Template.Spec.Phases[0].Objects = append(cod.Spec.Template.Spec.Phases[0].Objects, ocv1.ClusterObjectSetObject{Type: ocv1.ObjectTypeInlineManifest, InlineManifest: manifest(foreign.Name, "must-not-be-applied")}) + return c.Patch(ctx, &cod, client.MergeFromWithOptions(before, client.MergeFromWithOptimisticLock{})) + }); err != nil { + t.Fatal(err) + } + + if err := wait.PollUntilContextCancel(ctx, time.Second, true, func(ctx context.Context) (bool, error) { + var current ocv1.ClusterObjectDeployment + if err := c.Get(ctx, client.ObjectKey{Name: name}, ¤t); err != nil { + return false, err + } + condition := apimeta.FindStatusCondition(current.Status.Conditions, ocv1.ClusterObjectDeploymentTypeProgressing) + return condition != nil && condition.ObservedGeneration == current.Generation && condition.Status == metav1.ConditionFalse && condition.Reason == ocv1.ClusterObjectDeploymentReasonRevisionObjectCollision, nil + }); err != nil { + t.Fatalf("expected collision on newly introduced object: %v", err) + } + var preserved corev1.ConfigMap + if err := c.Get(ctx, client.ObjectKeyFromObject(foreign), &preserved); err != nil { + t.Fatal(err) + } + if preserved.UID != foreign.UID || !reflect.DeepEqual(preserved.Data, foreign.Data) || !reflect.DeepEqual(preserved.OwnerReferences, foreign.OwnerReferences) || !reflect.DeepEqual(preserved.Labels, foreign.Labels) { + t.Fatalf("foreign object was modified: %+v", preserved) + } +} diff --git a/test/e2e/migration/e2e_test.go b/test/e2e/migration/e2e_test.go index abfc413..e195a98 100644 --- a/test/e2e/migration/e2e_test.go +++ b/test/e2e/migration/e2e_test.go @@ -4,12 +4,14 @@ package e2e import ( "bytes" + "cmp" "context" "encoding/json" "fmt" "os" "os/exec" "path/filepath" + "slices" "strings" "testing" @@ -329,9 +331,10 @@ func TestPrecreatedClusterObjectSetSupersession(t *testing.T) { }); err != nil { t.Fatalf("list pre-existing COS: %v", err) } - if len(before.Items) != 1 { - t.Fatalf("pre-existing COS count = %d, want 1", len(before.Items)) + if len(before.Items) < 1 || len(before.Items) > 2 { + t.Fatalf("pre-existing COS count = %d, want initial revision and optional protected revision", len(before.Items)) } + slices.SortFunc(before.Items, func(a, b ocv1.ClusterObjectSet) int { return cmp.Compare(a.Spec.Revision, b.Spec.Revision) }) precreatedUID := before.Items[0].UID var originalCOD ocv1.ClusterObjectDeployment if err := kubeClient.Get(ctx, client.ObjectKey{Name: subscription}, &originalCOD); err != nil { @@ -340,6 +343,9 @@ func TestPrecreatedClusterObjectSetSupersession(t *testing.T) { if !metav1.IsControlledBy(&before.Items[0], &originalCOD) || before.Items[0].Spec.Group != subscription { t.Fatal("migration revision is not controlled by its COD") } + if originalCOD.Spec.Template.Spec.CollisionProtection != ocv1.CollisionProtectionPrevent { + t.Fatal("adoptable COD must already enforce Prevent") + } if originalCOD.Labels["apps.kubernetes.io/managed-by"] != "operator-controller" || metav1.GetControllerOf(&originalCOD) != nil { t.Fatal("staging COD must be ownerless and carry the operator-controller adoption label") } @@ -367,21 +373,38 @@ func TestPrecreatedClusterObjectSetSupersession(t *testing.T) { }); err != nil { t.Fatalf("list COS after CE creation: %v", err) } - if len(after.Items) != 2 { - t.Fatalf("COS count after CE creation = %d, want 2 (migration and catalog revisions)", len(after.Items)) + if len(after.Items) < 2 { + t.Fatalf("COS count after CE creation = %d, want initial and catalog revisions", len(after.Items)) } var migrationCOS, catalogCOS *ocv1.ClusterObjectSet for i := range after.Items { cos := &after.Items[i] - switch cos.Spec.Revision { - case 1: + if cos.Spec.Revision == 1 { migrationCOS = cos - case 2: + continue + } + if cos.Spec.CollisionProtection != ocv1.CollisionProtectionPrevent { + t.Fatalf("revision %s bypasses collision protection", cos.Name) + } + if !metav1.IsControlledBy(cos, &originalCOD) || cos.Spec.Group != subscription { + t.Fatalf("revision %s has unexpected ownership", cos.Name) + } + for _, phase := range cos.Spec.Phases { + if phase.CollisionProtection != "" && phase.CollisionProtection != ocv1.CollisionProtectionPrevent { + t.Fatalf("revision %s has permissive phase override", cos.Name) + } + for _, obj := range phase.Objects { + if obj.CollisionProtection != "" && obj.CollisionProtection != ocv1.CollisionProtectionPrevent { + t.Fatalf("revision %s has permissive object override", cos.Name) + } + } + } + if catalogCOS == nil || cos.Spec.Revision > catalogCOS.Spec.Revision { catalogCOS = cos } } if migrationCOS == nil || catalogCOS == nil { - t.Fatalf("COS revisions = %#v, want migration revision 1 and catalog revision 2", after.Items) + t.Fatalf("COS revisions = %#v, want migration revision 1 and a newer catalog revision", after.Items) } if migrationCOS.UID != precreatedUID { t.Fatalf("migration COS UID = %s, want pre-created UID %s", migrationCOS.UID, precreatedUID) From 3e45eed11bade18bf6db7db1158d41ec809eba3c Mon Sep 17 00:00:00 2001 From: Todd Short Date: Wed, 11 Nov 2026 16:37:31 -0500 Subject: [PATCH 05/10] fix: retain recovery backups before CE handoff Persist original Subscription and OperatorGroup specs on the COD at creation, propagate them to revisions, and derive backup annotations from the supplied Backup for direct API callers. Preserve caller data and prove a fresh caller can restore the saved Subscription spec after safe target release. Document export and explicit pre-CE recovery without automatically restarting OLMv0. Signed-off-by: Todd Short --- migration/pkg/migration/deployment.go | 1 + migration/pkg/migration/labels.go | 4 +- migration/pkg/migration/migration.go | 5 ++ migration/pkg/migration/staging_backup.go | 44 ++++++++++ .../pkg/migration/staging_backup_test.go | 83 +++++++++++++++++++ specs/20260821-migration-v0-to-v1/e2e.md | 32 +++++++ specs/20260821-migration-v0-to-v1/plan.md | 7 ++ .../requirements.md | 7 ++ .../20260821-migration-v0-to-v1/validation.md | 7 ++ 9 files changed, 188 insertions(+), 2 deletions(-) create mode 100644 migration/pkg/migration/staging_backup.go create mode 100644 migration/pkg/migration/staging_backup_test.go diff --git a/migration/pkg/migration/deployment.go b/migration/pkg/migration/deployment.go index 41d3c47..fca6467 100644 --- a/migration/pkg/migration/deployment.go +++ b/migration/pkg/migration/deployment.go @@ -326,6 +326,7 @@ func buildClusterObjectDeployment(opts Options, info *MigrationInfo, phases []*o LabelBundleName: info.BundleName, LabelBundleVersion: info.Version, } + addStagingBackup(annotations, info) if info.BundleImage != "" { annotations[LabelBundleReference] = info.BundleImage } diff --git a/migration/pkg/migration/labels.go b/migration/pkg/migration/labels.go index 0b0d896..fa5bdde 100644 --- a/migration/pkg/migration/labels.go +++ b/migration/pkg/migration/labels.go @@ -34,10 +34,10 @@ const ( // Value is "/" of the source Subscription. MigratedFromSubscriptionAnnotation = "olm.operatorframework.io/migrated-from-subscription" - // MigrationSubscriptionBackupAnnotation holds JSON-encoded Subscription spec on the CE (R2.5). + // MigrationSubscriptionBackupAnnotation holds JSON-encoded Subscription spec on retained staging resources and the CE (R2.5). MigrationSubscriptionBackupAnnotation = "olm.operatorframework.io/migration-subscription-backup" - // MigrationOperatorGroupBackupAnnotation holds JSON-encoded OperatorGroup spec on the CE (R2.5). + // MigrationOperatorGroupBackupAnnotation holds JSON-encoded OperatorGroup spec on retained staging resources and the CE (R2.5). MigrationOperatorGroupBackupAnnotation = "olm.operatorframework.io/migration-operatorgroup-backup" // AnnotationAcknowledgedPrefix is the prefix for per-flag audit annotations on the CE (R2.5). diff --git a/migration/pkg/migration/migration.go b/migration/pkg/migration/migration.go index 377a247..39b603e 100644 --- a/migration/pkg/migration/migration.go +++ b/migration/pkg/migration/migration.go @@ -619,6 +619,11 @@ func (m *Migrator) CreateClusterObjectSet(ctx context.Context, opts Options, inf // as one recoverable operation. Its result reports whether a target COD may have // started reconciling, including when cleanup was requested after a failure. func (m *Migrator) CreateMigrationResources(ctx context.Context, opts Options, info *MigrationInfo, backup *Backup) (MigrationResourcesResult, error) { + var err error + info, err = withStagingBackup(info, backup) + if err != nil { + return MigrationResourcesResult{}, err + } opts.ApplyDefaults() resources, err := m.createMigrationDeployment(ctx, opts, info) if err != nil { diff --git a/migration/pkg/migration/staging_backup.go b/migration/pkg/migration/staging_backup.go new file mode 100644 index 0000000..5b7c197 --- /dev/null +++ b/migration/pkg/migration/staging_backup.go @@ -0,0 +1,44 @@ +package migration + +import ( + "encoding/json" + "fmt" +) + +// withStagingBackup copies recovery specs into the migration plan before any +// target is created. The caller's plan and backup remain unchanged. +func withStagingBackup(info *MigrationInfo, backup *Backup) (*MigrationInfo, error) { + if info == nil { + return nil, fmt.Errorf("migration information is required") + } + copy := *info + if backup == nil { + return ©, nil + } + if backup.Subscription != nil { + data, err := json.Marshal(backup.Subscription.Spec) + if err != nil { + return nil, fmt.Errorf("encode Subscription recovery backup: %w", err) + } + copy.SubscriptionBackupJSON = string(data) + } + if backup.OperatorGroup != nil { + data, err := json.Marshal(backup.OperatorGroup.Spec) + if err != nil { + return nil, fmt.Errorf("encode OperatorGroup recovery backup: %w", err) + } + copy.OperatorGroupBackupJSON = string(data) + } + return ©, nil +} + +// addStagingBackup persists the same recovery specs used by CE rollback on the +// retained staging resource, so a failure before CE creation cannot lose them. +func addStagingBackup(annotations map[string]string, info *MigrationInfo) { + if info.SubscriptionBackupJSON != "" { + annotations[MigrationSubscriptionBackupAnnotation] = info.SubscriptionBackupJSON + } + if info.OperatorGroupBackupJSON != "" { + annotations[MigrationOperatorGroupBackupAnnotation] = info.OperatorGroupBackupJSON + } +} diff --git a/migration/pkg/migration/staging_backup_test.go b/migration/pkg/migration/staging_backup_test.go new file mode 100644 index 0000000..e5de335 --- /dev/null +++ b/migration/pkg/migration/staging_backup_test.go @@ -0,0 +1,83 @@ +package migration + +import ( + "context" + "encoding/json" + "reflect" + "testing" + "time" + + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "sigs.k8s.io/controller-runtime/pkg/client" + + operatorsv1 "github.com/operator-framework/api/pkg/operators/v1" + operatorsv1alpha1 "github.com/operator-framework/api/pkg/operators/v1alpha1" + ocv1 "github.com/operator-framework/operator-controller/api/v1" +) + +// TestStagingBackupSurvivesFailedHandoff proves that recovery data remains on +// the server after the original caller and its in-memory backup are discarded. +func TestStagingBackupSurvivesFailedHandoff(t *testing.T) { + sub, _ := healthySubscriptionFixtures() + sub.Spec.Channel = "original-channel" + sub.Spec.InstallPlanApproval = operatorsv1alpha1.ApprovalManual + og := &operatorsv1.OperatorGroup{Spec: operatorsv1.OperatorGroupSpec{TargetNamespaces: []string{"watched"}}} + m := migrationTestClient(t, establishedClusterObjectDeploymentCRD()) + info := &MigrationInfo{} + opts := Options{SubscriptionName: sub.Name, SubscriptionNamespace: sub.Namespace, ClusterExtensionName: "staged"} + ctx, cancel := context.WithTimeout(t.Context(), 50*time.Millisecond) + defer cancel() + result, err := m.CreateMigrationResources(ctx, opts, info, &Backup{Subscription: sub, OperatorGroup: og}) + if err == nil || !result.TargetMayBeActive { + t.Fatalf("expected retained staging resources: %+v %v", result, err) + } + if info.SubscriptionBackupJSON != "" || info.OperatorGroupBackupJSON != "" { + t.Fatal("modified caller's plan") + } + var cod ocv1.ClusterObjectDeployment + if err := m.Client.Get(t.Context(), client.ObjectKey{Name: "staged"}, &cod); err != nil { + t.Fatal(err) + } + var spec operatorsv1alpha1.SubscriptionSpec + if err := json.Unmarshal([]byte(cod.Annotations[MigrationSubscriptionBackupAnnotation]), &spec); err != nil { + t.Fatal(err) + } + if !reflect.DeepEqual(&spec, sub.Spec) { + t.Fatalf("lost original Subscription spec: %+v", spec) + } + var ogSpec operatorsv1.OperatorGroupSpec + if err := json.Unmarshal([]byte(cod.Annotations[MigrationOperatorGroupBackupAnnotation]), &ogSpec); err != nil { + t.Fatal(err) + } + if !reflect.DeepEqual(ogSpec, og.Spec) { + t.Fatal("lost OperatorGroup spec") + } + var extensions ocv1.ClusterExtensionList + if err := m.Client.List(t.Context(), &extensions); err != nil { + t.Fatal(err) + } + if len(extensions.Items) != 0 { + t.Fatal("created CE after failed rollout") + } + // This fake has no object controller or workloads. Remove the target before + // exercising explicit recovery using only the persisted Subscription spec. + if err := m.Client.Delete(t.Context(), &cod); err != nil { + t.Fatal(err) + } + ns, name, err := splitSubRef(cod.Annotations[MigratedFromSubscriptionAnnotation]) + if err != nil { + t.Fatal(err) + } + fresh := &Migrator{Client: reconcilingSubscriptionClient{Client: m.Client}} + recovered := &operatorsv1alpha1.Subscription{ObjectMeta: metav1.ObjectMeta{Name: name, Namespace: ns}, Spec: &spec} + if err := fresh.RecoverFromBackup(t.Context(), opts, &Backup{Subscription: recovered}); err != nil { + t.Fatal(err) + } + var actual operatorsv1alpha1.Subscription + if err := m.Client.Get(t.Context(), client.ObjectKeyFromObject(sub), &actual); err != nil { + t.Fatal(err) + } + if !reflect.DeepEqual(actual.Spec, sub.Spec) { + t.Fatal("persisted backup did not restore original spec") + } +} diff --git a/specs/20260821-migration-v0-to-v1/e2e.md b/specs/20260821-migration-v0-to-v1/e2e.md index 78b1583..056bb7c 100644 --- a/specs/20260821-migration-v0-to-v1/e2e.md +++ b/specs/20260821-migration-v0-to-v1/e2e.md @@ -405,3 +405,35 @@ The protection-only template update may create an intermediate protected revisio an unrelated existing object. Both cases collect package coverage and run in the existing handoff CI jobs. Unit regressions cover readiness, identity changes, patch conflicts, uncertain patch outcomes, and refusal to create a CE on failure. + +### Recovering a handoff that stopped before CE creation + +Migration stores the original Subscription and OperatorGroup specs on its retained +staging resource using the same backup annotations as the CE. These annotations +are written with resource creation, before any rollout wait or handoff can fail, +and are propagated to COD-generated revisions. This does not depend on `--backup`. + +Export the retained COD before removing any staging resources. If COD creation +failed after a directly staged COS, export that COS instead: + +```bash +kubectl get clusterobjectdeployment "$ce_name" -o json > staging.json +# Alternative when only the initial COS exists: +# kubectl get clusterobjectset "${ce_name}-1" -o json > staging.json +jq -e ' + .metadata.annotations as $a | + ($a["olm.operatorframework.io/migrated-from-subscription"] | split("/")) as $source | + {apiVersion: "operators.coreos.com/v1alpha1", kind: "Subscription", + metadata: {namespace: $source[0], name: $source[1]}, + spec: ($a["olm.operatorframework.io/migration-subscription-backup"] | fromjson)} +' staging.json > subscription-recovery.json +jq -e '.metadata.annotations["olm.operatorframework.io/migration-operatorgroup-backup"] | fromjson' staging.json > operatorgroup-spec-recovery.json +``` + +Exporting does not restore OLMv0. Before restoring the Subscription, stop the target +controllers, release their workload ownership, and verify the source namespace and +OperatorGroup are usable; otherwise OLMv0 and OLMv1 could reconcile concurrently. +The ordinary rollback CLI requires a CE and does not automate this pre-CE recovery. +Library callers can decode the saved spec into `Backup.Subscription` and use +`RecoverFromBackup` after safely releasing the target. Keep the exported files until +recovery has succeeded. diff --git a/specs/20260821-migration-v0-to-v1/plan.md b/specs/20260821-migration-v0-to-v1/plan.md index 0ed8e67..9e9403e 100644 --- a/specs/20260821-migration-v0-to-v1/plan.md +++ b/specs/20260821-migration-v0-to-v1/plan.md @@ -320,3 +320,10 @@ The protection-only template update may create an intermediate protected revisio an unrelated existing object. Both cases collect package coverage and run in the existing handoff CI jobs. Unit regressions cover readiness, identity changes, patch conflicts, uncertain patch outcomes, and refusal to create a CE on failure. + +Recovery before CE creation must not rely only on an in-memory backup. Persist the +original Subscription and OperatorGroup specs on retained staging resources at +creation, before rollout/handoff failures can strand the operator. Preserve them +on failed or uncertain handoffs and refuse automatic OLMv0 restart. Regression +tests must decode the server-side backup after discarding the original plan and +verify it can restore the original Subscription spec after safe target release. diff --git a/specs/20260821-migration-v0-to-v1/requirements.md b/specs/20260821-migration-v0-to-v1/requirements.md index c7d1618..91a3f69 100644 --- a/specs/20260821-migration-v0-to-v1/requirements.md +++ b/specs/20260821-migration-v0-to-v1/requirements.md @@ -383,3 +383,10 @@ unreferenced source would be deleted without changing it. Readiness reporting includes lightweight COS and COD API availability checks; these are diagnostic, not a guarantee that a later write will succeed. Operator migration uses COD and requires the experimental COD API. Gather (including CLI dry-run) and migration validate the prepared revision with a strict server-side dry-run create before removing OLMv0 management. Validation and creation share the same revision and Secret-reference builders; dry-run does not persist revisions or packed Secrets. The API server validates schema, admission, and permissions, but does not run controller-level validation of referenced workloads. Rollback permits verified newer sibling handoffs while retaining resource-UID, owner, and management-label checks. Rollback persists verified resource identities and UIDs on the restored Subscription before deleting the CE backup. Remigration includes still-unowned retained resources (including catalog-generated RBAC) omitted from the OLMv0 inventory; missing resources are skipped, replacements and newly controlled resources are rejected, and normal collection is deduplicated. + +Recovery before CE creation must not rely only on an in-memory backup. Persist the +original Subscription and OperatorGroup specs on retained staging resources at +creation, before rollout/handoff failures can strand the operator. Preserve them +on failed or uncertain handoffs and refuse automatic OLMv0 restart. Regression +tests must decode the server-side backup after discarding the original plan and +verify it can restore the original Subscription spec after safe target release. diff --git a/specs/20260821-migration-v0-to-v1/validation.md b/specs/20260821-migration-v0-to-v1/validation.md index 4d78a6f..153223d 100644 --- a/specs/20260821-migration-v0-to-v1/validation.md +++ b/specs/20260821-migration-v0-to-v1/validation.md @@ -166,3 +166,10 @@ must report `RevisionObjectCollision` without changing its UID, data, labels, or The protection transition may create an intermediate protected COS before the catalog revision; tests must validate every later revision uses `Prevent` without assuming that the catalog revision is always revision 2. + +Recovery before CE creation must not rely only on an in-memory backup. Persist the +original Subscription and OperatorGroup specs on retained staging resources at +creation, before rollout/handoff failures can strand the operator. Preserve them +on failed or uncertain handoffs and refuse automatic OLMv0 restart. Regression +tests must decode the server-side backup after discarding the original plan and +verify it can restore the original Subscription spec after safe target release. From afeba72c76c2ba053187c88586f2b3f4a87fd033 Mon Sep 17 00:00:00 2001 From: Todd Short Date: Wed, 11 Nov 2026 17:14:29 -0500 Subject: [PATCH 06/10] test: clean up packed Secrets after collision checks Delete packed migration Secrets from the discovered controller namespace after COD and COS teardown. Retry optimistic COD updates when controller reconciliation changes resource versions. Signed-off-by: Todd Short --- test/e2e/migration/cod_collision_test.go | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/test/e2e/migration/cod_collision_test.go b/test/e2e/migration/cod_collision_test.go index cc832c9..565dfdd 100644 --- a/test/e2e/migration/cod_collision_test.go +++ b/test/e2e/migration/cod_collision_test.go @@ -36,10 +36,14 @@ func TestCODProtectedRolloutCollision(t *testing.T) { t.Fatal(err) } name := ns.Name + systemNamespace := "" t.Cleanup(func() { collectArtifacts(t, ns.Name) run(t, "kubectl", "delete", "clusterobjectdeployment/"+name, "--ignore-not-found", "--wait=true", "--timeout=60s") run(t, "kubectl", "delete", "clusterobjectset", "-l", migration.LabelOwnerName+"="+name, "--ignore-not-found", "--wait=true", "--timeout=60s") + if systemNamespace != "" { + run(t, "kubectl", "delete", "secret", "-n", systemNamespace, "-l", migration.LabelOwnerName+"="+name, "--ignore-not-found", "--wait=true", "--timeout=60s") + } run(t, "kubectl", "delete", "namespace/"+ns.Name, "--wait=false") }) original := &corev1.ConfigMap{ObjectMeta: metav1.ObjectMeta{Name: "migrated", Namespace: ns.Name}, Data: map[string]string{"value": "original"}} @@ -56,6 +60,7 @@ func TestCODProtectedRolloutCollision(t *testing.T) { if err != nil { t.Fatal(err) } + systemNamespace = opts.SystemNamespace if err := m.CreateClusterObjectSet(ctx, opts, &migration.MigrationInfo{CollectedObjects: []unstructured.Unstructured{manifest(original.Name, "original")}}); err != nil { t.Fatal(err) } From 7772d63075bceda854fd722839a33576eea5ff81 Mon Sep 17 00:00:00 2001 From: Todd Short Date: Thu, 12 Nov 2026 09:54:29 -0500 Subject: [PATCH 07/10] fix: allow bounded collision retries during revision handoff Wait for actual COD completion instead of treating a transient ownership collision as terminal. Preserve deadline identity and the controller diagnostic when a collision persists. Verify system-managed namespace ownership by revision UID and CE ownership chain instead of assuming revision 2. Signed-off-by: Todd Short --- migration/pkg/migration/deployment.go | 17 ++++++++- migration/pkg/migration/deployment_test.go | 38 ++++++++++++++++++- specs/20260821-migration-v0-to-v1/e2e.md | 2 + specs/20260821-migration-v0-to-v1/plan.md | 2 + .../requirements.md | 4 +- .../20260821-migration-v0-to-v1/validation.md | 4 +- test/e2e/migration/e2e_test.go | 32 +++++++++++----- 7 files changed, 85 insertions(+), 14 deletions(-) diff --git a/migration/pkg/migration/deployment.go b/migration/pkg/migration/deployment.go index fca6467..e8d7456 100644 --- a/migration/pkg/migration/deployment.go +++ b/migration/pkg/migration/deployment.go @@ -3,6 +3,7 @@ package migration import ( "context" "encoding/json" + "errors" "fmt" "regexp" "slices" @@ -138,7 +139,8 @@ func (m *Migrator) protectDeploymentForAdoption(ctx context.Context, created *oc // waitForDeployment waits for the created deployment to complete its current rollout and become available. func (m *Migrator) waitForDeployment(ctx context.Context, created *ocv1.ClusterObjectDeployment) error { - return wait.PollUntilContextTimeout(ctx, cosWaitPollInterval, cosWaitTimeout, true, func(ctx context.Context) (bool, error) { + var collision error + err := wait.PollUntilContextTimeout(ctx, cosWaitPollInterval, cosWaitTimeout, true, func(ctx context.Context) (bool, error) { var cod ocv1.ClusterObjectDeployment if err := m.Client.Get(ctx, client.ObjectKeyFromObject(created), &cod); err != nil { return false, err @@ -146,11 +148,18 @@ func (m *Migrator) waitForDeployment(ctx context.Context, created *ocv1.ClusterO if cod.UID != created.UID || cod.Generation != created.Generation || cod.DeletionTimestamp != nil { return false, fmt.Errorf("migration ClusterObjectDeployment %s was replaced, changed or deleted", cod.Name) } + collision = nil progress := apimeta.FindStatusCondition(cod.Status.Conditions, ocv1.ClusterObjectDeploymentTypeProgressing) available := apimeta.FindStatusCondition(cod.Status.Conditions, ocv1.ClusterObjectDeploymentTypeAvailable) if progress != nil && progress.ObservedGeneration == cod.Generation { if progress.Status == metav1.ConditionFalse && progress.Reason != ocv1.ClusterObjectDeploymentReasonNewClusterObjectSetProgressed { - return false, fmt.Errorf("ClusterObjectDeployment %s rollout failed (%s): %s", cod.Name, progress.Reason, progress.Message) + failure := fmt.Errorf("ClusterObjectDeployment %s rollout failed (%s): %s", cod.Name, progress.Reason, progress.Message) + if progress.Reason != ocv1.ClusterObjectDeploymentReasonRevisionObjectCollision { + return false, failure + } + // Ownership can briefly collide while sibling revisions hand off. + // Continue observing; only actual completion permits migration. + collision = failure } if progress.Status == metav1.ConditionFalse && progress.Reason == ocv1.ClusterObjectDeploymentReasonNewClusterObjectSetProgressed && available != nil && available.ObservedGeneration == cod.Generation && available.Status == metav1.ConditionTrue { @@ -160,6 +169,10 @@ func (m *Migrator) waitForDeployment(ctx context.Context, created *ocv1.ClusterO m.progress(ProgressEvent{Step: ProgressStepCreate, Status: ProgressWaiting, Message: fmt.Sprintf("Waiting for ClusterObjectDeployment %s rollout completion and availability", cod.Name)}) return false, nil }) + if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) { + return errors.Join(err, collision) + } + return err } // rollbackDeployment permits the COD API to be absent, but never hides diff --git a/migration/pkg/migration/deployment_test.go b/migration/pkg/migration/deployment_test.go index da5da80..3833166 100644 --- a/migration/pkg/migration/deployment_test.go +++ b/migration/pkg/migration/deployment_test.go @@ -128,7 +128,6 @@ func TestDeploymentInvalidSpecification(t *testing.T) { func TestDeploymentTerminalRevisionFailures(t *testing.T) { for _, reason := range []string{ - ocv1.ClusterObjectDeploymentReasonRevisionObjectCollision, ocv1.ClusterObjectDeploymentReasonRevisionInvalidSpecification, ocv1.ClusterObjectDeploymentReasonUnmanagedRevision, "FutureTerminalReason", @@ -750,3 +749,40 @@ func TestProtectedCODRetriesStatusConflict(t *testing.T) { }) } } + +func TestDeploymentCollisionWait(t *testing.T) { + for _, resolves := range []bool{false, true} { + t.Run(fmt.Sprint("resolves=", resolves), func(t *testing.T) { + created := readyDeployment() + current := created.DeepCopy() + current.Status.Conditions[0].Reason = ocv1.ClusterObjectDeploymentReasonRevisionObjectCollision + current.Status.Conditions[0].Message = "existing object is still owned" + m := migrationTestClient(t, current) + reads := 0 + m.Client = interceptor.NewClient(m.Client.(client.WithWatch), interceptor.Funcs{Get: func(ctx context.Context, c client.WithWatch, key client.ObjectKey, obj client.Object, opts ...client.GetOption) error { + if err := c.Get(ctx, key, obj, opts...); err != nil { + return err + } + reads++ + if resolves && reads > 1 { + obj.(*ocv1.ClusterObjectDeployment).Status = created.Status + } + return nil + }}) + timeout := 50 * time.Millisecond + if resolves { + timeout = 2 * cosWaitPollInterval + } + ctx, cancel := context.WithTimeout(t.Context(), timeout) + defer cancel() + err := m.waitForDeployment(ctx, created) + if resolves { + if err != nil || reads < 2 { + t.Fatalf("transient collision did not resolve: %v", err) + } + } else if !errors.Is(err, context.DeadlineExceeded) || !strings.Contains(err.Error(), "existing object is still owned") { + t.Fatalf("persistent collision lost deadline or diagnostic: %v", err) + } + }) + } +} diff --git a/specs/20260821-migration-v0-to-v1/e2e.md b/specs/20260821-migration-v0-to-v1/e2e.md index 056bb7c..1672c81 100644 --- a/specs/20260821-migration-v0-to-v1/e2e.md +++ b/specs/20260821-migration-v0-to-v1/e2e.md @@ -437,3 +437,5 @@ The ordinary rollback CLI requires a CE and does not automate this pre-CE recove Library callers can decode the saved spec into `Backup.Subscription` and use `RecoverFromBackup` after safely releasing the target. Keep the exported files until recovery has succeeded. + +Revision collision observations during COD handoff are retried within the existing rollout timeout. Only current-generation completion and availability allow migration to continue; persistent collisions fail with the controller diagnostic and preserve staged recovery resources. diff --git a/specs/20260821-migration-v0-to-v1/plan.md b/specs/20260821-migration-v0-to-v1/plan.md index 9e9403e..7fcfa1c 100644 --- a/specs/20260821-migration-v0-to-v1/plan.md +++ b/specs/20260821-migration-v0-to-v1/plan.md @@ -327,3 +327,5 @@ creation, before rollout/handoff failures can strand the operator. Preserve them on failed or uncertain handoffs and refuse automatic OLMv0 restart. Regression tests must decode the server-side backup after discarding the original plan and verify it can restore the original Subscription spec after safe target release. + +Revision collision observations during COD handoff are retried within the existing rollout timeout. Only current-generation completion and availability allow migration to continue; persistent collisions fail with the controller diagnostic and preserve staged recovery resources. diff --git a/specs/20260821-migration-v0-to-v1/requirements.md b/specs/20260821-migration-v0-to-v1/requirements.md index 91a3f69..1cb848b 100644 --- a/specs/20260821-migration-v0-to-v1/requirements.md +++ b/specs/20260821-migration-v0-to-v1/requirements.md @@ -180,7 +180,7 @@ Reject unverified controller identities. Definitively rejected COS/COD creates ambiguous creation outcomes continue to require explicit recovery. Carry bundle and migration annotations and extension identity labels through `spec.template.metadata` onto generated COS revisions. Report current-generation -terminal `Progressing=False` conditions other than successful rollout completion immediately, preserving the +terminal `Progressing=False` conditions other than successful rollout completion or retryable revision collisions immediately, preserving the controller's diagnostic message; ignore stale-generation failure conditions. --- @@ -390,3 +390,5 @@ creation, before rollout/handoff failures can strand the operator. Preserve them on failed or uncertain handoffs and refuse automatic OLMv0 restart. Regression tests must decode the server-side backup after discarding the original plan and verify it can restore the original Subscription spec after safe target release. + +Revision collision observations during COD handoff are retried within the existing rollout timeout. Only current-generation completion and availability allow migration to continue; persistent collisions fail with the controller diagnostic and preserve staged recovery resources. diff --git a/specs/20260821-migration-v0-to-v1/validation.md b/specs/20260821-migration-v0-to-v1/validation.md index 153223d..d4f5ba1 100644 --- a/specs/20260821-migration-v0-to-v1/validation.md +++ b/specs/20260821-migration-v0-to-v1/validation.md @@ -34,7 +34,7 @@ kind cluster with both OLMv0 and OLMv1 installed. Assert inline and Secret-backed object encodings using the current COS/COD definitions, including workload preservation during rollback. Older experimental schemas are outside the compatibility requirements. - Assert prompt failures for all current-generation terminal `Progressing=False` reasons except successful completion, including revision collisions and invalid revisions; preserve the controller's reason and message. Definitive COD create rejections restore OLMv0 and report that the target cannot be active; timeouts and transport failures refuse automatic recovery. + Assert prompt failures for all current-generation terminal `Progressing=False` reasons except successful completion and retryable revision collisions, including invalid revisions; preserve the controller's reason and message. Definitive COD create rejections restore OLMv0 and report that the target cannot be active; timeouts and transport failures refuse automatic recovery. Rollback persists verified COD UIDs before deletion and accepts matching dangling references even after restarting rollback. Unknown UIDs remain rejected, and failure to persist verified identity prevents COD deletion. ## V2. Eligibility matrix (one case per check, R3) @@ -173,3 +173,5 @@ creation, before rollout/handoff failures can strand the operator. Preserve them on failed or uncertain handoffs and refuse automatic OLMv0 restart. Regression tests must decode the server-side backup after discarding the original plan and verify it can restore the original Subscription spec after safe target release. + +Revision collision observations during COD handoff are retried within the existing rollout timeout. Only current-generation completion and availability allow migration to continue; persistent collisions fail with the controller diagnostic and preserve staged recovery resources. diff --git a/test/e2e/migration/e2e_test.go b/test/e2e/migration/e2e_test.go index e195a98..edc3141 100644 --- a/test/e2e/migration/e2e_test.go +++ b/test/e2e/migration/e2e_test.go @@ -833,16 +833,30 @@ func TestSystemManagedNamespaceMigration(t *testing.T) { if err := json.Unmarshal([]byte(namespaceJSON), &managedNamespace); err != nil { t.Fatalf("decode system-managed namespace: %v", err) } - catalogCOS := subscription + "-2" - ownedByCatalogCOS := false - for _, owner := range managedNamespace.OwnerReferences { - if owner.Kind == ocv1.ClusterObjectSetKind && owner.Name == catalogCOS { - ownedByCatalogCOS = true - break - } + owner := metav1.GetControllerOf(&managedNamespace) + if owner == nil || owner.Kind != ocv1.ClusterObjectSetKind || owner.APIVersion != ocv1.GroupVersion.String() { + t.Fatalf("system-managed namespace has no COS controller: %#v", managedNamespace.OwnerReferences) + } + _, kubeClient, _ := newMigrator(t) + var revision ocv1.ClusterObjectSet + if err := kubeClient.Get(t.Context(), client.ObjectKey{Name: owner.Name}, &revision); err != nil { + t.Fatal(err) + } + if revision.UID != owner.UID || revision.Spec.Group != subscription || revision.Spec.CollisionProtection != ocv1.CollisionProtectionPrevent { + t.Fatalf("namespace owner is not a protected revision of %s: %+v", subscription, revision) } - if !ownedByCatalogCOS { - t.Fatalf("system-managed namespace %q ownerReferences = %#v, want catalog ClusterObjectSet %q", targetNamespace, managedNamespace.OwnerReferences, catalogCOS) + var extension ocv1.ClusterExtension + if err := kubeClient.Get(t.Context(), client.ObjectKey{Name: subscription}, &extension); err != nil { + t.Fatal(err) + } + if !metav1.IsControlledBy(&revision, &extension) { + var deployment ocv1.ClusterObjectDeployment + if err := kubeClient.Get(t.Context(), client.ObjectKey{Name: subscription}, &deployment); err != nil { + t.Fatal(err) + } + if !metav1.IsControlledBy(&revision, &deployment) || !metav1.IsControlledBy(&deployment, &extension) { + t.Fatal("namespace revision is not managed by the migrated ClusterExtension") + } } targetDeployments, err := output("kubectl", "get", "deployment", "-n", targetNamespace, "-o", "name") if err != nil || strings.TrimSpace(targetDeployments) == "" { From c54eada6ebd35e2ea3687ca4345d96afe30857d1 Mon Sep 17 00:00:00 2001 From: Todd Short Date: Thu, 12 Nov 2026 09:59:05 -0500 Subject: [PATCH 08/10] fix: finish protected COD rollout before CE handoff Wait for current-generation completion after changing the COD template to Prevent. This prevents catalog rollout from overtaking the protected staging revision. Add a timeout regression proving stale initial readiness cannot create a CE, and update migration documentation. Signed-off-by: Todd Short --- migration/pkg/migration/deployment.go | 6 +++++- migration/pkg/migration/deployment_test.go | 15 +++++++++++++-- specs/20260821-migration-v0-to-v1/e2e.md | 2 ++ specs/20260821-migration-v0-to-v1/plan.md | 2 ++ specs/20260821-migration-v0-to-v1/requirements.md | 2 ++ specs/20260821-migration-v0-to-v1/validation.md | 2 ++ 6 files changed, 26 insertions(+), 3 deletions(-) diff --git a/migration/pkg/migration/deployment.go b/migration/pkg/migration/deployment.go index e8d7456..6773cdf 100644 --- a/migration/pkg/migration/deployment.go +++ b/migration/pkg/migration/deployment.go @@ -93,7 +93,11 @@ func (m *Migrator) createClusterObjectDeployment(ctx context.Context, opts Optio if err := m.waitForDeployment(ctx, cod); err != nil { return err } - return m.protectDeploymentForAdoption(ctx, cod) + if err := m.protectDeploymentForAdoption(ctx, cod); err != nil { + return err + } + // Finish the protected staging rollout before CE can introduce catalog content. + return m.waitForDeployment(ctx, cod) } // protectDeploymentForAdoption atomically enables collision protection and CE diff --git a/migration/pkg/migration/deployment_test.go b/migration/pkg/migration/deployment_test.go index 3833166..10a3be1 100644 --- a/migration/pkg/migration/deployment_test.go +++ b/migration/pkg/migration/deployment_test.go @@ -656,7 +656,7 @@ func TestProtectedCODHandoff(t *testing.T) { // TestProtectedCODFailurePreservesStaging refuses CE creation and OLMv0 recovery // after an initial rollout timeout or an uncertain protection-patch outcome. func TestProtectedCODFailurePreservesStaging(t *testing.T) { - for _, mode := range []string{"wait timeout", "patch rejected", "patch response lost"} { + for _, mode := range []string{"wait timeout", "patch rejected", "patch response lost", "protected rollout timeout"} { t.Run(mode, func(t *testing.T) { m := migrationTestClient(t, establishedClusterObjectDeploymentCRD()) patchAttempted := false @@ -678,6 +678,14 @@ func TestProtectedCODFailurePreservesStaging(t *testing.T) { }, Patch: func(ctx context.Context, c client.WithWatch, obj client.Object, p client.Patch, opts ...client.PatchOption) error { patchAttempted = true + if mode == "protected rollout timeout" { + if err := c.Patch(ctx, obj, p, opts...); err != nil { + return err + } + cod := obj.(*ocv1.ClusterObjectDeployment) + cod.Generation++ // The initial rollout status is now stale. + return c.Update(ctx, cod) + } if mode == "patch response lost" { if err := c.Patch(ctx, obj, p, opts...); err != nil { return err @@ -692,6 +700,9 @@ func TestProtectedCODFailurePreservesStaging(t *testing.T) { if err == nil || !result.TargetMayBeActive { t.Fatalf("result=%+v error=%v", result, err) } + if mode == "protected rollout timeout" && (!patchAttempted || !errors.Is(err, context.DeadlineExceeded)) { + t.Fatalf("did not wait for protected rollout: %v", err) + } if mode == "wait timeout" && patchAttempted { t.Fatal("enabled adoption before readiness") } @@ -699,7 +710,7 @@ func TestProtectedCODFailurePreservesStaging(t *testing.T) { if err := m.Client.Get(t.Context(), client.ObjectKey{Name: "example"}, &cod); err != nil { t.Fatal(err) } - if mode != "patch response lost" && cod.Labels[controllerManagedByLabel] != "" { + if mode != "patch response lost" && mode != "protected rollout timeout" && cod.Labels[controllerManagedByLabel] != "" { t.Fatal("failed handoff enabled adoption") } if mode == "patch response lost" && (cod.Spec.Template.Spec.CollisionProtection != ocv1.CollisionProtectionPrevent || cod.Labels[controllerManagedByLabel] != "operator-controller") { diff --git a/specs/20260821-migration-v0-to-v1/e2e.md b/specs/20260821-migration-v0-to-v1/e2e.md index 1672c81..e68ccf7 100644 --- a/specs/20260821-migration-v0-to-v1/e2e.md +++ b/specs/20260821-migration-v0-to-v1/e2e.md @@ -439,3 +439,5 @@ Library callers can decode the saved spec into `Backup.Subscription` and use recovery has succeeded. Revision collision observations during COD handoff are retried within the existing rollout timeout. Only current-generation completion and availability allow migration to continue; persistent collisions fail with the controller diagnostic and preserve staged recovery resources. + +COD-only migration waits for the protected staging rollout to complete after changing the template to `Prevent`, before creating the ClusterExtension. Stale initial-generation readiness must not authorize catalog handoff. diff --git a/specs/20260821-migration-v0-to-v1/plan.md b/specs/20260821-migration-v0-to-v1/plan.md index 7fcfa1c..141f1a2 100644 --- a/specs/20260821-migration-v0-to-v1/plan.md +++ b/specs/20260821-migration-v0-to-v1/plan.md @@ -329,3 +329,5 @@ tests must decode the server-side backup after discarding the original plan and verify it can restore the original Subscription spec after safe target release. Revision collision observations during COD handoff are retried within the existing rollout timeout. Only current-generation completion and availability allow migration to continue; persistent collisions fail with the controller diagnostic and preserve staged recovery resources. + +COD-only migration waits for the protected staging rollout to complete after changing the template to `Prevent`, before creating the ClusterExtension. Stale initial-generation readiness must not authorize catalog handoff. diff --git a/specs/20260821-migration-v0-to-v1/requirements.md b/specs/20260821-migration-v0-to-v1/requirements.md index 1cb848b..7693ffd 100644 --- a/specs/20260821-migration-v0-to-v1/requirements.md +++ b/specs/20260821-migration-v0-to-v1/requirements.md @@ -392,3 +392,5 @@ tests must decode the server-side backup after discarding the original plan and verify it can restore the original Subscription spec after safe target release. Revision collision observations during COD handoff are retried within the existing rollout timeout. Only current-generation completion and availability allow migration to continue; persistent collisions fail with the controller diagnostic and preserve staged recovery resources. + +COD-only migration waits for the protected staging rollout to complete after changing the template to `Prevent`, before creating the ClusterExtension. Stale initial-generation readiness must not authorize catalog handoff. diff --git a/specs/20260821-migration-v0-to-v1/validation.md b/specs/20260821-migration-v0-to-v1/validation.md index d4f5ba1..8a63f54 100644 --- a/specs/20260821-migration-v0-to-v1/validation.md +++ b/specs/20260821-migration-v0-to-v1/validation.md @@ -175,3 +175,5 @@ tests must decode the server-side backup after discarding the original plan and verify it can restore the original Subscription spec after safe target release. Revision collision observations during COD handoff are retried within the existing rollout timeout. Only current-generation completion and availability allow migration to continue; persistent collisions fail with the controller diagnostic and preserve staged recovery resources. + +COD-only migration waits for the protected staging rollout to complete after changing the template to `Prevent`, before creating the ClusterExtension. Stale initial-generation readiness must not authorize catalog handoff. From 014ee1f5e2854cb040d98941d4388b2e0540e06c Mon Sep 17 00:00:00 2001 From: Todd Short Date: Thu, 12 Nov 2026 11:04:02 -0500 Subject: [PATCH 09/10] docs: correct COD-only recovery fallback Describe exporting an orphaned COD-generated revision when the COD is unavailable, rather than implying failed COD creation leaves a directly staged COS. Preserve the requirement to export backups before cleanup. Signed-off-by: Todd Short --- specs/20260821-migration-v0-to-v1/e2e.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/specs/20260821-migration-v0-to-v1/e2e.md b/specs/20260821-migration-v0-to-v1/e2e.md index e68ccf7..685da63 100644 --- a/specs/20260821-migration-v0-to-v1/e2e.md +++ b/specs/20260821-migration-v0-to-v1/e2e.md @@ -413,13 +413,15 @@ staging resource using the same backup annotations as the CE. These annotations are written with resource creation, before any rollout wait or handoff can fail, and are propagated to COD-generated revisions. This does not depend on `--backup`. -Export the retained COD before removing any staging resources. If COD creation -failed after a directly staged COS, export that COS instead: +Export the retained COD before removing any staging resources. If the COD is no +longer available but an orphaned COD-generated COS retains the migration backup +annotations, export that revision instead. Failed COD creation does not leave a +directly staged COS: this migration path creates revisions only through a COD. ```bash kubectl get clusterobjectdeployment "$ce_name" -o json > staging.json -# Alternative when only the initial COS exists: -# kubectl get clusterobjectset "${ce_name}-1" -o json > staging.json +# Alternative: set cos_name to the orphaned COD-generated revision retaining the backup. +# kubectl get clusterobjectset "$cos_name" -o json > staging.json jq -e ' .metadata.annotations as $a | ($a["olm.operatorframework.io/migrated-from-subscription"] | split("/")) as $source | From 69a2bc013c209377966b0b8e9fbc29832c9e41ed Mon Sep 17 00:00:00 2001 From: Todd Short Date: Fri, 13 Nov 2026 09:25:58 -0500 Subject: [PATCH 10/10] test: adapt COD prerequisites to merged preflight Signed-off-by: Todd Short --- migration/pkg/migration/deployment_test.go | 2 +- migration/pkg/migration/unit_test.go | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/migration/pkg/migration/deployment_test.go b/migration/pkg/migration/deployment_test.go index 10a3be1..5bd5886 100644 --- a/migration/pkg/migration/deployment_test.go +++ b/migration/pkg/migration/deployment_test.go @@ -75,7 +75,7 @@ func TestDeploymentReadiness(t *testing.T) { // TestPrepareDeployment covers invalid names, unavailable APIs, and occupied deployment identities. func TestPrepareDeployment(t *testing.T) { - crd := &apiextensionsv1.CustomResourceDefinition{ObjectMeta: metav1.ObjectMeta{Name: clusterObjectDeploymentCRDName}, Spec: apiextensionsv1.CustomResourceDefinitionSpec{Versions: []apiextensionsv1.CustomResourceDefinitionVersion{{Name: "v1", Served: true, Schema: testRevisionSchema(true)}}}, Status: apiextensionsv1.CustomResourceDefinitionStatus{Conditions: []apiextensionsv1.CustomResourceDefinitionCondition{{Type: apiextensionsv1.Established, Status: apiextensionsv1.ConditionTrue}}}} + crd := establishedClusterObjectDeploymentCRD() ctx := context.Background() if err := migrationTestClient(t).prepareClusterObjectDeployment(ctx, "example"); err == nil { t.Fatal("accepted missing CRD") diff --git a/migration/pkg/migration/unit_test.go b/migration/pkg/migration/unit_test.go index 1d3dc6e..977bec7 100644 --- a/migration/pkg/migration/unit_test.go +++ b/migration/pkg/migration/unit_test.go @@ -1289,7 +1289,7 @@ func TestPrerequisitesAndRecoveryErrors(t *testing.T) { func TestGatherRequiresControllerNamespace(t *testing.T) { sub, csv := healthySubscriptionFixtures() - m := migrationTestClient(t, sub, csv) + m := migrationTestClient(t, sub, csv, establishedClusterObjectDeploymentCRD()) _, err := m.Gather(context.Background(), Options{SubscriptionName: sub.Name, SubscriptionNamespace: sub.Namespace}) if err == nil || !strings.Contains(err.Error(), "operator-controller Deployment") { t.Fatalf("Gather() without the controller namespace = %v, want a prerequisite error", err)