Azure DevOps ARM部署APIM时Key Vault参数传递报错排查

报错根因 #

Either Value or Key vault must be provided and Secret Identifier is not in the correct format报错的核心原因是Key Vault参数的引用格式不符合ARM任务的识别规则：$(keyvaultname/secretname)既不是流水线拉取机密后生成的有效变量名，也不是ARM部署支持的Key Vault原生引用格式，导致参数值校验失败。

两种正确配置方案 #

方案1：提前拉取机密为流水线变量后传明文值 #

如果你已经在流水线中添加了Azure Key Vault任务、或者关联了Key Vault类型的变量组，机密会被自动拉取为流水线可用变量，直接按普通变量引用即可：

• Key Vault任务/变量组拉取机密后，生成的流水线变量名和Key Vault中的机密名称完全一致，不会携带Key Vault名称前缀。比如Key Vault中存的APIM管理员密钥名为apim-admin-key，对应变量就是$(apim-admin-key)。
• 在ARM任务的override parameters配置栏中，按普通参数格式传入即可，示例：

  -apimAdminKey $(apim-admin-key) -apimServiceName my-apim-instance
  

• 注意：该方案要求ARM模板中对应参数为普通securestring/string类型，部署时传入的是机密明文值。

方案2：ARM部署时直接引用Key Vault机密（无需提前拉取） #

该方案不需要提前添加Key Vault相关任务/变量组，由ARM部署过程中直接从Key Vault拉取机密值，安全性更高：

• 提前给ARM任务使用的Azure服务连接对应的服务主体，授予目标Key Vault的机密读取（Get）权限。
• 确认ARM模板中对应密钥参数为securestring类型，不需要额外配置Key Vault引用结构。
• 在override parameters中按ARM原生Key Vault引用格式传参，注意转义规则，示例：

  -apimAdminKey "`"Microsoft.KeyVault/vaults/<替换为你的Key Vault名称>/secrets/<替换为对应机密名称>`""
  

  如果需要指定固定版本的机密，在机密名后追加/<机密版本号>即可。

常见踩坑点 #

• 不要在Key Vault任务拉取的变量前加Key Vault名称前缀，会直接导致变量解析为空。
• 用ARM原生引用格式时，不要漏掉外层的`"转义符，否则会被识别为普通字符串触发格式报错。
• 不要把两种方案的格式混用，比如在ARM Key Vault引用格式外面套$()，会导致解析失败。

内容的提问来源于stack exchange，提问作者Raju K