Microsoft Azure Storage Service Version Removal Update: Extension to 2016

Summary

The Storage Service uses versioning to govern what operations are available, how a given request will be processed and what will be returned. In 2014, we announced that specific versions of the Microsoft Azure Storage Service would be removed on December 9^th, 2015. Based on your feedback, we are now making the following changes with the details in the table below.

1. We will delay the removal date for some REST API versions and impacted client libraries. This includes all REST endpoints starting version 2009-07-17 and earlier. The effective date for this service removal is August 1^st, 2016.
2. We will indefinitely postpone the removal date for the endpoints 2011-08-18 and 2009-09-19. This is effective immediately. We intend to remove these versions at some point in the future, but not within the coming 12 months. The exact date of removal will be communicated via this blog forum and with 12 months’ notice provided.
3. We will begin using service version 2014-04-05 for requests that do not include a specific version for SAS authentication and Anonymous access. However, we will begin rejecting any unversioned SharedKey/SharedKeyLite authenticated requests. The effective date for this is August 1^st, 2016.
4. Finally, there is no change to support level and availability of versions 2012-02-12 and beyond.

Please plan and implement your application upgrades soon so you are not impacted when service versions are removed. Additionally, we encourage you to regularly update to the latest service version and client libraries so you get the benefit of the latest features. To understand the details of how this will impact you and what you need to do, please read on.

How will these changes manifest?

Explicitly Versioned Requests

Any requests which are explicitly versioned using the HTTP x-ms-version request header set to one of the removed versions or in the case of SAS requests api-version parameter set to one of the removed versions, will fail with an HTTP 400 (Bad Request) status code, similar to any request made with an invalid version header.

SharedKey/SharedKeyLite Requests with no explicit version

For requests that were signed using the account’s shared key, if no explicit version is specified using HTTP x-ms-version, the request was previously processed with the undocumented 2008 version. Going forward, processing will fail with HTTP 400 (Bad Request) if the version is not explicitly specified.

SAS Requests with no “sv” parameter and no “x-ms-version”

Prior to version 2012-02-12, a SAS request did not specify a version in the “sv” parameter of the SAS token. The SAS token parameters of these requests were interpreted using the rules for the 2009-07-17 REST processing version. These requests will still work, but now the request will be processed with 2015-04-05 version. We advise you in this case to ensure that you either send “x-ms-version” with a non-deprecated version or set a default version on your account.

Anonymous Requests with no explicit version

For any anonymous requests (with no authentication) with no version specified, the service assumes that the request is version agnostic. Effective August 1st 2016, anonymous requests will be processed with version 2015-04-05. The version used for anonymous requests may change again in the future.

Note that we make no guarantees about whether or not there will be breaking changes when unversioned requests are processed with a new service version. Instances of these requests include browser-initiated HTTP requests and HTTP requests without the service version specified that are made from applications not using Storage client libraries. If your application is unable to send an x-ms-version for anonymous requests (for example, from a browser), then you can set a default REST version for your account through Set Blob Service Properties, for the Blob service for instance.

Default Service Version

If Set Blob Service Properties (REST API) has been used to set the default version of requests to version 2009-09-19 or higher, the version set will be used. If default service version was set to a version that is now removed, that request is considered to be explicitly versioned, and will fail with “400 Bad Request”. If default service version was set to a version that is still supported, that version will continue to be used.

Client Libraries

The latest versions of all of our client libraries and tools will not be affected by this announcement. However the .Net client library v1.5.1 uses Version 2009-09-19 and will be impacted when that version is eventually removed. If you are still using this library, please update to the latest .Net client library before the version is removed. For a list of .Net client libraries using various REST endpoints, please visit https://msdn.microsoft.com/en-us/library/azure/dn744252.aspx. If you are using non-.Net libraries, then you should not be impacted. For more information, please look at the at the Minimum Supported Versions/Libraries/SDK’s section in this article.

Azure CloudDrive

If you are using Azure CloudDrive, then you are not impacted by this announcement since it uses REST Version 2009-09-19. We will have an announcement in the near future on CloudDrive migration.

What should I do?

To ensure that your application continues to work properly after removal of older versions, you should do the following things.

Check your application to find what versions it is using

The first thing to do is to determine what REST versions your application is using. If your application is under your control and you are aware of all components that call Azure Storage, then you can verify this by checking the components against the above list, or by inspecting your code if you have written your own code to make calls to storage.

As a stronger check, or if you are unsure which versions of the components have been deployed, you can enable logging, which will log the requests being made to your storage account. The logs have the request version used included, which can be used to find if any requests are being made using versions with planned removal.

Here is a sample log entry, with the version used highlighted in red – in this case the request was an anonymous and unversioned GetBlob request which implicitly used the 2009-09-19 version:

1.0;2011-08-09T18:52:40.9241789Z;GetBlob;AnonymousSuccess;200;18;10;anonymous;;myaccount;blob;"https:// myaccount.blob.core.windows.net/thumbnails/lake.jpg?timeout=30000";"/myaccount/thumbnails/lake.jpg";a84aa705-8a85-48c5-b064-b43bd22979c3;0;123.100.2.10;2009-09-19;252;0;265;100;0;;;"0x8CE1B6EA95033D5";Friday, 09-Aug-11 18:52:40 GMT;;;;"8/9/2011 6:52:40 PM ba98eb12-700b-4d53-9230-33a3330571fc"

Similar to the above, you can look at log entries to identify any references to service versions that are being removed.

What to change

If you find any log entries which show that a version to be removed is being used, you will need to find that component and either validate that it will continue to work (unversioned requests may continue to work as their implicit version will simply increase – see above), or take appropriate steps to change the version being used. Most commonly, one of the following two steps will be used:

1. Change the version specified in the request. If you are using client libraries, you can accomplish this by migrating to a later version of the libraries/tools. When possible, migrate to the latest version to get the most improvements and fixes.
2. Set the default service version to one of the supported versions now so that the behavior can be verified prior to removal. This only applies to anonymous requests with no explicit version.

When migrating your applications to newer versions, you should review the above linked change lists for each service version and test thoroughly to ensure that your application is working properly after you’ve updated it. Please note that service version updates have included both included syntactic breaks (the request will receive a response that either is a failure or formed very differently) and semantic breaks (the request will receive a similar response that means something different).

Post migration validation

After migration, you should validate in the logs that you do not find any of the earlier versions being used. Make sure to check the logs over long enough durations of time to be sure that there are no tasks/workloads running rarely that would still use the older versions (scheduled tasks that run once per day, for example).

Conclusion

It is recommended that users begin their applications upgrades now in order to avoid being impacted when the earlier service versions are removed on August 1^st, 2016. Additionally, it is considered a best practice to explicitly version all requests made to the storage service. See MSDN for a discussion of versioning in Azure Storage and best practices.

Thank you.

Dinesh Murthy
Principal Program Manager
Microsoft Azure Storage