部署Azure Cosmos DB for MongoDB ARM模板时遇吞吐量迁移错误求助

问题描述 #

通过PowerShell的New-AzResourceGroupDeployment命令部署Azure Cosmos DB for MongoDB账户，目标是创建两个集合：一个用手动吞吐量，另一个用自动缩放吞吐量。部署时触发以下错误：

Status Message: Message: {"code":"BadRequest","message":"Message: {"Errors":["x-ms-cosmos-migrate-offer-to-manual-throughput must be supplied and offercontent must contain autopilotSettings for migration of autoscale collection to manual throughput."]}"

奇怪的是Cosmos DB资源已完全按定义部署完成，但模板中并未尝试将自动缩放集合迁移为手动吞吐量。对应的ARM模板代码如下：

{
  "type": "Microsoft.DocumentDB/databaseAccounts",
  "apiVersion": "2023-04-15",
  "name": "[variables('provisionedCosmosAccountName')]",
  "location": "[resourceGroup().location]",
  "kind": "MongoDB",
  "properties": {
    "databaseAccountOfferType": "Standard",
    "minimalTlsVersion": "Tls12",
    "consistencyPolicy": {
      "defaultConsistencyLevel": "Session",
      "maxIntervalInSeconds": 5,
      "maxStalenessPrefix": 100
    },
    "apiProperties": {
      "serverVersion": "4.2"
    },
    "locations": [
      {
        "locationName": "[resourceGroup().location]",
        "failoverPriority": 0,
        "isZoneRedundant": false
      }
    ],
    "capabilities": [
      {
        "name": "EnableMongo"
      },
      {
        "name": "DisableRateLimitingResponses"
      }
    ],
    "backupPolicy": {
      "type": "Periodic",
      "periodicModeProperties": {
        "backupIntervalInMinutes": 240,
        "backupRetentionIntervalInHours": 8,
        "backupStorageRedundancy": "Geo"
      }
    },
    "capacity": {
      "totalThroughputLimit": 7000
    }
  }
},
{
  "type": "Microsoft.DocumentDB/databaseAccounts/mongodbDatabases",
  "apiVersion": "2023-04-15",
  "name": "[format('{0}/{1}', variables('provisionedCosmosAccountName'), variables('cosmosDatabaseName'))]",
  "dependsOn": [
    "[resourceId('Microsoft.DocumentDB/databaseAccounts', variables('provisionedCosmosAccountName'))]"
  ],
  "properties": {
    "resource": {
      "id": "[variables('cosmosDatabaseName')]"
    }
  }
},
{
  "type": "Microsoft.DocumentDB/databaseAccounts/mongodbDatabases/collections",
  "apiVersion": "2023-04-15",
  "name": "[format('{0}/{1}/{2}', variables('provisionedCosmosAccountName'), variables('cosmosDatabaseName'), 'Audits')]",
  "dependsOn": [
    "[resourceId('Microsoft.DocumentDB/databaseAccounts/mongodbDatabases', variables('provisionedCosmosAccountName'), variables('cosmosDatabaseName'))]",
    "[resourceId('Microsoft.DocumentDB/databaseAccounts', variables('provisionedCosmosAccountName'))]"
  ],
  "properties": {
    "resource": {
      "id": "Audits",
      "shardKey": {
        "PartitionKey": "Hash"
      },
      "indexes": [
        {
          "key": {
            "keys": [
              "_id"
            ]
          }
        },
        {
          "key": {
            "keys": [
              "PartitionKey"
            ]
          }
        }
      ]
    }
  }
},
{
  "type": "Microsoft.DocumentDB/databaseAccounts/mongodbDatabases/collections",
  "apiVersion": "2023-04-15",
  "name": "[format('{0}/{1}/{2}', variables('provisionedCosmosAccountName'), variables('cosmosDatabaseName'), 'Event')]",
  "dependsOn": [
    "[resourceId('Microsoft.DocumentDB/databaseAccounts/mongodbDatabases', variables('provisionedCosmosAccountName'), variables('cosmosDatabaseName'))]",
    "[resourceId('Microsoft.DocumentDB/databaseAccounts', variables('provisionedCosmosAccountName'))]"
  ],
  "properties": {
    "resource": {
      "id": "Event",
      "shardKey": {
        "PartitionKey": "Hash"
      },
      "indexes": [
        {
          "key": {
            "keys": [
              "_id"
            ]
          }
        },
        {
          "key": {
            "keys": [
              "PartitionKey",
              "RunId"
            ]
          },
          "options": {
            "unique": true
          }
        },
        {
          "key": {
            "keys": [
              "PartitionKey"
            ]
          }
        },
        {
          "key": {
            "keys": [
              "ChainId"
            ]
          }
        },
        {
          "key": {
            "keys": [
              "ActionCount"
            ]
          }
        },
        {
          "key": {
            "keys": [
              "EventId"
            ]
          }
        },
        {
          "key": {
            "keys": [
              "RunId"
            ]
          }
        }
      ]
    },
    "options": {
      "autoscaleSettings": {
        "maxThroughput": 2000
      }
    }
  }
},
{
  "type": "Microsoft.DocumentDB/databaseAccounts/mongodbDatabases/collections/throughputSettings",
  "apiVersion": "2023-04-15",
  "name": "[format('{0}/{1}/{2}', variables('provisionedCosmosAccountName'), variables('cosmosDatabaseName'), 'Audits/default')]",
  "dependsOn": [
    "[resourceId('Microsoft.DocumentDB/databaseAccounts/mongodbDatabases/collections', variables('provisionedCosmosAccountName'), variables('cosmosDatabaseName'), 'Audits')]",
    "[resourceId('Microsoft.DocumentDB/databaseAccounts/mongodbDatabases', variables('provisionedCosmosAccountName'), variables('cosmosDatabaseName'))]",
    "[resourceId('Microsoft.DocumentDB/databaseAccounts', variables('provisionedCosmosAccountName'))]"
  ],
  "properties": {
    "resource": {
      "throughput": 500
    }
  }
},
{
  "type": "Microsoft.DocumentDB/databaseAccounts/mongodbDatabases/collections/throughputSettings",
  "apiVersion": "2023-04-15",
  "name": "[format('{0}/{1}/{2}', variables('provisionedCosmosAccountName'), variables('cosmosDatabaseName'), 'Event/default')]",
  "dependsOn": [
    "[resourceId('Microsoft.DocumentDB/databaseAccounts/mongodbDatabases/collections', variables('provisionedCosmosAccountName'), variables('cosmosDatabaseName'), 'Event')]",
    "[resourceId('Microsoft.DocumentDB/databaseAccounts/mongodbDatabases', variables('provisionedCosmosAccountName'), variables('cosmosDatabaseName'))]",
    "[resourceId('Microsoft.DocumentDB/databaseAccounts', variables('provisionedCosmosAccountName'))]"
  ],
  "properties": {
    "resource": {
      "throughput": 200,
      "autoscaleSettings": {
        "maxThroughput": 2000
      }
    }
  }
},

已尝试过给数据库设置自动缩放限制，以及替换账户资源中的capacity和totalThroughputLimit为自动缩放配置，但问题仍未解决。

问题原因 #

错误的核心是Event集合的吞吐量配置重复且冲突：

• 在Event集合的collections资源中，已经通过options.autoscaleSettings定义了自动缩放吞吐量（maxThroughput=2000）
• 又额外定义了独立的throughputSettings资源，同时指定了固定吞吐量throughput:200和自动缩放配置，这会让ARM部署服务误认为是要将已配置自动缩放的集合迁移为手动吞吐量，触发了迁移校验逻辑，但部署请求中缺少迁移所需的x-ms-cosmos-migrate-offer-to-manual-throughput头参数，因此抛出错误。

解决步骤 #

1. 移除Event集合的独立throughputSettings资源：
   既然已经在collections资源的options里配置了自动缩放吞吐量，无需再单独定义throughputSettings资源，避免重复配置导致的冲突。

2. 保留Audits集合的手动吞吐量配置：
   Audits集合的配置是正确的——因为没有在collections资源中定义吞吐量，通过独立的throughputSettings指定固定手动吞吐量是合理的。

3. 调整账户级吞吐量限制（可选）：
   如果保留账户级的capacity.totalThroughputLimit:7000，需确保所有集合的吞吐量总和不超过该限制；若不需要全局限制，可直接移除capacity配置块。

修正后的关键代码示例 #

保留Event集合的collections定义，移除对应的throughputSettings资源：

{
  "type": "Microsoft.DocumentDB/databaseAccounts/mongodbDatabases/collections",
  "apiVersion": "2023-04-15",
  "name": "[format('{0}/{1}/{2}', variables('provisionedCosmosAccountName'), variables('cosmosDatabaseName'), 'Event')]",
  "dependsOn": [
    "[resourceId('Microsoft.DocumentDB/databaseAccounts/mongodbDatabases', variables('provisionedCosmosAccountName'), variables('cosmosDatabaseName'))]",
    "[resourceId('Microsoft.DocumentDB/databaseAccounts', variables('provisionedCosmosAccountName'))]"
  ],
  "properties": {
    "resource": {
      "id": "Event",
      "shardKey": {
        "PartitionKey": "Hash"
      },
      "indexes": [
        // 原索引定义保留
      ]
    },
    "options": {
      "autoscaleSettings": {
        "maxThroughput": 2000
      }
    }
  }
}

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