Model Versions, Upgrade Policies, and Retirement

What this slice covers

Models are not fixed products. They are refreshed constantly, superseded, and eventually withdrawn, and a deployment you created months ago will be affected by all three whether or not you are watching. This note covers versioning, the upgrade policies you choose at deployment time, the lifecycle stages a model passes through, and what actually happens on the day a version retires.

This is the part of the topic that most often turns into a production incident, because the failure arrives on a schedule someone else set.

Two versions, not one

When you work with a model there are two independent version numbers in play, and confusing them is the first mistake.

The model version identifies the weights — a deployment of a given model might target a dated release such as 2024-08-06, with a later dated release becoming available in time.

The API version identifies the contract your code speaks to, passed as the api-version query parameter on REST calls. Azure SDK releases are usually paired with particular API versions, but you can specify the one you want.

They move independently. A single deployment can support multiple API versions, and a new model version does not necessarily oblige you to change API version — a weights update is the typical case where it does not.

Upgrade policies

When you deploy a model you configure an update policy, and you can change it later in the deployment settings. Policies are set per deployment and the available options vary by model and provider. There are three:

• Opt out of automatic upgrades. The deployment stays where it is. A new version requires a manual upgrade from you, and when the current model retires the deployment stops working.
• Upgrade once a new default version becomes available. The deployment moves to each new default automatically.
• Once the current version expires. The deployment stays put until its version is retired, then updates automatically.

Note the guidance boundary: this applies to standard deployment types. Provisioned deployments follow separate model-management guidance.

Two more facts round out the Azure OpenAI picture. Customers are notified at least two weeks before a new version becomes the default. And Azure maintains the previous major version of a model until its retirement date, so you can switch back to it if needed — that rollback window is the safety net that makes automatic upgrades tolerable.

Regional availability does not exempt you. If the newest version is not yet live in your region, Azure deploys it there as part of the scheduled upgrade rather than skipping you.

Lifecycle stages

Every catalogue model sits in exactly one of five stages, and the practical question for each is whether you can create new deployments and whether existing ones still run.

Preview means experimental — weights, runtime, and API schema may change, and general availability is not promised. Generally available means production-ready with fixed weights and APIs. Legacy is an optional warning stage meaning better models exist and you should plan migration; models may skip it entirely. Deprecated means no new customers: existing subscriptions that have already deployed that specific model version can carry on, while everyone else is locked out, and access is not inherited by a sibling subscription in the same tenant. Retired means removed from service, with inference requests returning HTTP 410.

Lifecycle length is not uniform. Generally available models from several partner providers follow a 12-month lifecycle rather than the standard 18-month one.

Partner models version differently

For models from partners and community, a new version frequently arrives as a new model ID rather than a new version of the same one — successive Llama generations are the worked example, each carrying its own identifier. Sometimes every version remains reachable through the same API version; sometimes the API contract changed and your client must change with it. Do not assume the smooth in-place upgrade path that Azure OpenAI models offer.

How you find out

Notification comes through email to subscription owners and contributors, Azure Service Health alerts, and the upcoming-retirement tables in the deprecation and retirement documentation. If nobody on your team reads any of those channels, the first signal will be traffic failing.

Mistakes to avoid

• Treating opt-out as the safe choice. It is the only policy that guarantees an outage at retirement.
• Assuming an automatic upgrade cannot change behaviour. Test after upgrades; that is what the two-week notice and the rollback window are for.
• Confusing API version with model version when debugging a change in output.
• Expecting partner models to upgrade in place under the same identifier.
• Deploying a preview model into production and being surprised when its schema shifts.

What to carry forward

Pick an upgrade policy deliberately, know which lifecycle stage each deployed model is in, test after every version change, and treat retirement dates as scheduled work rather than as bad news that arrives unannounced.