TL;DR · Key Takeaways
- Mappings and profiles are the translation layer between the names your templates use and the real resources each region has.
- A flavor mapping turns a name like small into actual CPU and memory; an image mapping turns a name like ubuntu into a real OS image, per region.
- A network profile is a collection of network characteristics: existing networks, their settings, and policies for on-demand networks.
- Storage profiles, backed by storage classes and policies such as the vSAN default, decide how a deployment’s disks are placed.
- Get the naming contract right and one template deploys unchanged across regions. Get it inconsistent and every region needs its own template.
Write a template that asks for a small Ubuntu box, and it should deploy in London or Frankfurt without a single change. Mappings and profiles are what make that true. They are the translation layer between the names your templates speak and the real flavors, images, networks, and storage each region actually has. Skip this layer and your templates hard-code one region’s specifics, which means a second region needs a second template, and now you maintain two of everything.
The four building blocks
Four pieces sit between a template and the metal. A flavor mapping resolves a size name to real CPU and memory. An image mapping resolves an OS name to a real template or image. A network profile describes which networks a deployment can use and how on-demand networks are built. A storage profile decides how disks are placed using storage classes and policies. Templates reference the names; these four resolve the names to reality, per region and cloud account.
| Building block | Turns this name | Into this |
|---|---|---|
| Flavor mapping | small, medium, large | Real vCPU and memory |
| Image mapping | ubuntu, win2022 | A real template or image |
| Network profile | app-net, on-demand | Real networks and policies |
| Storage profile | gold, default | A storage class or policy |
The naming contract is the whole trick
Here is the insight that makes this layer worth the effort. Because a template references a name and the mapping resolves it per region, the same name can point at different real resources in different regions, and the template never knows. Define small as 2 vCPU and 8Gi in region-a and the equivalent in region-b, define ubuntu as the local Ubuntu template in each, and a single template deploys in both. The names are a contract between template authors and infrastructure admins: authors promise to only ask for names that exist, admins promise every region honours the same names.
# Same names, different reality per region (flavor + image mappings)
region-a:
flavor: small -> 2 vCPU, 8Gi
image: ubuntu -> ubuntu-2204-template-a
region-b:
flavor: small -> 2 vCPU, 8Gi
image: ubuntu -> ubuntu-2204-template-b
# The template just references the names, so it is region-agnostic:
resources:
app_vm:
type: Cloud.vSphere.Machine
properties:
flavor: small # resolved by the region's flavor mapping
image: ubuntu # resolved by the region's image mappingNetwork and storage profiles
A network profile is more than a list of networks. It is a collection of network characteristics for a named cloud account and region: the existing networks a deployment can attach to and their settings, plus policies that define on-demand networks and other behaviour. This is where VCF Automation’s ability to build NSX networking in the background gets configured, so a template can ask for an on-demand network and the profile decides how that network is actually created. Get the profile right and developers request networking without ever touching NSX; get it wrong and either nothing connects or everything lands on one flat segment.
Storage profiles do the same job for disks. Backed by storage classes and policies, including the vSAN default policy, a storage profile decides how a deployment’s storage is placed and what guarantees it carries. A name like gold can map to a high-performance vSAN policy in one region and the nearest equivalent in another, keeping the same portability promise as flavors and images. The mistake teams make is leaving storage to the default and discovering later that everything landed on one policy with no way to differentiate tiers.
Worked example
You support two regions and want one template library. In each region you define three flavor mappings (small, medium, large), the same handful of image mappings (ubuntu, win2022) pointing at that region’s local templates, a network profile that exposes an existing management segment plus an on-demand policy for app networks, and two storage profiles (standard and gold) mapped to the local vSAN policies. Now an author writes one template that asks for medium, ubuntu, an on-demand app network, and gold storage, and it deploys identically in both regions. Add a third region later and the only work is recreating those same named mappings there. The template library does not change at all.
How on-demand networking actually works
The headline capability of a network profile is on-demand networking, and it is worth understanding because it is where a lot of the platform’s value lives. A template can declare it needs a network without naming an existing one, and the profile’s on-demand policy tells VCF Automation how to build it: which transport zone, which edge, what kind of segment, and how it connects outward. The platform then creates the NSX segment and the wiring in the background at deploy time, and tears it all down when the deployment is destroyed. For a developer this is the difference between filing a network ticket and waiting, and getting a working, isolated network as part of the same request that built their machines.
The design decision inside a network profile is which network types you expose. Existing networks attach a deployment to a segment you already run, which suits shared services everyone uses. On-demand networks create fresh, isolated segments per deployment, which suits self-contained application stacks that should not share a broadcast domain with anyone else. Outbound and routed options control how those networks reach the rest of the world. Expose only the types your tenants should actually use, because every network type you offer is a shape of network someone can now request without asking you, and an over-generous profile is how unexpected segments start appearing in NSX.
One binding detail ties this back to portability. A profile is defined for a specific cloud account and region, so it is not shared globally; each region needs its own profile, just as it needs its own mappings. That is why a template that deploys cleanly is really a template plus a complete set of mappings and profiles in the target region. It also means a change to one region’s network design is a change to that region’s profile alone, not a global edit, which is safer but easy to forget when you assume a fix in one place covers everywhere. Document the profiles next to the mappings, because together they are the full contract every template silently depends on.
The mapping mistakes that break deployments
The naming contract drifts
Flavor and image mappings work because a template references a mapping name, not a raw vSphere object, and the platform resolves the name per region. The failure mode is drift: a template references a mapping name that exists in one region and not another, so the same catalog item deploys in region A and fails in region B. Keep the mapping names identical across regions, and treat the name set as a contract every region must honor.
Image gaps between regions
An image mapping points at an actual image in a content library, and content libraries are per-region. If a region’s library is missing the image a mapping expects, the deployment fails at provision time even though the template and mapping look correct. When you add a region, verify it carries every image the mappings reference before you let tenants target it.
Profile mismatches
Network and storage profiles decide how a deployment gets connectivity and disk. A profile that promises on-demand networking the underlying NSX cannot deliver, or a storage profile pointing at a policy a region lacks, produces a deployment that passes template validation and fails on placement. Validate profiles against what each region can actually provide, not against what you intended it to provide.
The single most common mapping ticket is a catalog item that deploys cleanly in the region it was built in and fails everywhere else. The cause is never the template; it is a mapping name, image or profile that exists in the home region and is missing in the target. Before you publish a multi-region item, deploy it once in every region it claims to support. That one test catches the whole class of failure.
In practice: When I onboard a new region I run a single throwaway deployment of each published catalog item against it before any tenant is allowed to target it. That one pass exercises every mapping, image and profile the item depends on and surfaces the gaps, a missing image here, an unmatched storage policy there, while they are cheap to fix. Skipping it means the gaps are found by a tenant, at request time, as a failure that looks like the platform broke. The throwaway deploy is ten minutes of work that converts a class of confusing tenant-facing failures into a quiet pre-flight you handle yourself.
Where template portability is won
Mappings and profiles are unglamorous and they are where template portability is won or lost. My recommendation: agree a small, fixed vocabulary of names, three flavors, a short list of images, a couple of storage tiers, and make every region honour exactly those names. Treat the names as a contract: authors only ask for names that exist everywhere, admins guarantee every region defines them. Build network profiles that expose what developers actually need, including on-demand networks, so they never have to reach into NSX. Do this and your template library is written once and runs anywhere you have a region. Skip it and you will maintain a separate template for every place you deploy, which is the exact toil this platform exists to remove.
Next we finally write the thing all of this supports: VMware Cloud Templates, the blueprints that reference these names. For where deployments actually land, revisit Part 10 on cloud zones. How many flavor and image names do you standardise on? Tell me in the comments.
References
- Network Profiles in VCF Automation (Broadcom TechDocs)
- Image Mappings in VCF Automation (Broadcom TechDocs)
- VCF Automation: From Zero to a Running VM (vWorld)
About The Author
DrJha