You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/hugo/content/guide/breaking-changes/_index.md
+10-87Lines changed: 10 additions & 87 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,111 +7,34 @@ We go to great lengths to avoid breaking changes as much as possible, as we're w
7
7
8
8
## Upcoming Breaking Changes
9
9
10
-
### Scheduled for v2.10.0
10
+
### Resource Versioning
11
11
12
-
* The following properties on `machinelearningservices.WorkspacesCompute` will be marked as secrets: `SslConfiguration.Key`, `SslConfiguration.Cert`, `VirtualMachineSshCredentials.PrivateKeyData`, and `VirtualMachineSshCredentials.PublicKeyData`.
13
-
We try to avoid breaking changes, but in this case, allowing raw keys in the spec is a security problem and as such we've decided to make a break to correct this issue.
12
+
As first reported in [#4147](https://github.com/Azure/azure-service-operator/issues/4147) and explored in the ADR [Resources and Version Priority]({{< relref "adr-2025-05-version-priority" >}}), the way we're defining our resource versions in ASO is not compliant with Kubernetes rules.
14
13
15
-
## Released Breaking Changes
14
+
This failure results in Kubernetes' [version priority](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#version-priority) rules consistently selecting the _oldest_ version of any ASO resource.
16
15
17
-
### 2.9.0
16
+
This has resulted in confusion, and more importantly, to _data loss for users as they work with their resources_. (See [ASO #4723](https://github.com/Azure/azure-service-operator/issues/4723), [CAPZ #5168](https://github.com/kubernetes-sigs/cluster-api-provider-azure/issues/5168), and [CAPZ #5649](https://github.com/kubernetes-sigs/cluster-api-provider-azure/issues/5649) for examples.)
18
17
19
-
Breaking changes are:
18
+
In upcoming releases of ASO, we're going to gradually migrate resources to a new compliant approach using `v1api` as a consistent prefix to just `v`.
20
19
21
-
* DelegatedManagedIdentityResourceId is now a secret
22
-
* ContainerService version v1api20230202preview has been deleted
23
-
24
-
For more information see [v2.9.0 Breaking Changes]( {{< relref "breaking-changes-v2.9.0.md" >}} ).
25
-
26
-
### v2.8.0
27
-
28
-
Breaking changes are:
29
-
30
-
* ManagedCluster property .spec.properties.windowsProfile.adminPassword is now a SecretReference rather than a string
31
-
* Use "never" rather than "" to prevent syncing for AZURE_SYNC_PERIOD
32
-
33
-
For more information see [v2.8.0 Breaking Changes]( {{< relref "breaking-changes-v2.8.0.md" >}} ).
34
-
35
-
### v2.6.0
36
-
37
-
Breaking changes are:
38
-
39
-
* VirtualMachineScaleSet ProtectedSettings now a SecretReference
40
-
41
-
For more information see [v2.6.0 Breaking Changes]( {{< relref "breaking-changes-v2.6.0.md" >}} ).
42
-
43
-
### v2.4.0
44
-
45
-
Breaking changes are:
46
-
47
-
* Beta CRD versions have been removed
48
-
49
-
For more information see [v2.4.0 Breaking Changes]( {{< relref "breaking-changes-v2.4.0.md" >}} ).
50
-
51
-
### v2.2.0
52
-
53
-
Breaking changes are:
54
-
55
-
* ManagedClusters ManagedClusterServicePrincipalProfile.Secret field is now marked as a SecretReference
56
-
* Remove un-used Status properties
57
-
58
-
For more information see [v2.2.0 Breaking Changes]( {{< relref "breaking-changes-v2.2.0.md" >}} ).
59
-
60
-
### v2.1.0
61
-
62
-
Breaking changes are:
63
-
64
-
* The operator no longer installs CRDs by default.
65
-
*`serviceoperator.azure.com/credential-from` no longer supports secret references that are outside the namespace the resource is in
66
-
* Upgrades from releases prior to `v2.0.0-beta.5` are still disallowed (same as v2.0.0)
67
-
68
-
For more information see [v2.1.0 Breaking Changes]( {{< relref "breaking-changes-v2.1.0.md" >}} ).
69
-
70
-
### v2.0.0
71
-
72
-
Breaking changes are:
73
-
74
-
* Upgrades from releases prior to `v2.0.0-beta.5` are disallowed
75
-
* Alpha CRD versions have been removed
76
-
* Structure change for ResourceGroup status
77
-
78
-
For more information see [v2.0.0 Breaking Changes]( {{< relref "breaking-changes-v2.0.0.md" >}} ).
79
-
80
-
### v2.0.0-beta.4
81
-
82
-
In the `v2.0.0-beta.4` release of Azure Service Operator (ASO) we pivoted to using Azure Swagger API Specifications as the sole source of truth for our code generator. This change brought with it a significant improvement in fidelity - the code we generate is now much closer to what the Azure Swagger API Specifications describe.
83
-
84
-
Unfortunately, this change also brings with it a number of breaking changes requiring simple manual modifications to pre-existing resources.
85
-
86
-
Breaking changes are:
87
-
88
-
* The discriminator value for polymorphic types has been changed to match the name of the property used to specify that option.
89
-
* Enumerated properties that previously had a base type but no enumeration values have been updated to include the enumeration values.
90
-
* Objects that were incorrectly generated as nested properties have been directly inlined
91
-
* ARM Id fields are now correctly identified as references, allowing linking to a resource in Kubernetes instead of only in Azure.
92
-
* Status properties that cannot be set by the end user on a Spec that were included in the Spec in error
93
-
* Sub-resources that were incorrectly inlined into the parent resource have been moved to a separate resource.
94
-
* Properties that previously included on Spec but actually had no function have been removed.
95
-
* Validation rules have been tightened, or added to properties that previously had no validation rules.
96
-
97
-
For detailed information, including an exhaustive list of all affected resource properties, see [v2.0.0-beta.4 Breaking Changes]( {{< relref "breaking-changes-v2.0.0-beta.4.md" >}} ).
20
+
This will, eventually, be a breaking change but we're going to try and make this as painless as possible by introducing the new versioning scheme alongside the old one (we'll support both `v1api20250701` and `v20250701` of the resource simultaneously) wherever possible.
98
21
99
22
## Policies
100
23
101
24
We know that breaking changes are a problem for many of our users, so we're making the following commitments to keep such things to a minimum.
102
25
103
26
**No breaking changes to existing resource versions**
104
27
105
-
We will not introduce a breaking change in an existing version of a resource such as `v1api20230101`.
28
+
We will not introduce a breaking change in an existing version of a resource such as `v1api20230101`.
106
29
107
30
In the case of such a change being forced upon us, we will take all reasonable steps to reduce the impact as far as possible.
108
31
109
-
The most likely cause of this will be a security issue that requires action - such as if we discover a password field that hasn't been correctly flagged as a secret.
32
+
The most likely cause of this will be a security issue that requires action - such as if we discover a password field that hasn't been correctly flagged as a secret.
110
33
There's also a possibilty of a change ocurring upstream, but we consider this to be extremely unlikely because of the stringent API change criteria used by Azure.
111
34
112
35
**Minimal breaking changes in new resource versions**
113
36
114
-
We *may* introduce breaking changes between versions of resources, such as between `v1api20230101` and `v1api20230201`. These two versions correspond to two different Azure API versions (that is, `2023-01-01` and `2023-02-01`), and if the upstream Azure service introduces a breaking change in the newer of these two API versions we may pass that breaking change along.
37
+
We _may_ introduce breaking changes between versions of resources, such as between `v1api20230101` and `v1api20230201`. These two versions correspond to two different Azure API versions (that is, `2023-01-01` and `2023-02-01`), and if the upstream Azure service introduces a breaking change in the newer of these two API versions we may pass that breaking change along.
115
38
116
39
### Mitigation techniques
117
40
@@ -121,7 +44,7 @@ We've done this before when a new version of a resource API introduced a breakin
121
44
122
45
**Custom Tooling**: For our `v2.0.0` release, we provided a specialized tool (`asoctl`) specifically designed to smooth the way for upgrading users. In addition to the existing two modes, we may add further functions to cater for other scenarios.
123
46
124
-
For users upgrading from ASO v1, [`asoctl import azure-resource`]( {{< relref "asoctl#import-azure-resource" >}} ) provides a way to scaffold an ASO v2 resource based on an existing Azure resource.
47
+
For users upgrading from ASO v1, [`asoctl import azure-resource`]( {{< relref "asoctl#import-azure-resource" >}} ) provides a way to scaffold an ASO v2 resource based on an existing Azure resource.
125
48
126
49
For clusters that once had an alpha release of ASO v2 installed, [`asoctl clean crds`]( {{< relref "asoctl#clean-crds" >}} ) does the cleanup required to ensure the upgrade from `v2.0.0-beta.5` to `v2.0.0` goes smoothly.
weight: -50# This should be 5 lower than the previous breaking change document
5
+
---
6
+
## Breaking changes
7
+
8
+
Improvements to our code generator have resulted in some properties now being more tightly validated, with better alignment to the requirements of the associated Azure resources.
9
+
10
+
Some invalid resources that were previously accepted by ASO only to fail when reconciled will now be rejected up front. Valid resources will be unaffected.
0 commit comments