Two Foundry concepts do the version-control work. First, every Claude model ID is a pinned snapshot: starting with the 4.6 generation the IDs are dateless (claude-opus-4-8, claude-sonnet-5) but still pinned — the model behind an ID does not silently change. Second, Foundry separates resources (security and billing configuration) from deployments (the model instances you actually call). Your application's model parameter names a deployment, and that indirection is your upgrade mechanism.
Deployment names are your pinning tool
When you deploy a Claude model in the Foundry portal, the deployment name defaults to the model ID but can be customized — and it cannot be changed after creation. This immutability is a feature: a deployment named for a specific model version is a stable, auditable contract. Two conventions work:
- Version-explicit names (e.g. a deployment per model version): upgrades mean creating a new deployment and changing which name your application calls — a config change in your app, visible in your deploy history.
- Role-based names (e.g. a "production-chat" deployment): the application config never changes; the mapping from role to model lives in Foundry. Since names are immutable but you choose them at creation, this only works if you plan the abstraction before the first deployment.
Also decide the hosting version consciously: Foundry's "Model version" selector at deploy time chooses between Hosted on Anthropic infrastructure (version 1) and Hosted on Azure (version 2), and the default flow auto-selects Hosted on Azure. The two differ in feature support, so an "upgrade" that also switches hosting version can change more than model behavior.
Why upgrades need real testing, not just a smoke test
Anthropic's migration guide documents genuinely breaking changes between recent generations. Moving from Sonnet 4.6 to Sonnet 5, for example: manual extended thinking returns 400, non-default temperature/top_p/top_k return 400, adaptive thinking becomes on-by-default, and a new tokenizer means the same text uses roughly 30% more tokens — so the same context window holds less, and per-request cost shifts. Opus 4.7 to 4.8, by contrast, is documented as fully backward compatible. You cannot know which kind of upgrade you have without reading the migration notes and running your own evaluation set.
A safe upgrade sequence
- Create the new deployment alongside the old one in the same resource (or a staging resource). Nothing about the existing deployment changes.
- Point staging at the new deployment name and run your evaluation suite: golden prompts with expected outputs, JSON-schema conformance checks, latency and token-count comparisons against the old model's baselines.
- Check quota before cutover. Rate-limit pools are shared per subscription by model+version — your new model draws from a different pool than the old one, with its own defaults (and some models, like Fable 5 on pay-as-you-go, default to zero quota until increased).
- Swap production traffic by changing the deployment name your app calls — behind a feature flag or gradual rollout if your gateway supports it, so you can shift a slice of traffic first.
- Keep the old deployment running until the new one has survived real traffic. Rollback is then a one-line config revert.
- Retire the old deployment once confidence is established, and record the change for audit.
Watch the lifecycle calendar
Pinning defers upgrades; it does not avoid them. Foundry follows the Claude API model lifecycle schedule, and models do retire: Claude Opus 4.1 on Foundry is deprecated and retires on August 5, 2026, with Opus 4.8 as the documented migration target. Treat deprecation announcements as the start of your upgrade project, not a reminder for later — the sequence above takes calendar time, and you want to finish it before the retirement date forces the issue.
Where to go next
For deployment mechanics, see Foundry model deployments; for codifying the whole thing, ARM templates and Bicep or Terraform. Platform-neutral upgrade strategy lives in upgrading models and version pinning.