Azure’s approach to versioning and avoiding breaking changes
Azure’s approach to versioning and avoiding breaking changes
Azure is dedicated to avoiding “breaking changes”—changes in service behavior that result in failures or unexpected behavior in production customer applications. Azure has developed detailed policy for allowed changes in service interfaces and behavior and a process for enforcing these guidelines. We recently published an overview of this policy in the Azure Developer Center on Microsoft Learn. This blog post explores the philosophy of the Azure Breaking Change policy and the process and tools we use to ensure that it’s followed.
Versioning and compatibility in Azure
A key concern in software versioning is backward compatibility. A software system is backward compatible if it accepts and processes any input from a prior version in a “compatible” way. Here, the term “compatible” generally means to preserve the essential function, possibly with some improvements. Backward compatibility is desirable because it allows users to easily obtain the benefits from a new version of the software.
Azure is committed to providing dependable and backward-compatible versioning of Azure services. Azure’s policy on versioning and breaking changes rests on these principles:
- Production customer workloads must not break due to a service change.
- Customers can adopt a new API version without requiring any code changes.
Azure has established policies, process, and tooling to achieve these objectives.
Azure versioning and breaking change policy
All Azure services allow customers to specify an API version when making requests to the service, usually with a query parameter named api-version. The value of this parameter specifies or contains a date in “YYYY-MM-DD” format that roughly indicates the date when the API version was introduced. Azure services may release “preview” versions, which are intended to be used for testing and feedback before the generally available (GA) version is released. Preview versions have an API version with the -preview suffix.
Azure has a Versioning and Breaking Change policy that defines the goals and requirements for versioning of Azure services. The essence of this policy is that the API version of a service is a contract that completely defines the behavior of the service. Any change of behavior requires a change in the API version. The policy defines specific changes in service behavior that are considered breaking changes that are to be avoided whenever possible. The Azure Breaking Changes Review Board reviews all service changes that could potentially disrupt customer workloads.
Breaking changes to GA services are strongly discouraged, but may be necessary to address security, compliance, or legal requirements. In rare occasions, a breaking change may be allowed for a necessary architectural change to enable new customer-requested features. Customers must be notified of these changes and are typically given three years to migrate their applications from the prior version before it’s retired.
Treatment for “preview” services is more lenient, since the intent of previews is to adapt to customer feedback and make breaking changes before GA. Customers are expected to migrate off a preview version within 90 days of the availability of a new preview or GA version.
Breaking changes process
All Azure services publish their REST API definition to the azure-rest-api-specs GitHub repo. Pull requests (PRs) to this repo are checked (using tooling described in the next section) for compliance with the Versioning and Breaking Change policy. If any issues are found, the PR can’t be merged without approval from the Breaking Change Review Board.
The Review Board holds office hours every week to review pending changes. Service teams attend these meetings to discuss the proposed changes and typically the Board recommends alternative designs that preserve behavior for current customers. Occasionally, a service team makes changes to the REST API definition to add missing information or correct details that aren’t consistent with actual service implementation. These changes are permitted, as they aren’t changes in service behavior.
In rare cases, a service needs to introduce a change that impacts current users, either because of security exposures or because all the alternative approaches aren’t feasible. In these cases, the prior version of the service is formally “retired”. The retirement process involves notification of all affected customers, a retirement notice published on Azure Updates. Following customer notification, the service continues to remain available, typically for three years, for customers to migrate from the prior version to the new version. The migration period may be shorter for changes that fix security, compliance, or legal vulnerabilities.
Breaking changes tooling
The primary tool for detecting breaking changes is azure-openapi-diff, which compares two REST API definitions and flags any differences that might be breaking changes by applying the BreakingChangeReviewRequired label to the PR. Azure employs many “specification extensions” and azure-openapi-diff checks for differences in these extensions as well. There are currently 47 different types of changes that azure-openapi-diff detects. Some changes are considered breaking changes and raise errors; other changes are flagged with the NewApiVersionRequired label if made without updating the API version.
The azure-rest-api-specs repo is configured to run azure-openapi-diff to compare the changes in the PR against the most recent GA version, if there’s one, and the most recent preview version, again if there’s one. Any issues detected in the PR are flagged for breaking change review. PRs with breaking changes are blocked from merging until the Review Board has applied the Approved-BreakingChange label.
Continuous improvement
Azure makes a significant investment in avoiding customer disruption from breaking changes, but there’s still room for improvement. One area for improvement is finding and correcting errors or omissions in a service’s REST API definition before it’s published. We’re attacking this problem by monitoring live traffic for some services while they’re still in preview and checking this traffic against the REST API definition. We’re hoping to expand live traffic validation to more services and complement it with active testing of the API definition as part of the CI process for the azure-rest-api-specs repo.
Summary
Versioning is an essential tool for protecting customers from breaking changes in Azure services. Azure has established a versioning policy, backed by process and tooling, to minimize customer disruption from breaking changes. Azure’s versioning policy allows customers to use Azure services with confidence that service changes won’t disrupt their workloads.
Mike Kistler Principal Program Manager, Azure SDK
Light
Dark
0 comments