ARM API version linter: prevent preview API from being used in azurerm#30612
Merged
catriona-m merged 14 commits intohashicorp:mainfrom Dec 15, 2025
Merged
ARM API version linter: prevent preview API from being used in azurerm#30612catriona-m merged 14 commits intohashicorp:mainfrom
catriona-m merged 14 commits intohashicorp:mainfrom
Conversation
| # - module: github.com/hashicorp/go-azure-sdk/resource-manager | ||
| # service: compute | ||
| # version: 2021-06-01-preview | ||
| # stableVersionTargetDate: 2026-01-01 |
Collaborator
There was a problem hiding this comment.
suggest stating stableVersionTargetDate as optional as there would be cases the preview API promoter could provide justifications to enroll preview API but their team has no clear plan to release stable. In addition, there might be further justifications as "our preview API would always be of prod SLA, so there is no need to wait our stable API."
Collaborator
Author
There was a problem hiding this comment.
We actually want a commitment to release stable version in the future. See the argument at the beginning of guide-api-version.md about automated breaking change checks. If this is bypassed, the API is always at risk of breaking change that severely impacts azurerm users. Such bypass should only be on temporary basis.
| # service: compute | ||
| # version: 2021-06-01-preview | ||
| # stableVersionTargetDate: 2026-01-01 | ||
| # responsibleIndividual: github.com/gerrytan |
Collaborator
There was a problem hiding this comment.
As for the responsibleIndividual:
- Assume it should be one of the API owner team, and let them know they are expected to sign on AzureRM repo here towards their justification on their preview API is ok to use
- There might be exception on privacy say the API owner is not willing to expose their GH handles. While, we can start by this and see how it's going to work.
Collaborator
Author
There was a problem hiding this comment.
GH profile URL is always public in nature, and individuals can always fine-tune the GitHub privacy setting to expose / hide certain informations. The concept of ownership is important so we know who to contact / follow up to 2-3 months in the future if the needs arise.
|
|
||
| Provider logic should be implemented using stable Azure Resource Manager (ARM) API version. Preview versions are prone to breaking changes which results in very poor azurerm user experience (eg: removed property). There are [automated checks on azure-rest-api-specs that prevents breaking changes against stable version](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/ci-fix.md#sdk-breaking-change-review). Such checks are not applicable to preview versions. | ||
|
|
||
| Breaking API changes often materialise into [azurerm breaking change](guide-breaking-changes.md) which involves non-trivial upgrade steps and long major version release wait time. v3.0.0 was released in March 2022 and v4.0.0 in August 2024. |
Collaborator
There was a problem hiding this comment.
Suggest not mentioning this concrete v3.0 -> v4.0 example, because breaking api changes brought by preview API could be part of the reason that increases the duration between major versions, but it does not constitute the decisive factor. Mentioning the v3.0 -> v4.0 example implies its duration was due to breaking api changes brought by preview API.
Collaborator
Author
There was a problem hiding this comment.
Mentioning v3 -> v4 timeline here is only to highlight the potential user pain if a major version breaking change occur. While I understand it's not necessarily the future schedule going forward, it is a historical fact that can be viewed simply from the repository releases section.
Contributor
|
This PR is being labeled as "stale" because it has not been updated for 30 or more days. If this PR is still valid, please remove the "stale" label. If this PR is blocked, please add it to the "Blocked" milestone. If you need some help completing this PR, please leave a comment letting us know. Thank you! |
katbyte
requested changes
Oct 23, 2025
| @@ -0,0 +1,53 @@ | |||
| # Guide: ARM API Version | |||
Collaborator
There was a problem hiding this comment.
Suggested change
| # Guide: ARM API Version | |
| # Guide: ARM API Versions |
| @@ -0,0 +1,53 @@ | |||
| # Guide: ARM API Version | |||
|
|
|||
| Provider logic should be implemented using stable Azure Resource Manager (ARM) API version. Preview versions are prone to breaking changes which results in very poor azurerm user experience (eg: removed property). There are [automated checks on azure-rest-api-specs that prevents breaking changes against stable version](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/ci-fix.md#sdk-breaking-change-review). Such checks are not applicable to preview versions. | |||
Collaborator
There was a problem hiding this comment.
Suggested change
| Provider logic should be implemented using stable Azure Resource Manager (ARM) API version. Preview versions are prone to breaking changes which results in very poor azurerm user experience (eg: removed property). There are [automated checks on azure-rest-api-specs that prevents breaking changes against stable version](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/ci-fix.md#sdk-breaking-change-review). Such checks are not applicable to preview versions. | |
| The provider should be implemented using stable Azure Resource Manager (ARM) API/SDK version. Preview versions are prone to sudden breaking changes which can result in a less then ideal user experience (eg: removed property or behavioural change). There are [automated checks on azure-rest-api-specs that prevents breaking changes against stable version](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/ci-fix.md#sdk-breaking-change-review) but they do not catch everything and are not applicable to preview versions. |
|
|
||
| Provider logic should be implemented using stable Azure Resource Manager (ARM) API version. Preview versions are prone to breaking changes which results in very poor azurerm user experience (eg: removed property). There are [automated checks on azure-rest-api-specs that prevents breaking changes against stable version](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/ci-fix.md#sdk-breaking-change-review). Such checks are not applicable to preview versions. | ||
|
|
||
| Breaking API changes often materialise into [azurerm breaking change](guide-breaking-changes.md) which involves non-trivial upgrade steps and long major version release wait time. v3.0.0 was released in March 2022 and v4.0.0 in August 2024. |
Collaborator
There was a problem hiding this comment.
Suggested change
| Breaking API changes often materialise into [azurerm breaking change](guide-breaking-changes.md) which involves non-trivial upgrade steps and long major version release wait time. v3.0.0 was released in March 2022 and v4.0.0 in August 2024. | |
| These breaking API changes often materialise into [breaking changes](guide-breaking-changes.md) which can involve non-trivial upgrade steps and/or require waiting till a major version release to make the breaking change. v3.0.0 was released in March 2022 and v4.0.0 in August 2024. |
|
|
||
| Breaking API changes often materialise into [azurerm breaking change](guide-breaking-changes.md) which involves non-trivial upgrade steps and long major version release wait time. v3.0.0 was released in March 2022 and v4.0.0 in August 2024. | ||
|
|
||
| Day-0 Terraform support for preview API should be done via [azapi provider](https://registry.terraform.io/providers/Azure/azapi/latest/docs) where users have full control of API version choice. |
Collaborator
There was a problem hiding this comment.
Suggested change
| Day-0 Terraform support for preview API should be done via [azapi provider](https://registry.terraform.io/providers/Azure/azapi/latest/docs) where users have full control of API version choice. | |
| Day-0 Terraform support for preview APIs can be done via [azapi provider](https://registry.terraform.io/providers/Azure/azapi/latest/docs) where users have full control of API version choice. |
| ## Obtaining exception to use preview API | ||
|
|
||
| > [!WARNING] | ||
| > preview API version usage is risky, prone to human error and can result in very poor azurerm user experience. Add an exception as a last resort only when all the consequences are fully understood. |
Collaborator
There was a problem hiding this comment.
Suggested change
| > preview API version usage is risky, prone to human error and can result in very poor azurerm user experience. Add an exception as a last resort only when all the consequences are fully understood. | |
| > using a preview API version can be risky, prone to human error, and can result in a substandard user experience. An exception is a last resort only when all the consequences are fully understood and there is no alternitive. |
Comment on lines
+26
to
+30
| 1. There is a clear business reason for not using stable API version, for example: reputational damage to Microsoft / Azure because azurerm Terraform support for the feature cannot be provided in time to meet customers' expectation and azapi support is insufficient | ||
| 1. Guarantee that no breaking change will be made to the relevant preview API that could negatively impact azurerm users | ||
| 1. There is a commitment to release a stable API version in the near future, a specific target date has to be set | ||
| 1. There is a responsible individual with deep knowledge of the API that can be contacted in the future if required | ||
| 1. There is an agreement between Microsoft and Hashicorp that the exception is appropriate |
Collaborator
There was a problem hiding this comment.
Suggested change
| 1. There is a clear business reason for not using stable API version, for example: reputational damage to Microsoft / Azure because azurerm Terraform support for the feature cannot be provided in time to meet customers' expectation and azapi support is insufficient | |
| 1. Guarantee that no breaking change will be made to the relevant preview API that could negatively impact azurerm users | |
| 1. There is a commitment to release a stable API version in the near future, a specific target date has to be set | |
| 1. There is a responsible individual with deep knowledge of the API that can be contacted in the future if required | |
| 1. There is an agreement between Microsoft and Hashicorp that the exception is appropriate | |
| 1. There is a clear and compelling reason for not using a stable API version. For example: the fix for a critical security vulnerability or impactful bug is only available in a the preview version. | |
| 1. There is a commitment from the service that no breaking changes will be made to the relevant preview API that could negatively impact azurerm users. | |
| 1. There is a commitment from the service team to release a stable API version in the near future, a specific target date has to be set. | |
| 1. There is a responsible individual with deep knowledge of the API that can be contacted in the future if required. | |
| 1. There is an agreement between Microsoft and Hashicorp that the exception is appropriate. |
| @@ -0,0 +1,117 @@ | |||
| package main | |||
Collaborator
There was a problem hiding this comment.
i might want to make this tool something more explicit like preview-api-version-lint[er] so its more descriptive in it focuses on preview apis
Collaborator
Author
|
Thank you for reviewing @katbyte , all comments have been addressed. Have also merged latest main and checked the GH workflow passes. |
catriona-m
requested changes
Nov 6, 2025
Member
catriona-m
left a comment
catriona-m
left a comment
There was a problem hiding this comment.
Hi @gerrytan thanks for working on this, I left a few suggestions inline for you to consider, but then I can take another look. Thanks!
| @@ -0,0 +1,53 @@ | |||
| # Guide: ARM API Versions | |||
|
|
|||
| The provider should be implemented using stable Azure Resource Manager (ARM) API/SDK version. Preview versions are prone to sudden breaking changes which can result in a less then ideal user experience (eg: removed property or behavioural change). There are [automated checks on azure-rest-api-specs that prevents breaking changes against stable version](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/ci-fix.md#sdk-breaking-change-review) but they do not catch everything and are not applicable to preview versions. | |||
Member
There was a problem hiding this comment.
Suggested change
| The provider should be implemented using stable Azure Resource Manager (ARM) API/SDK version. Preview versions are prone to sudden breaking changes which can result in a less then ideal user experience (eg: removed property or behavioural change). There are [automated checks on azure-rest-api-specs that prevents breaking changes against stable version](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/ci-fix.md#sdk-breaking-change-review) but they do not catch everything and are not applicable to preview versions. | |
| The provider should be implemented using stable Azure Resource Manager (ARM) API/SDK version. Preview versions are prone to sudden breaking changes which can result in a less than ideal user experience (eg: removed property or behavioural change). There are [automated checks on azure-rest-api-specs that prevents breaking changes against stable version](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/ci-fix.md#sdk-breaking-change-review) but they do not catch everything and are not applicable to preview versions. |
|
|
||
| These breaking API changes often materialise into [breaking changes](guide-breaking-changes.md) which can involve non-trivial upgrade steps and/or require waiting till a major version release to make the breaking change. v3.0.0 was released in March 2022 and v4.0.0 in August 2024. | ||
|
|
||
| Day-0 Terraform support for preview APIs can be done via [azapi provider](https://registry.terraform.io/providers/Azure/azapi/latest/docs) where users have full control of API version choice. |
Member
There was a problem hiding this comment.
Suggested change
| Day-0 Terraform support for preview APIs can be done via [azapi provider](https://registry.terraform.io/providers/Azure/azapi/latest/docs) where users have full control of API version choice. |
it would be good to focus on the do's/don'ts of preview versions in the provider for this guide, rather than making further recommendations that are outside of the provider
|
|
||
| Day-0 Terraform support for preview APIs can be done via [azapi provider](https://registry.terraform.io/providers/Azure/azapi/latest/docs) where users have full control of API version choice. | ||
|
|
||
| In October 2025 we implemented an API version check on PRs that prevents the use of preview versions. All historical usages of preview versions have been allow-listed as exceptions. See `internal/tools/preview-api-version-linter` for the implementation details. |
Member
There was a problem hiding this comment.
Suggested change
| In October 2025 we implemented an API version check on PRs that prevents the use of preview versions. All historical usages of preview versions have been allow-listed as exceptions. See `internal/tools/preview-api-version-linter` for the implementation details. | |
| In November 2025 we implemented an API version check on PRs that prevents the use of preview versions. All historical usages of preview versions have been allow-listed as exceptions. See `internal/tools/preview-api-version-linter` for the implementation details. |
| ## Obtaining exception to use preview API | ||
|
|
||
| > [!WARNING] | ||
| > using a preview API version can be risky, prone to human error, and can result in a substandard user experience. An exception is a last resort only when all the consequences are fully understood and there is no alternative. |
Member
There was a problem hiding this comment.
Suggested change
| > using a preview API version can be risky, prone to human error, and can result in a substandard user experience. An exception is a last resort only when all the consequences are fully understood and there is no alternative. | |
| > Using a preview API version can be risky, prone to human error, and can result in a substandard user experience. An exception is a last resort only when all the consequences are fully understood and there is no alternative. |
| > [!WARNING] | ||
| > using a preview API version can be risky, prone to human error, and can result in a substandard user experience. An exception is a last resort only when all the consequences are fully understood and there is no alternative. | ||
|
|
||
| To add an exception to use preview API version, following criteria must be met: |
Member
There was a problem hiding this comment.
Suggested change
| To add an exception to use preview API version, following criteria must be met: | |
| To add an exception to use preview API version, the following criteria must be met: |
|
|
||
| To add an exception to use preview API version, following criteria must be met: | ||
|
|
||
| 1. There is a clear and compelling reason for not using a stable API version. For example: the fix for a critical security vulnerability or impactful bug is only available in a the preview version. |
Member
There was a problem hiding this comment.
Suggested change
| 1. There is a clear and compelling reason for not using a stable API version. For example: the fix for a critical security vulnerability or impactful bug is only available in a the preview version. | |
| 1. There is a clear and compelling reason for not using a stable API version. For example: the fix for a critical security vulnerability or impactful bug is only available in the preview version. |
| 1. There is an agreement between Microsoft and Hashicorp that the exception is appropriate. | ||
|
|
||
| > [!NOTE] | ||
| > Feature being in preview phase is not a sufficient reason to add this exception. The concept of preview should be decoupled between feature and ARM API. It is okay to leave the feature in preview phase while having the API promoted to stable. This will safeguard the API against breaking changes and ensure azurerm support for the feature can be shipped sooner to customers. Otherwise Terraform support for the feature should be provided via azapi. |
Member
There was a problem hiding this comment.
Suggested change
| > Feature being in preview phase is not a sufficient reason to add this exception. The concept of preview should be decoupled between feature and ARM API. It is okay to leave the feature in preview phase while having the API promoted to stable. This will safeguard the API against breaking changes and ensure azurerm support for the feature can be shipped sooner to customers. Otherwise Terraform support for the feature should be provided via azapi. | |
| > A feature being in preview phase is not a sufficient reason to add this exception. The concept of preview should be decoupled between feature and ARM API. It is okay to leave the feature in preview phase while having the API promoted to stable. This will safeguard the API against breaking changes and ensure azurerm support for the feature can be shipped sooner to customers. |
|
|
||
| - module: github.com/Azure/azure-sdk-for-go | ||
| service: resources | ||
| version: 2021-06-01-preview |
Member
There was a problem hiding this comment.
should we consider narrowing this down by packages or resources as well? having this scoped at the version could mean someone could use a preview api that is already in use the service, but for a different resource
Collaborator
Author
There was a problem hiding this comment.
Hi @catriona-m the current scoping / granularity should be sufficient:
- Including the resource will increase the permutation, causing a very large allowlist / exception file, making it hard to maintain
- True that further use of allow-listed preview API is harder to prevent, have to rely on PR review, but at the same time with this process the responsible individual from service team (someone with deep expertise of the API) would have already sign off the exemption and should be fully aware of the breaking change risk and consequences
|
|
||
| The provider should be implemented using stable Azure Resource Manager (ARM) API/SDK version. Preview versions are prone to sudden breaking changes which can result in a less then ideal user experience (eg: removed property or behavioural change). There are [automated checks on azure-rest-api-specs that prevents breaking changes against stable version](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/ci-fix.md#sdk-breaking-change-review) but they do not catch everything and are not applicable to preview versions. | ||
|
|
||
| These breaking API changes often materialise into [breaking changes](guide-breaking-changes.md) which can involve non-trivial upgrade steps and/or require waiting till a major version release to make the breaking change. v3.0.0 was released in March 2022 and v4.0.0 in August 2024. |
Member
There was a problem hiding this comment.
Suggested change
| These breaking API changes often materialise into [breaking changes](guide-breaking-changes.md) which can involve non-trivial upgrade steps and/or require waiting till a major version release to make the breaking change. v3.0.0 was released in March 2022 and v4.0.0 in August 2024. | |
| These breaking API changes often materialise into [breaking changes](guide-breaking-changes.md) which can involve non-trivial upgrade steps and/or require waiting until a major version release to make the breaking change. v3.0.0 was released in March 2022 and v4.0.0 in August 2024. |
Collaborator
Author
|
Thank you @catriona-m , I have addressed all the feedbacks. Also have merged latest main and rerun the linter test. Can you please have another look 🙏. 
|
catriona-m
requested changes
Dec 12, 2025
Member
catriona-m
left a comment
catriona-m
left a comment
There was a problem hiding this comment.
Thanks @gerrytan I just spotted one typo but once that's fixed this should be good to go.
| fmt.Fprintf(os.Stderr, "%s\n", v) | ||
| } | ||
| fmt.Fprintf(os.Stderr, ` | ||
| Preview versions are prone to sudden breaking changes which can result in a less then ideal user experience, |
Member
There was a problem hiding this comment.
Suggested change
| Preview versions are prone to sudden breaking changes which can result in a less then ideal user experience, | |
| Preview versions are prone to sudden breaking changes which can result in a less than ideal user experience, |
Collaborator
Author
There was a problem hiding this comment.
Oops, thank you @catriona-m , I have pushed a fix for this
Collaborator
Author
|
@catriona-m this PR is ready for you to take another look. I have addressed all feedbacks, merged latest main and fixed linter errors. |
Collaborator
Author
|
Thank you @catriona-m ! |
Contributor
|
I'm going to lock this pull request because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active contributions. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Community Note
Description
Usage of preview ARM API version is a big grey area. This PR adds a new linter "ARM API Version Linting" that prevents preview API from being imported. It does so by scanning the vendor folder for 3 piece of information: go modules name + service + version string.
The linter is invoked when PRs are opened / new commits pushed on the PR.
Historical use of preview APIs are allowlisted in
historical-exceptions.yml.A documentation to educate users on the consequences of preview API, and also process to obtain new exceptions has been added, see guide-api-version.md
With this process contributors will be more informed about risks and consequences of preview API and increased transparency on why a specific preview API was used.
See below example of a PR that fails the linter checks:
https://github.com/hashicorp/terraform-provider-azurerm/actions/runs/17665781010/job/50207049336
PR Checklist
For example: “
resource_name_here- description of change e.g. adding propertynew_property_name_here”Changes to existing Resource / Data Source
(For changes that include a state migration only). I have manually tested the migration path between relevant versions of the provider.Testing
Change Log
Below please provide what should go into the changelog (if anything) conforming to the Changelog Format documented here.
No azurerm user facing changes
This is a (please select all that apply):
Related Issue(s)
n/a
Rollback Plan
Disable the GitHub workflow "ARM API Version Linting" via UI
Changes to Security Controls
Are there any changes to security controls (access controls, encryption, logging) in this pull request? If so, explain.
Note
If this PR changes meaningfully during the course of review please update the title and description as required.