ssa: introduce support for migrating API version

Signed-off-by: Matheus Pimenta <matheuscscp@gmail.com>

Author: matheuscscp

ssa/manager_apply.go

@@ -68,6 +68,11 @@ type ApplyOptions struct {
 	// CustomStageKinds defines a set of Kubernetes resource types that should be applied
 	// in a separate stage after CRDs and before namespaced objects.
 	CustomStageKinds map[schema.GroupKind]struct{} `json:"customStageKinds,omitempty"`
+
+	// MigrateAPIVersion configures the engine to migrate the API version
+	// in managed fields to the API version of the applied object when they
+	// differ.
+	MigrateAPIVersion bool `json:"migrateAPIVersion,omitempty"`
 }
 
 // ApplyCleanupOptions defines which metadata entries are to be removed before applying objects.
@@ -108,6 +113,15 @@ func (m *ResourceManager) Apply(ctx context.Context, object *unstructured.Unstru
 		return m.changeSetEntry(object, SkippedAction), nil
 	}
 
+	var patched bool
+	if opts.MigrateAPIVersion && getError == nil {
+		var err error
+		patched, err = m.migrateAPIVersion(ctx, existingObject, object.GetAPIVersion())
+		if err != nil {
+			return nil, fmt.Errorf("%s failed to migrate API version: %w", utils.FmtUnstructured(existingObject), err)
+		}
+	}
+
 	dryRunObject := object.DeepCopy()
 	if err := m.dryRunApply(ctx, dryRunObject); err != nil {
 		if !errors.IsNotFound(getError) && m.shouldForceApply(object, existingObject, opts, err) {
@@ -121,11 +135,12 @@ func (m *ResourceManager) Apply(ctx context.Context, object *unstructured.Unstru
 		return nil, ssaerrors.NewDryRunErr(err, dryRunObject)
 	}
 
-	patched, err := m.cleanupMetadata(ctx, object, existingObject, opts.Cleanup)
+	patchedCleanupMetadata, err := m.cleanupMetadata(ctx, object, existingObject, opts.Cleanup)
 	if err != nil {
 		return nil, fmt.Errorf("%s metadata.managedFields cleanup failed: %w",
 			utils.FmtUnstructured(existingObject), err)
 	}
+	patched = patched || patchedCleanupMetadata
 
 	// do not apply objects that have not drifted to avoid bumping the resource version
 	if !patched && !m.hasDrifted(existingObject, dryRunObject) {
@@ -172,6 +187,15 @@ func (m *ResourceManager) ApplyAll(ctx context.Context, objects []*unstructured.
 					return nil
 				}
 
+				var patched bool
+				if opts.MigrateAPIVersion && getError == nil {
+					var err error
+					patched, err = m.migrateAPIVersion(ctx, existingObject, object.GetAPIVersion())
+					if err != nil {
+						return fmt.Errorf("%s failed to migrate API version: %w", utils.FmtUnstructured(existingObject), err)
+					}
+				}
+
 				dryRunObject := object.DeepCopy()
 				if err := m.dryRunApply(ctx, dryRunObject); err != nil {
 					// We cannot have an immutable error (and therefore shouldn't force-apply) if the resource doesn't
@@ -207,11 +231,12 @@ func (m *ResourceManager) ApplyAll(ctx context.Context, objects []*unstructured.
 					}
 				}
 
-				patched, err := m.cleanupMetadata(ctx, object, existingObject, opts.Cleanup)
+				patchedCleanupMetadata, err := m.cleanupMetadata(ctx, object, existingObject, opts.Cleanup)
 				if err != nil {
 					return fmt.Errorf("%s metadata.managedFields cleanup failed: %w",
 						utils.FmtUnstructured(existingObject), err)
 				}
+				patched = patched || patchedCleanupMetadata
 
 				if patched || m.hasDrifted(existingObject, dryRunObject) {
 					toApply[i] = object
@@ -345,6 +370,46 @@ func (m *ResourceManager) apply(ctx context.Context, object *unstructured.Unstru
 	return m.client.Patch(ctx, object, client.Apply, opts...)
 }
 
+// migrateAPIVersion updates the API version in managed field entries
+// whose API version differs from the desired API version using a raw
+// patch. This is important for making the API server validate the
+// managed fields against the schema of the desired API version on
+// dry-run. If this operation succeeds, existingObject will be updated
+// with the content returned by the API server. The function returns a
+// boolean indicating whether a patch was applied. All managed field
+// entries owned by this ResourceManager's field owner are migrated,
+// including entries on subresources like status — leaving any of our
+// own entries at an older API version can cause dry-run failures on
+// subsequent applies, and a stale main-resource entry can even trigger
+// failures on a status subresource apply (and vice versa). Entries
+// owned by other field managers are left untouched.
+func (m *ResourceManager) migrateAPIVersion(ctx context.Context,
+	existingObject *unstructured.Unstructured,
+	desiredAPIVersion string) (bool, error) {
+
+	// Build patch.
+	patch, err := PatchMigrateToVersion(existingObject, desiredAPIVersion,
+		WithMigrateManager(m.owner.Field))
+	if err != nil {
+		return false, fmt.Errorf("failed to create patch for migrating managed fields API version: %w", err)
+	}
+	if len(patch) == 0 {
+		return false, nil
+	}
+
+	// Apply patch.
+	patchBytes, err := json.Marshal(patch)
+	if err != nil {
+		return false, fmt.Errorf("failed to marshal patch for migrating managed fields API version: %w", err)
+	}
+	rawPatch := client.RawPatch(types.JSONPatchType, patchBytes)
+	if err := m.client.Patch(ctx, existingObject, rawPatch, client.FieldOwner(m.owner.Field)); err != nil {
+		return false, fmt.Errorf("failed to migrate managed fields API version to %s: %w", desiredAPIVersion, err)
+	}
+
+	return true, nil
+}
+
 // cleanupMetadata performs an HTTP PATCH request to remove entries from metadata annotations, labels and managedFields.
 func (m *ResourceManager) cleanupMetadata(ctx context.Context,
 	desiredObject *unstructured.Unstructured,