Skip to content

Commit 231c6f0

Browse files
theunrepentantgeektheunrepentantgeek
authored
Document our approach for rare property conversions (#5005)
* Add draft * Update draft
1 parent 6f2ee30 commit 231c6f0

File tree

2 files changed

+77
-9
lines changed

2 files changed

+77
-9
lines changed

‎docs/hugo/content/design/ADR-2025-10-28-Property-Conversion-Long-Tail/_index.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: '2025-10: The Long Tail of Property Conversion'
3+
toc_hide: true
4+
---
5+
6+
## Context
7+
8+
We are successfully generating conversion code for inter-version transformation of resources across a wide range of resources. However, we're encountering the "long tail" - increasingly rare edge cases that fall outside the capabilities of our current automatic conversion generator.
9+
10+
The most recent example affects preview versions of [`ManagedClustersAgentPool`]({{< relref "reference/containerservice/v1api20240402preview/_index.md" >}}#ManagedClustersAgentPool) (a child resource of [`ManagedCluster`]({{< relref "reference/containerservice/v1api20240402preview/_index.md" >}}#ManagedCluster)) where the cardinatlity of [ScaleProfile]({{< relref "reference/containerservice/v1api20240402preview/_index.md" >}}#ScaleProfile) has changed from plural (`AutoScaleProfile[]`) to singular (`AutoScaleProfile`).
11+
12+
In the past, as each case of incompatibility has arisen, we've enhanced the code generator to handle the new case, taking the stance that it's better to handle these cases once (by enhancing the generator) than to handle them many times (by writing custom conversion code for each resource that needs it).
13+
14+
### Option 1: Continue to extend the generator (status quo)
15+
16+
As new cases that aren't yet handled arise, enhance the code generator to handle the required conviersions automatically. This is the status quo approach.
17+
18+
#### Pros
19+
20+
* Once a case is handled, it is handled for all resources, so we don't need to write custom conversion code for each resource that needs it.
21+
22+
#### Cons
23+
24+
* Each new case adds complexity to the generator, making it harder to maintain and reason about.
25+
* The frequency of new cases is low, so the cost of enhancing the generator may outweigh the benefits.
26+
27+
### Option 2: Add an opt-out mechanism for custom conversion
28+
29+
When a resource requires a property conversion that the generator doesn't handle, allow configuration to specify that custom conversion code will be provided for that specific property. The generator will then skip generating conversion code for that property, allowing the custom code to take precedence.
30+
31+
#### Pros
32+
33+
* Avoids adding complexity to the generator for rare cases.
34+
* Allows for targeted custom conversion code only where needed.
35+
* We already have the `augment*` hooks for custom conversion code, so this approach builds on existing mechanisms.
36+
37+
#### Cons
38+
39+
* Requires writing custom conversion code for each resource that needs it, which could lead to more code to maintain.
40+
* May lead to inconsistencies if different resources implement custom conversion differently (though, policy differences between different situations may make this an advantage).
41+
42+
43+
## Decision
44+
45+
Add an opt-out mechanism for custom conversion for specific properties when the generator doesn't handle the required conversion.
46+
47+
Assess each case as it arises, and if it is rare enough that enhancing the generator isn't justified, use the opt-out mechanism to provide custom conversion code for that property. For more common cases, continue to enhance the generator as we have in the past.
48+
49+
### Suggested Configuration
50+
51+
Enhance the existing `objectModelConfiguration` structure to allow specifying `$conversionStrategy` at the property level. Permissible values would be:
52+
53+
* `auto` - Default behavior, generate conversion code automatically.
54+
* `custom` - Skip generating conversion code for this specific property only, but generate a type assertion to force implementation of the appropriate `augment*` hook (this will help to avoid silent failures where a developer forgets to implement the custom conversion code).
55+
* `none` - Skip generating conversion code for this property without forcing implementation of the `augment*` hook (useful for properties that don't require conversion at all).
56+
57+
## Status
58+
59+
Proposed.
60+
61+
## Consequences
62+
63+
## Experience Report
64+
65+
## References
66+
67+
* [Resource Versioning]({{< relref "design/versioning/_index.md" >}})

‎docs/hugo/content/design/_index.md‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,16 @@ These ADRs reflect work that is being discussed, has been proposed, or is curren
1919

2020
### 2025
2121

22-
| Proposed | Title | Description | Status |
23-
| :------: | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
24-
| 2025 | [**Version Priority**]({{< relref "ADR-2025-05-Version-Priority" >}}) | A design to address the problems with version priority in Azure Service Operator, ensuring that the most recent resource version is selected by Kubernetes. | Implementation underway |
25-
| 2025 | [**Improving ARM References**]({{< relref "ADR-2025-01-ARM-References" >}}) | Options for remedying the problems we face when we fail to identify a property as an ARM reference prior to releasing ASO. | Implementation underway |
26-
| 2024 | [**Upstream Deletion**]({{< relref "ADR-2024-02-Upstream-Deletion" >}}) | When might deletion of an upstream resource occur and how will ASO handle it. | Open |
27-
| 2023 | [**Resource Deprecation**]({{< relref "ADR-2023-04-Deprecation" >}}) | Understand the policy for handling Azure resource deprecation in Azure Service Operator, including the process for flagging deprecated resources, communicating changes, and removing unsupported resources. | Open |
28-
| 2022 | [**Change Detection**]({{< relref "ADR-2022-11-Change-Detection" >}}) | The challenges of change detection in Azure Service Operator, discussing the limitations of relying on Azure Resource Manager for goal state comparison, the impact of ARM throttling, and a proposal for ASO to perform its own goal state comparison to mitigate these issues. | Revision in progress |
29-
| Earlier | [**CrossPlane**]({{< relref "crossplane" >}}) | Discusses the intricacies of code generation for Crossplane, including static "special" properties, cross resource references, and the challenges associated with generating these references. | Open |
30-
| Earlier | [**Improving the Reconciler interface**]({{< relref "reconcile-interface" >}}) | Explore a proposal for improving the Reconciler interface in controller-runtime, addressing issues of code duplication and potential bugs due to differences in checks for Create vs Delete operations. | Open |
22+
| Proposed | Title | Description | Status |
23+
| :------: | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
24+
| 2025 | [**The Long Tail of Property Conversion**]({{< relref "ADR-2025-10-28-Property-Conversion-Long-Tail" >}}) | A design to address the increasingly rare edge cases that fall outside the capabilities of our current automatic conversion generator for inter-version transformation of resources. | Proposed |
25+
| 2025 | [**Version Priority**]({{< relref "ADR-2025-05-Version-Priority" >}}) | A design to address the problems with version priority in Azure Service Operator, ensuring that the most recent resource version is selected by Kubernetes. | Implementation underway |
26+
| 2025 | [**Improving ARM References**]({{< relref "ADR-2025-01-ARM-References" >}}) | Options for remedying the problems we face when we fail to identify a property as an ARM reference prior to releasing ASO. | Implementation underway |
27+
| 2024 | [**Upstream Deletion**]({{< relref "ADR-2024-02-Upstream-Deletion" >}}) | When might deletion of an upstream resource occur and how will ASO handle it. | Open |
28+
| 2023 | [**Resource Deprecation**]({{< relref "ADR-2023-04-Deprecation" >}}) | Understand the policy for handling Azure resource deprecation in Azure Service Operator, including the process for flagging deprecated resources, communicating changes, and removing unsupported resources. | Open |
29+
| 2022 | [**Change Detection**]({{< relref "ADR-2022-11-Change-Detection" >}}) | The challenges of change detection in Azure Service Operator, discussing the limitations of relying on Azure Resource Manager for goal state comparison, the impact of ARM throttling, and a proposal for ASO to perform its own goal state comparison to mitigate these issues. | Revision in progress |
30+
| Earlier | [**CrossPlane**]({{< relref "crossplane" >}}) | Discusses the intricacies of code generation for Crossplane, including static "special" properties, cross resource references, and the challenges associated with generating these references. | Open |
31+
| Earlier | [**Improving the Reconciler interface**]({{< relref "reconcile-interface" >}}) | Explore a proposal for improving the Reconciler interface in controller-runtime, addressing issues of code duplication and potential bugs due to differences in checks for Create vs Delete operations. | Open |
3132

3233
## Completed Changes
3334

0 commit comments

Comments
 (0)