Breaking Behavioural Change in Cognitive Service

[tombuildsstuff]

👋

This upstream issue describes a breaking change in the Cognitive Services API: https://github.com/terraform-providers/terraform-provider-azurerm/issues/9102

If this functionality is being deprecated, shouldn't this be done in a new version of the API, with a published migration path ahead of time?

We've discovered this blog post published today, multiple hours after this breaking change occurred fwiw: https://azure.microsoft.com/en-us/updates/bing-search-apis-will-transition-from-azure-cognitive-services-to-azure-marketplace-on-31-october-2023/

Notably this is still published on the website, as if this functionality is still available: https://azure.microsoft.com/en-us/services/cognitive-services/bing-web-search-api/

cc @JeffreyRichter

[tombuildsstuff]

ping @fengzhou-msft

[ghost]

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @jaggerbodas-ms, @arwong.

[jaggerbodas-ms]

Hi @tombuildsstuff ,

As you have noted above, Bing Search Services are transitioned to Azure Marketplace. i.e. Post 10/30 provisioning new Bing resource via existing Cognitive Services methodologies will not work and customers can provision any new instances of Bing Search Services via Azure Marketplace. All the existing resources provisioned via the Azure Cognitive Services platform previously, will be supported till 31st Oct 2023 or till the end of a respective enterprise agreement.

This update was shared with the resource owners over email. However, due to some technical problems Azure Marketing Portal updates were delayed.

[tombuildsstuff]

@jaggerbodas-ms I can understand the need to deprecate functionality, but the issue here is this has been done as a breaking change.

An alternative approach, followed by other Azure API's, would be to introduce a new API version which removed support for this builder - and then push people across to the new one - whilst there's more complexity involved in doing so, this means that customers don't encounter a breaking change. For context, in this instance we've had a Github issue opened due to a customers production environment/scripts no longer working - so whilst there may have been an email sent here, what's the migration path for users, to down-tools and update their scripts with no notice?

From a technical perspective, I'd argue this is down to the API provisioning multiple different types of products from a single payload - so perhaps this API wants splitting apart so that it's possible to deprecate these in the future by dropping them from the next API Version - WDYT?

@JeffreyRichter for this one, is there some kind of documentation around deprecation policies? Removing functionality from an existing API version on a given date (particularly with no notice), is the kind of thing that's hard to plan for

Thanks!

[JeffreyRichter]

Yes, Azure has some documentation. Our policy is that a service can only make breaking changes after giving customers 3-years notice (1-year for a security/compliance related issues). Teams are adopting this policy now and some teams adopt it sooner than later. In other words, there is some transition time for some teams where it might not be happening this way immediately but this is the goal.

[tombuildsstuff]

@JeffreyRichter thanks for the link, unfortunately it appears that isn't public - is there a public reference for that document?

[JeffreyRichter]

Sorry, that document is not public. Unfortunately, I just learned that I'd have to run the document through legal in order to publish it publicly so that won't happen anytime soon. But we do have an internal document and it does state the 3-year breaking change notification policy.