Specify custom API version on resources

[danielrbradley]

Hello!

• Vote on this issue by adding a 👍 reaction
• If you want to implement this feature, comment to let us know (we'll work with you on design, scheduling, etc.)

Issue details

In version 2 of the provider we're removing selected resources to reduce SDK size where the next version of the resource is compatible with the previous verion. In theory API behaviour can vary between versions and a user might want to use a specific version.

To ensure that the provider allows a user to interact with the full Azure surface area, we could add a string ApiVersion field to all resources which would allow the same SDK class to be used with other versions.

Initially this could be just a string field but could also be implemented to include an enum of known versions for that resource.

If the user specifies an invalid API version or a version that's incompatible with the resources shape of the SDK resource class then errors would just be propegated by the Azure API - we would not validate this. We could also consider disabling validation of properties if the version is specified in case transformations are also being used to manipulate the shape of the payload.

Affected area/feature

• Schema generation
• Provider

Use cases

• Using workload profiles with ManagedEnvironment throws error code "WorkloadProfileRelatedApiNotSupported" #2667
• Migration azure-native to v2 leads to ManagedCluster replacing #2669

[thomas11]

resolves #1877

[danielrbradley]

@thomas11 I don't think this does solve the specific use case in #1877 - that is for resources which don't exist in any way in the SDK rather than a different version of an existing resource.

[thomas11]

@danielrbradley the "resource doesn't exist in the SDK" case is covered by #68. Whereas #1877 is explicitly about API versions - although the semantics of the use case may differ. We should clarify this.

[danielrbradley]

@thomas11 ah yes your right - custom resource providers meaning API versions we don't support.

[danielrbradley]

Discussion points with @mikhailshilkov

1. Consider property naming to make it clear it's an "escape hatch". E.g. OverrideApiVersion
2. Add to the 2.0 migration guide for maintaining any v1 resource versions.
3. Add to the provider documentation to explain how it works & what it's for. Include details about using transformations to modify payload if required.