Safe limits for Azure VNet modification via REST API / SDK (large configurations)

Eduardo Palou Hervias 20 Reputation points Microsoft Employee
2026-06-24T08:25:43.27+00:00

Hello.

We are working with Azure VNets that have a relatively high number of configurations (multiple peerings, subnets, and associated resources).

We are planning to update these VNets programmatically (via REST API / SDK) to add summarizedGatewayPrefixes.

However, when exporting the VNet configuration, some of these VNets result in very large JSON payloads (over ~50k lines).

We would like to understand if there are any known limitations or best practices related to modifying VNets of this size.

Specifically:

  1. Are there any documented limits (payload size, request size, or complexity) when performing PUT/PATCH operations on VNets through REST API or SDK?
  2. Can large VNet configurations lead to issues such as timeouts, partial updates, or inconsistencies during deployment?
  3. Is there any recommended approach to safely update properties like summarizedGatewayPrefixes without sending the full VNet definition (e.g., partial updates or alternative APIs)?
  4. Are there known best practices for handling large-scale VNets to avoid deployment or update failures?

Any guidance or insight from Microsoft engineering or documentation would be highly appreciated.

Thanks

Eduardo

Azure Virtual Network
Azure Virtual Network

An Azure networking service that is used to provision private networks and optionally to connect to on-premises datacenters.

0 comments
Answer accepted by question author
Sindhuja Dasari 2,115 Reputation points Microsoft External Staff Moderator
2026-07-06T11:13:58+00:00

Hello @Eduardo Palou Hervias

Glad to connect with you.
Based on the information shared by the architect team, the current API JSON payload size limit is 4 MB, and the current Virtual Network configuration size is approximately 3 MB, which remains within the supported limit and should not present any issues for current operations.

It is noted that the VNet definition may continue to grow over time as additional networking configurations are added, including VNet peerings and other resources.
The request to review or increase the current payload size limit is pending PG team evaluation.

Additionally, recent Azure Virtual Network API behaviour changes allow Virtual Network updates without requiring the subnet collection to be included in every PUT request. This helps reduce the operational risk associated with updating large VNet definitions by decreasing the payload size that must be submitted during update operations and reducing the likelihood of issues such as request timeouts, update inconsistencies, or conflicts when working with large and complex VNet configurations.

At this time, there is no immediate concern, as the current VNet payload remains below the supported limit and the latest API improvements help mitigate some of the challenges previously associated with large VNet update operations.
Please210246-screenshot-2021-12-10-121802.pngand “up-vote” wherever the information provided helps you, **this can be beneficial to other community members.

Was this answer helpful?

1 person found this answer helpful.
0 comments

1 additional answer

Sort by: Most helpful
Most helpful Newest Oldest
  1. Alex Burlachenko 25,285 Reputation points MVP Volunteer Moderator
    2026-06-24T14:51:12.1533333+00:00

    Eduardo Palou Hervias hi, thx for sharing urs issue here at Q&A portal,

    For VNets, I’d avoid doing full-resource PUT with a huge exported JSON unless u really have to.

    ARM PUT is normally a full replace-style update. So if ur payload is huge, stale, or missing server-managed fields, u can get weird failures or accidentally overwrite parts of the VNet config. Not fun, esp w/ peerings/subnets attached. Safer move is use the smallest scoped API that updates only what u need. If summarizedGatewayPrefixes is exposed on the virtual network resource in ur api-version, use PATCH if supported by that Network RP version, or use SDK/CLI cmd that sends a minimal model instead of replaying the full export. I’d also use If-Match / ETag handling so u don’t overwrite someone else’s change. Read VNet, keep the ETag, patch/update, then re-read and verify. https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/lock-resources

    For large VNets, expect long-running Network RP ops. Don’t assume timeout means failure. Track the Azure-AsyncOperation / operation result and check provisioning state after. Network updates can take time even when the payload is valid.

    test on a cloned/non-prod VNet shape first, update one VNet at a time, take the current config backup, avoid parallel subnet/peering changes during the same window, and log correlation IDs for every request. I don’t know of a clean public doc that says ‘VNet PUT max is X lines of JSON’. The real limit is usually ARM/request payload size + Network RP validation/operation time, not line count. 50k lines is a smell tho. Means u should not round-trip the full export unless MS networking confirms that’s the intended path.

    https://learn.microsoft.com/en-us/rest/api/virtualnetwork/virtual-networks so, best ask to MS Networking would be what api-version supports partial update for summarizedGatewayPrefixes, and whether the Network RP team recommends PATCH/minimal update vs full VNet PUT for large VNet configs.

    rgds,

    Alex

    &

    If my answer was helpful pls mark it and additional thx if u follow me at Q&A portal

    Was this answer helpful?

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.