Allow opting out of property conversions if an error occurs (#5051)

* Add $conversionStrategy configuration

* Respect renames when constructing compatibility types

* Look up property conversion strategy from config

* Use config to suppress errors

* Add docs

* Tidy azure-arm.yaml

Author: theunrepentantgeek

v2/azure-arm.yaml

@@ -1008,6 +1008,18 @@ status:
 #     The name in the serialized ARM payload does NOT change. This only changes the name of the property
 #     in the ASO types. The shape serialized to ARM uses the original name.
 #
+# $conversionStrategy: <string>
+#     Specifies a custom conversion strategy to use when converting between API versions.
+#     Only valid on properties which are complex types (i.e. objects) for which attempted automatic 
+#     conversion returns an error.
+#
+#     Valid values are:
+#     - auto - use automatic conversion (default)
+#     - manual - use manually implemented conversion functions
+#
+#     Note that manual implementation of the appropriate augment* interface(s) will be *required* 
+#     to make the generated conversion tests pass.
+#
 objectModelConfiguration:
   alertsmanagement:
     2021-04-01:
@@ -2373,6 +2385,12 @@ objectModelConfiguration:
       ManagedClusters_MaintenanceConfiguration:
         $exportAs: MaintenanceConfiguration
         $supportedFrom: v2.11.0
+      ScaleProfile:
+        Autoscale:
+          $conversionStrategy: manual
+      ScaleProfile_STATUS:
+        Autoscale:
+          $conversionStrategy: manual
       UserAssignedIdentity:
         ClientId:
           $importConfigMapMode: optional

v2/tools/generator/internal/codegen/pipeline/repair_skipping_properties.go

@@ -332,9 +332,12 @@ func (repairer *skippingPropertyRepairer) createRepairs(
 		return repairer.createRepairs(reintroduced)
 	}
 
-	// Construct the name of the compatibility type we need to create
+	// Construct the name of the compatibility type we need to create, allowing for renames
 	compatPkg := astmodel.MakeCompatPackageReference(lastMissing.DeclaringType().InternalPackageReference())
 	compatType := tn.WithPackageReference(compatPkg)
+	if newName, ok := repairer.objectModelConfiguration.TypeNameInNextVersion.Lookup(tn); ok {
+		compatType = compatType.WithName(newName)
+	}
 
 	result, err := repairer.createRepairs(reintroduced)
 	if err != nil {

v2/tools/generator/internal/config/object_model_configuration.go

@@ -48,6 +48,7 @@ type ObjectModelConfiguration struct {
 	TypeNameInNextVersion    typeAccess[string]
 
 	// Property access fields here (alphabetical, please)
+	ConversionStrategy             propertyAccess[ConversionStrategy]
 	Description                    propertyAccess[string]
 	ImportConfigMapMode            propertyAccess[ImportConfigMapMode]
 	IsSecret                       propertyAccess[bool]
@@ -106,6 +107,8 @@ func NewObjectModelConfiguration() *ObjectModelConfiguration {
 		result, func(c *TypeConfiguration) *configurable[string] { return &c.NameInNextVersion })
 
 	// Initialize property access fields here (alphabetical, please)
+	result.ConversionStrategy = makePropertyAccess[ConversionStrategy](
+		result, func(c *PropertyConfiguration) *configurable[ConversionStrategy] { return &c.ConversionStrategy })
 	result.Description = makePropertyAccess[string](
 		result, func(c *PropertyConfiguration) *configurable[string] { return &c.Description })
 	result.ImportConfigMapMode = makePropertyAccess[ImportConfigMapMode](

v2/tools/generator/internal/config/property_configuration.go

@@ -23,6 +23,7 @@ import (
 type PropertyConfiguration struct {
 	name string
 	// Configurable properties here (alphabetical, please)
+	ConversionStrategy             configurable[ConversionStrategy]  // Specify the conversion strategy for this property
 	Description                    configurable[string]              // Specify a description override for this property
 	ImportConfigMapMode            configurable[ImportConfigMapMode] // The config map mode
 	IsSecret                       configurable[bool]                // Specify whether this property is a secret
@@ -52,8 +53,16 @@ const (
 // arm+compat allows us to fix up an ARM reference if we miss it before releasing a version of the resource.
 // See https://azure.github.io/azure-service-operator/design/adr-2025-01-arm-references/ for the gory details.
 
+type ConversionStrategy string
+
+const (
+	ConversionStrategyAuto   = ConversionStrategy("auto")   // Automatic conversion (default)
+	ConversionStrategyManual = ConversionStrategy("manual") // Manual conversion
+)
+
 // Tags used in yaml files to specify configurable properties. Alphabetical please.
 const (
+	conversionStrategyTag             = "$conversionStrategy"             // String specifying the conversion strategy (auto or manual)
 	descriptionTag                    = "$description"                    // String overriding the properties default description
 	exportAsConfigMapPropertyNameTag  = "$exportAsConfigMapPropertyName"  // String specifying the name of the property set to export this property as a config map.
 	importConfigMapModeTag            = "$importConfigMapMode"            // string specifying the ImportConfigMapMode mode
@@ -69,6 +78,7 @@ func NewPropertyConfiguration(name string) *PropertyConfiguration {
 	return &PropertyConfiguration{
 		name: name,
 		// Initialize configurable properties here (alphabetical, please)
+		ConversionStrategy:             makeConfigurable[ConversionStrategy](conversionStrategyTag, scope),
 		Description:                    makeConfigurable[string](descriptionTag, scope),
 		ImportConfigMapMode:            makeConfigurable[ImportConfigMapMode](importConfigMapModeTag, scope),
 		IsSecret:                       makeConfigurable[bool](isSecretTag, scope),
@@ -94,6 +104,20 @@ func (pc *PropertyConfiguration) UnmarshalYAML(value *yaml.Node) error {
 			continue
 		}
 
+		// $conversionStrategy: <string>
+		if strings.EqualFold(lastID, conversionStrategyTag) && c.Kind == yaml.ScalarNode {
+			switch strings.ToLower(c.Value) {
+			case string(ConversionStrategyAuto):
+				pc.ConversionStrategy.Set(ConversionStrategyAuto)
+			case string(ConversionStrategyManual):
+				pc.ConversionStrategy.Set(ConversionStrategyManual)
+			default:
+				return eris.Errorf("unknown %s value: %s.", conversionStrategyTag, c.Value)
+			}
+
+			continue
+		}
+
 		// $nameInNextVersion: <string>
 		if strings.EqualFold(lastID, nameInNextVersionTag) && c.Kind == yaml.ScalarNode {
 			pc.NameInNextVersion.Set(c.Value)

v2/tools/generator/internal/conversions/property_conversion_context.go

@@ -165,6 +165,23 @@ func (c *PropertyConversionContext) FindNextType(name astmodel.InternalTypeName)
 	return c.conversionGraph.FindNextType(name, c.definitions)
 }
 
+// PropertyConversionStrategy returns true if the specified property has been configured to use manual conversion.
+func (c *PropertyConversionContext) PropertyConversionStrategy(
+	container astmodel.InternalTypeName,
+	property astmodel.PropertyName,
+) config.ConversionStrategy {
+	if c.configuration == nil {
+		return config.ConversionStrategyAuto
+	}
+
+	strategy, ok := c.configuration.ConversionStrategy.Lookup(container, property)
+	if !ok {
+		return config.ConversionStrategyAuto
+	}
+
+	return strategy
+}
+
 // PathExists returns true if a path exists in the conversion graph starting from the specified type name and ending
 // at the specified type name. If no conversion graph is available, returns false.
 func (c *PropertyConversionContext) PathExists(

v2/tools/generator/internal/functions/property_assignment_function_builder.go

@@ -14,6 +14,7 @@ import (
 
 	"github.com/Azure/azure-service-operator/v2/internal/set"
 	"github.com/Azure/azure-service-operator/v2/tools/generator/internal/astmodel"
+	"github.com/Azure/azure-service-operator/v2/tools/generator/internal/config"
 	"github.com/Azure/azure-service-operator/v2/tools/generator/internal/conversions"
 )
 
@@ -246,7 +247,27 @@ func (builder *PropertyAssignmentFunctionBuilder) createConversions(
 		// Generate a conversion from one endpoint to another
 		conv, err := builder.createConversion(sourceEndpoint, destinationEndpoint, conversionContext)
 		if err != nil {
-			// An error was returned, we abort creating conversions for this object
+			// An error was returned, we can't create a conversion for this pair
+			// We return the error *unless* we have an excluded property
+
+			dstName := builder.direction.SelectName(builder.receiverDefinition.Name(), builder.otherDefinition.Name())
+			dstStrategy := conversionContext.PropertyConversionStrategy(
+				dstName,
+				astmodel.PropertyName(destinationEndpoint.Name()),
+			)
+
+			srcName := builder.direction.SelectName(builder.otherDefinition.Name(), builder.receiverDefinition.Name())
+			srcStrategy := conversionContext.PropertyConversionStrategy(
+				srcName,
+				astmodel.PropertyName(sourceEndpoint.Name()),
+			)
+
+			if srcStrategy == config.ConversionStrategyManual || dstStrategy == config.ConversionStrategyManual {
+				// One of the properties is marked as manual conversion, so we can skip this error
+				return nil
+			}
+
+			// Otherwise, return the conversion error
 			return eris.Wrapf(
 				err,
 				"creating conversion to %s by %s",