Enable RPs & users to announce upcoming changes

[AlexanderSehr]

I was unable to find any related issue, so here it goes:

I'd like to request a feature to enable users (and ideally also the Azure Resource Providers) to issue warnings about upcoming changes. The idea would be that you deploy a template (for example DiagnosticSettings as a very recent example) and because of either something configured somewhere by the PG, or maybe the original creator of the template, a warning should show up in the logs during the deployment of the template.

This could look similar to how it is done in

• Terraform: source
  
• PowerShell: source

  WARNING: Set-AzureRmVMBootDiagnostics: A property of the output of this cmdlet will change in an upcoming breaking change release. The StorageAccountType property for a DataDisk will return Standard_LRS and Premium_LRS

• Azure CLI: source
  

I could see this being quite useful also for, for example, the Public Bicep Registry, or any Solution Maintainer, to notify consumers of changes ahead of time - simply by showing them custom messages in the log.

I'm aware that I'm essentially asking for 2 things here:

• Enable template creators to embedd info messages in their templates that show up during deployments
• Enable RPs to issue warnings of upcoming changes that show up during deployments

Having the first would already be great. The second then the icing on the cake - especially in response to those aformentioned changes in the backend with the diagnostic settings which all of a sudden started breaking all over the place if you didn't happen to read about the change in the docs ahead of time.

[jeskew]

Thanks for the suggestion, @AlexanderSehr! I think this could be really useful, although I think the Terraform example you include is closer to what we would support than the az CLI or PS module examples are.

For template authors, we could support some way to mark a parameter, an output, or a type property as deprecated, potentially including a custom deprecation message. If a consumer of the template supplied a value for a deprecated parameter (or property) or accessed a deprecated output (or property), a warning could be surfaced:

module.bicep

@deprecated('Use \'name\' property of storageAccountConfig param instead')
param storageAccountName string?

param storageAccountConfig {
  name: string?

  @deprecated('This was a typo')
  namme: string?
}

resource sa 'Microsoft.Storage/storageAccounts@<api version>' existing = {
  name: (storageAccountConfig.?name ?? storageAccountConfig.?namme ?? storageAccountName)!
}

@deprecated('This output field will be removed in a future version of this module')
output foo string = <value>

main.bicep

module mod 'mod.bicep' = {
  name: 'mod'
  params: {
    storageAccountName: 'foo'             // <-- Would raise warning diagnostic with custom deprecation message
    storageAccountConfig: {
      namme: 'foo'                        // <-- Would raise warning diagnostic with custom deprecation message
      name: 'foo'
    }
  }
}

outputs modFoo string = mod.outputs.foo   // <-- Would raise warning diagnostic with custom deprecation message

We would only be able to do something similar for RPs if deprecation information is captured in providers' service models. It appears that field-level deprecated traits are only supported in OpenAPI 3.0+, and I believe most RP service models adhere to the Swagger 2.0 spec. I can check around to see if there are any Swagger extensions we could look for instead. But even OpenAPI 3.0 only appears to support a boolean deprecated trait, so there may not be any way for RP teams to provide custom deprecation messages.

[anthony-c-martin]

We would only be able to do something similar for RPs if deprecation information is captured in providers' service models. It appears that field-level deprecated traits are only supported in OpenAPI 3.0+, and I believe most RP service models adhere to the Swagger 2.0 spec. I can check around to see if there are any Swagger extensions we could look for instead. But even OpenAPI 3.0 only appears to support a boolean deprecated trait, so there may not be any way for RP teams to provide custom deprecation messages.

FWIW it feels to me like 'deprecated' fields goes against the current design principals for Azure APIs. Rather than supporting 2 ways of doing things on a single API version, RPs tend to just use API versions to "safely" introduce breaking changes.

[AlexanderSehr]

We would only be able to do something similar for RPs if deprecation information is captured in providers' service models. It appears that field-level deprecated traits are only supported in OpenAPI 3.0+, and I believe most RP service models adhere to the Swagger 2.0 spec. I can check around to see if there are any Swagger extensions we could look for instead. But even OpenAPI 3.0 only appears to support a boolean deprecated trait, so there may not be any way for RP teams to provide custom deprecation messages.

FWIW it feels to me like 'deprecated' fields goes against the current design principals for Azure APIs. Rather than supporting 2 ways of doing things on a single API version, RPs tend to just use API versions to "safely" introduce breaking changes.

One would think so @anthony-c-martin, and every now and then you have cases such as the Diagnostic Settings Retention Policy (where they deprecated the feature across the board even a month before the announced schedule) or the Azure Purview Service (where all of a sudden the support for any location but the US was scrapped). 🤔
But overall I agree, why else have Api versions if you (usually) cannot rely on a stable support.

In any case, the ability to announce upcoming changes for future versions would help RP users too, not to speak of the other suggested feature, that is, to enable the template author to do the same. Like in case of [CARML] (aka.ms/carml) it would have been great to use that feature as a means to announce it's upcoming migration the the Puic Bicep Registry (which is a accompanied by a landslide of breaking changes we try to be as visual about a possible).

[jeskew]

@anthony-c-martin I did find several usages of "deprecated" in RP models, though it is only used as a trait on operations rather than on individual fields. Autorest does support the "deprecated" trait on fields and parameters, but it looks like no RPs are using it.

[jeskew]

There is an open issue for adding a @deprecated() decorator: #3505