如何使现有 ARM 模板上的资源 API 版本保持最新？

Question

我有一个现有的 Azure 模板，可以提供以下资源

Microsoft.ClassicStorage/StorageAccounts (api version 2014-06-01)
microsoft.insights/components (api version 2014-08-01)

还有一些人...

使用文章 Resource providers and types 中的代码，我发现我模板上的资源 API 版本落后了几个版本：

Microsoft.ClassicStorage/StorageAccounts. Current: 2014-06-01, available:

2016-11-01
2016-04-01
2015-12-01
2015-06-01
2014-06-01
2014-04-01-beta
2014-04-01
2014-01-01

microsoft.insights/components. Current: 2014-08-01, available:

2015-05-01
2014-12-01-preview
2014-08-01
2014-04-01

这是我的问题

在模板中维护资源 API 版本的最佳做法是什么？
我在哪里可以了解每个 API 版本中引入的更改？
如果我更改已使用旧 API 版本配置的资源的 API 版本，Azure 会做什么？

Answer 1

有none，因为没有意义（进一步阅读）
我不知道有这样的地方，很可能根本不存在
没什么，除非资源定义中发生了某些变化。

一般来说，只要您使用的 API 版本可以处理您的请求（API 版本可以有不同的功能），您就不必关心 API 版本妥妥的时尚。

ARM 模板的 PM 说：API 版本无关紧要，也不必彼此一致（因此您可以对所有资源使用不同的 API 版本相同的模板和相同的 API 版本并不意味着资源可以更好地协同工作或类似的东西）。（不是确切的引用，但你明白了）

即使您最多查看其余 api 参考资料，它也会指出其描述的 api 版本（最多）。有时它甚至不会这样做...所以它是一个黑盒子，不要理会它。

唯一一次 api 版本很重要 - 你想做的事情在你的 api 版本中不可用，你需要使用合适的版本（不一定是最新的，有时旧版本有什么你需要，比如托管磁盘 were\are 2016-04-30-preview 或类似的东西）

Answer 2

"What is the best practice to maintain resource API versions in a template?"

您不需要更新资源的 api-version 字段，除非您正在使用先前 api-version 未涵盖的新功能。

主要是能用就不要修了

ARM 模板中嵌入的 api-version 字段的目的是确保模板在任何时间点继续按预期运行。

我见过一些带有 api 版本变量的模板。我不喜欢这种方法。更改 api 版本太容易了，更新该版本可能会使架构无效并导致任意数量的错误。

"Where do I learn about the changes introduced in each API version?"

它是非常原始的形式，但您可以在此 GitHub 存储库中看到资源提供者的 Swagger 规范。

GitHub: azure/azure-rest-api-specs 和 GitHub: azure/azure-resource-manager-schemas

Azure SDK、ARM 模板，甚至一些门户 UI 将此存储库作为自动生成的 Swagger 源。

对于最新的 ARM 版本功能，您可以使用此文档子站点，它也是从规范生成的。

ARM Template Resource Definitions

如果我更改已使用旧 API 版本配置的资源的 API 版本，Azure 会做什么？

如果您更改 api 版本并执行更改，如果您尚未将资源配置更新到新版本，Azure 资源管理器 API 可能会响应对象架构错误。

您可以运行验证调用来获取这些错误而不进行任何更改。

同样，除非您在新 api 版本中使用新功能或配置，否则确实没有理由更新模板资源的 api 版本。

Answer 3

根据其他回复，我为我的团队起草了以下资源管理器 API 版本的最佳实践文档。

Azure 资源管理器API 版本指南

对添加到模板的新资源尽可能使用最新的 API 版本。使用文章 Resource providers and types 作为如何获取资源类型的最新 API 版本的指南。
请勿为了与 API 版本保持同步而更改已配置资源的 API 版本。一般原则 - 如果有效，请不要修复它。
仅在 Microsoft Azure 建议或更新的 API 版本将启用新功能时才更改已配置资源的 API 版本。
不要为 API 版本使用模板变量。 API 版本必须在模板中定义为文本。

Answer 4

其实有一种方法可以始终使用最新的 API 版本。我不推荐它，但你可以使用：

[providers('<provider>','<type>').apiVersions[0]]

这是一个存储帐户的工作示例：

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "resources": [
        {
            "type": "Microsoft.Storage/storageAccounts",
            "name": "uniquename",
            "apiVersion": "[providers('Microsoft.Storage','storageAccounts').apiVersions[0]]",
            "location": "West Europe",
            "sku": {
                "name": "Standard_LRS"
            },
            "kind": "Storage",
            "properties": {}
        }
    ]
}

我更愿意在编写ARM模板时使用最新版本，并在遇到错误或必须使用一些新功能时检查更新版本。我写了两篇关于如何 determine latest API version for a resource provider and how to find outdated Azure ARM templates.

的文章

如何使现有 ARM 模板上的资源 API 版本保持最新？

How do I keep resource API versions up to date on existing ARM template?

azure

azure-resource-manager