如何用az cli、PowerShell、Terraform为Azure APIM配置Key Vault证书引用

az cli、PowerShell、Terraform 全量支持和Azure门户完全等价的「直接引用Key Vault证书」配置模式，无需上传证书字节副本，配置合规时可自动实现证书轮换后的网关证书重载。

az cli 配置方法 #

依托az apim custom-domain系列命令即可完成配置，核心是指定Key Vault证书的Secret ID替代本地证书文件上传流程，示例命令：

az apim custom-domain update \
  --name <你的APIM实例名称> \
  --resource-group <资源组名称> \
  --gateway Hostname="api.你的自定义域名.com" \
  --gateway-certificate-key-vault-id "https://<你的KV名称>.vault.azure.net/secrets/<KV内证书名称>"

• 注意：Key Vault证书ID必须去掉末尾的版本后缀，否则APIM会固定锁定当前证书版本，不会自动检测轮换
• 前置要求：提前给APIM的系统分配托管标识在该Key Vault上授予秘密读取权限

PowerShell 配置方法 #

使用Az.ApiManagement模块的自定义域名配置能力，通过指定证书来源类型为KeyVault即可切换为引用模式，示例脚本：

# 构造自定义域名配置对象
$customDomainConfig = [Microsoft.Azure.Commands.ApiManagement.Models.PsApiManagementCustomHostNameConfiguration]@{
    Hostname = "api.你的自定义域名.com"
    HostnameCertificateType = "KeyVault"
    KeyVaultId = "https://<你的KV名称>.vault.azure.net/secrets/<KV内证书名称>"
}
# 应用配置到APIM
Update-AzApiManagement `
  -ResourceGroupName <资源组名称> `
  -Name <你的APIM实例名称> `
  -CustomGatewayHostConfiguration $customDomainConfig

配置逻辑和操作门户的后端调用完全一致，自动重载规则没有差异。

Terraform 配置方法 #

你之前看到的所有要求上传证书字节的示例，本质都是没有使用互斥的key_vault_id配置项，只要替换为该字段，就完全等价于门户的引用配置，不需要导出、上传任何证书内容，示例资源定义：

# 引用Key Vault证书的自定义域名配置
resource "azurerm_api_management_custom_domain" "gateway_domain" {
  api_management_id = azurerm_api_management.example.id
  gateway {
    host_name = "api.你的自定义域名.com"
    # 直接关联Key Vault证书的不带版本的Secret ID，无需传入base64格式的证书内容
    key_vault_id = azurerm_key_vault_certificate.example.secret_id
  }
}

• 注意：不要同时配置certificate和key_vault_id两个字段，二者是互斥的配置项，分别对应上传证书字节模式和Key Vault引用模式，同时配置会触发校验报错

自动重载的生效条件 #

满足以下条件时，APIM会自动完成证书轮换后的重载，无需人工干预：

• APIM开启系统分配托管标识，且该标识对目标Key Vault的证书Secret拥有get权限
• 配置关联的Key Vault证书ID未绑定具体版本号
• APIM会以4小时为周期轮询Key Vault的证书版本，检测到新版本后自动替换网关绑定的证书

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