Mappings define the critical relationships between source and target resources, ensuring VMs are migrated to appropriate networks and storage systems. This chapter covers comprehensive mapping management for both network and storage resources.
For foundational concepts about network and storage mappings, see the official Forklift mapping documentation and storage mapping documentation .
Overview
What are Mappings?
Mappings define source-to-target resource relationships for migration:
Network Mappings : Define how source VM networks map to target Kubernetes/OpenShift networks
Storage Mappings : Define how source storage systems map to target StorageClasses
Why Mappings are Essential
Resource Translation : Convert source virtualization concepts to Kubernetes resources
Policy Enforcement : Ensure VMs land on appropriate networks and storage classes
Performance Optimization : Route workloads to optimal target resources
Security Compliance : Maintain network isolation and storage encryption requirements
Mapping Types Supported
Mapping Type
Source Resources
Target Resources
Network
VM Networks, Port Groups, VLANs
Pod networking, Multus networks, Default networking
Storage
Datastores, Storage Domains, Volumes
StorageClasses with volume modes and access patterns
Note : All source providers support automatic mapping generation during plan creation. Provider-specific mappers intelligently match source networks and storage to appropriate target resources.
Listing, Viewing, and Deleting Mappings
List Mappings
1
2
3
4
5
6
7
8
9
10
11
# List all network mappings
kubectl mtv get mappings network
# List all storage mappings
kubectl mtv get mappings storage
# List mappings in specific namespace
kubectl mtv get mappings network --namespace migration-namespace
# List mappings across all namespaces
kubectl mtv get mappings storage --all-namespaces
View Mapping Details
1
2
3
4
5
6
7
8
9
# Describe network mapping
kubectl mtv describe mapping network --name my-network-mapping
# Describe storage mapping
kubectl mtv describe mapping storage --name my-storage-mapping
# View mapping in YAML format
kubectl get networkmapping my-network-mapping -o yaml
kubectl get storagemapping my-storage-mapping -o yaml
Delete Mappings
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Delete specific network mapping
kubectl mtv delete mapping network --name my-network-mapping
# Delete specific storage mapping
kubectl mtv delete mapping storage --name my-storage-mapping
# Delete multiple mappings
kubectl mtv delete mapping network --name mapping1,mapping2,mapping3
# Delete all network mappings in namespace (use with caution)
kubectl mtv delete mapping network --all
# Delete all storage mappings in namespace (use with caution)
kubectl mtv delete mapping storage --all
How-To: Creating Mappings
Network Mapping Creation
Network mappings translate source VM networks to target Kubernetes networking:
Basic Network Mapping Syntax
1
2
3
4
kubectl mtv create mapping network --name NAME \
--source SOURCE_PROVIDER \
--target TARGET_PROVIDER \
--network-pairs "source1:target1,source2:target2,..."
kubectl-mtv supports four network mapping formats verified from the command code:
Format
Description
Example
source:target-namespace/target-network
Multus network with namespace
'VM Network:multus-system/bridge-network'
source:target-network
Multus network in same namespace
'Management Network:mgmt-network'
source:default
Default pod networking
'VM Network:default'
source:ignored
Ignore/skip network
'Backup Network:ignored'
Network Mapping Examples
Basic Network Mapping
1
2
3
4
5
# Simple network mapping for vSphere to OpenShift
kubectl mtv create mapping network --name prod-network-mapping \
--source vsphere-prod \
--target openshift-target \
--network-pairs "VM Network:default,Management Network:multus-system/mgmt-net"
Advanced Network Mapping
1
2
3
4
5
# Comprehensive network mapping with multiple network types
kubectl mtv create mapping network --name comprehensive-network \
--source vsphere-prod \
--target openshift-target \
--network-pairs "Production VLAN:prod-network,Management Network:multus-system/management,DMZ Network:dmz-net,Backup Network:ignored"
Development Environment Mapping
1
2
3
4
5
# Development network mapping with simplified targeting
kubectl mtv create mapping network --name dev-network-mapping \
--source vsphere-dev \
--target openshift-dev \
--network-pairs "Dev Network:default,Test Network:default,Isolated Network:ignored"
Multi-Namespace Network Mapping
1
2
3
4
5
# Cross-namespace network mapping
kubectl mtv create mapping network --name cross-ns-mapping \
--source ovirt-prod \
--target openshift-target \
--network-pairs "ovirtmgmt:openshift-sdn/default,production:prod-namespace/prod-net,dmz:security-namespace/dmz-network"
Storage Mapping Creation
Storage mappings define how source storage systems map to target StorageClasses with enhanced options:
Basic Storage Mapping Syntax
1
2
3
4
kubectl mtv create mapping storage --name NAME \
--source SOURCE_PROVIDER \
--target TARGET_PROVIDER \
--storage-pairs "source1:storageclass1,source2:storageclass2,..."
Storage pairs support enhanced options verified from the command code:
1
'source:storage-class[;volumeMode=Block|Filesystem][;accessMode=ReadWriteOnce|ReadWriteMany|ReadOnlyMany][;offloadPlugin=vsphere][;offloadSecret=secret-name][;offloadVendor=vendor-name]'
Enhanced Storage Options
Volume Modes
Mode
Description
Use Case
Filesystem
Traditional file system access
General application storage
Block
Raw block device access
Databases, high-performance applications
Access Modes
Mode
Description
Use Case
ReadWriteOnce
Read-write by single node
Single-instance applications
ReadWriteMany
Read-write by multiple nodes
Shared file systems
ReadOnlyMany
Read-only by multiple nodes
Shared configuration, content
Offload Vendors (Storage Array Integration)
Verified vendor list from command code:
flashsystem - IBM FlashSystem
vantara - Hitachi Vantara
ontap - NetApp ONTAP
primera3par - HPE Primera/3PAR
pureFlashArray - Pure Storage FlashArray
powerflex - Dell PowerFlex
powermax - Dell PowerMax
powerstore - Dell PowerStore
infinibox - Infinidat InfiniBox
Storage Mapping Examples
Basic Storage Mapping
1
2
3
4
5
# Simple storage mapping for vSphere to OpenShift
kubectl mtv create mapping storage --name basic-storage-mapping \
--source vsphere-prod \
--target openshift-target \
--storage-pairs "datastore1:fast-ssd,datastore2:standard-storage"
Advanced Storage Mapping with Enhanced Options
1
2
3
4
5
# Storage mapping with volume modes and access patterns
kubectl mtv create mapping storage --name advanced-storage \
--source vsphere-prod \
--target openshift-target \
--storage-pairs "fast-datastore:premium-ssd;volumeMode=Block;accessMode=ReadWriteOnce,shared-datastore:shared-storage;volumeMode=Filesystem;accessMode=ReadWriteMany,archive-datastore:backup-storage;accessMode=ReadOnlyMany"
Storage Array Offloading Configuration
1
2
3
4
5
6
7
# Storage mapping with FlashSystem offloading
kubectl mtv create mapping storage --name offload-flashsystem \
--source vsphere-prod \
--target openshift-target \
--storage-pairs "production-ds:flashsystem-fast;offloadPlugin=vsphere;offloadVendor=flashsystem;offloadSecret=flashsystem-creds" \
--default-volume-mode Block \
--default-access-mode ReadWriteOnce
NetApp ONTAP Offloading with Secret Creation
1
2
3
4
5
6
7
8
9
10
11
# Create storage mapping with automatic offload secret creation
kubectl mtv create mapping storage --name ontap-offload \
--source vsphere-prod \
--target openshift-target \
--storage-pairs "netapp-datastore:ontap-gold;offloadPlugin=vsphere;offloadVendor=ontap" \
--offload-vsphere-username vcenter-service@vsphere.local \
--offload-vsphere-password VCenterPassword123 \
--offload-vsphere-url https://vcenter.company.com \
--offload-storage-username ontap-admin \
--offload-storage-password NetAppPassword123 \
--offload-storage-endpoint https://netapp-cluster.company.com
Default Options for Multiple Storage Classes
1
2
3
4
5
6
7
8
9
# Storage mapping with global defaults
kubectl mtv create mapping storage --name default-options \
--source ovirt-prod \
--target openshift-target \
--storage-pairs "ovirt-data:standard-rwo,ovirt-shared:shared-rwx,ovirt-fast:premium-block" \
--default-volume-mode Filesystem \
--default-access-mode ReadWriteOnce \
--default-offload-plugin vsphere \
--default-offload-vendor vantara
Complete Storage Array Offloading Examples
IBM FlashSystem Configuration
1
2
3
4
5
6
7
8
9
10
11
# FlashSystem storage array offloading
kubectl mtv create mapping storage --name flashsystem-prod \
--source vsphere-prod \
--target openshift-target \
--storage-pairs "ssd-datastore:flashsystem-tier1;offloadPlugin=vsphere;offloadVendor=flashsystem;volumeMode=Block;accessMode=ReadWriteOnce" \
--offload-vsphere-username svc-flashsystem@vsphere.local \
--offload-vsphere-password FlashSystemVCPassword \
--offload-vsphere-url https://vcenter.prod.company.com \
--offload-storage-username flashsystem-admin \
--offload-storage-password FlashSystemPassword \
--offload-storage-endpoint https://flashsystem.company.com:7443
Pure Storage FlashArray Configuration
1
2
3
4
5
6
7
8
9
# Pure Storage FlashArray offloading
kubectl mtv create mapping storage --name pure-flasharray \
--source vsphere-prod \
--target openshift-target \
--storage-pairs "pure-datastore:pure-block-gold;offloadPlugin=vsphere;offloadVendor=pureFlashArray;volumeMode=Block" \
--offload-storage-username pureuser \
--offload-storage-password PureStorageAPIKey \
--offload-storage-endpoint https://pure-array.company.com \
--offload-cacert @/certs/pure-ca.pem
Dell PowerMax Configuration
1
2
3
4
5
6
7
8
9
# Dell PowerMax storage array configuration
kubectl mtv create mapping storage --name powermax-enterprise \
--source vsphere-prod \
--target openshift-target \
--storage-pairs "powermax-gold:powermax-tier1;offloadPlugin=vsphere;offloadVendor=powermax;volumeMode=Block;accessMode=ReadWriteOnce" \
--offload-storage-username powermax-svc \
--offload-storage-password PowerMaxPassword \
--offload-storage-endpoint https://powermax.company.com:8443 \
--default-volume-mode Block
How-To: Patching Mappings
Mapping patching allows you to add, update, or remove pairs without recreating the entire mapping:
Network Mapping Patching
Add Network Pairs
1
2
3
# Add new network pairs to existing mapping
kubectl mtv patch mapping network --name prod-network-mapping \
--add-pairs "New VLAN:new-network,Guest Network:guest-net"
Update Network Pairs
1
2
3
# Update existing network mappings
kubectl mtv patch mapping network --name prod-network-mapping \
--update-pairs "Management Network:multus-system/new-mgmt-net,Production VLAN:updated-prod-network"
Remove Network Pairs
1
2
3
# Remove networks from mapping
kubectl mtv patch mapping network --name prod-network-mapping \
--remove-pairs "Old Network,Deprecated VLAN"
Combined Network Operations
1
2
3
4
5
# Perform multiple operations in single command
kubectl mtv patch mapping network --name prod-network-mapping \
--add-pairs "New Production:prod-new" \
--update-pairs "Management Network:mgmt-updated" \
--remove-pairs "Legacy Network"
Storage Mapping Patching
Add Storage Pairs
1
2
3
# Add new storage pairs with enhanced options
kubectl mtv patch mapping storage --name prod-storage-mapping \
--add-pairs "new-datastore:premium-nvme;volumeMode=Block;accessMode=ReadWriteOnce,backup-datastore:backup-storage;volumeMode=Filesystem;accessMode=ReadOnlyMany"
Update Storage Pairs
1
2
3
# Update existing storage mappings with new options
kubectl mtv patch mapping storage --name prod-storage-mapping \
--update-pairs "fast-datastore:ultra-fast-ssd;volumeMode=Block;offloadPlugin=vsphere;offloadVendor=flashsystem"
Remove Storage Pairs
1
2
3
# Remove storage pairs from mapping
kubectl mtv patch mapping storage --name prod-storage-mapping \
--remove-pairs "old-datastore,deprecated-storage"
Advanced Storage Patching with Offloading
1
2
3
4
5
# Add storage with complete offloading configuration
kubectl mtv patch mapping storage --name enterprise-mapping \
--add-pairs "tier1-datastore:flashsystem-gold;volumeMode=Block;accessMode=ReadWriteOnce;offloadPlugin=vsphere;offloadVendor=flashsystem;offloadSecret=flashsystem-secret" \
--default-volume-mode Block \
--default-offload-plugin vsphere
Complete Mapping Workflow Examples
Example 1: Enterprise Production Setup
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# Step 1: Create comprehensive network mapping
kubectl mtv create mapping network --name enterprise-network \
--source vsphere-production \
--target openshift-production \
--network-pairs "Production VLAN:prod-network,Management Network:multus-system/mgmt-network,DMZ VLAN:security-namespace/dmz-net,Backup Network:ignored"
# Step 2: Create enterprise storage mapping with offloading
kubectl mtv create mapping storage --name enterprise-storage \
--source vsphere-production \
--target openshift-production \
--storage-pairs "Tier1-SSD:flashsystem-premium;volumeMode=Block;accessMode=ReadWriteOnce;offloadPlugin=vsphere;offloadVendor=flashsystem,Tier2-SATA:standard-storage;volumeMode=Filesystem;accessMode=ReadWriteOnce,Shared-NFS:shared-nfs;volumeMode=Filesystem;accessMode=ReadWriteMany" \
--offload-vsphere-username svc-migration@vsphere.local \
--offload-vsphere-password $( cat /secure/vcenter-password) \
--offload-vsphere-url https://vcenter.prod.company.com \
--offload-storage-username flashsystem-admin \
--offload-storage-password $( cat /secure/flashsystem-password) \
--offload-storage-endpoint https://flashsystem.company.com:7443
# Step 3: Verify mappings
kubectl mtv describe mapping network --name enterprise-network
kubectl mtv describe mapping storage --name enterprise-storage
Example 2: Development Environment
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Development network mapping (simple)
kubectl mtv create mapping network --name dev-simple-network \
--source vsphere-dev \
--target openshift-dev \
--network-pairs "Dev VLAN:default,Test Network:default,Management:ignored" \
--namespace development
# Development storage mapping (basic)
kubectl mtv create mapping storage --name dev-simple-storage \
--source vsphere-dev \
--target openshift-dev \
--storage-pairs "dev-datastore:standard-ssd,test-datastore:test-storage" \
--default-volume-mode Filesystem \
--default-access-mode ReadWriteOnce \
--namespace development
Example 3: Multi-Provider Setup
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# oVirt to OpenShift mapping
kubectl mtv create mapping network --name ovirt-to-ocp \
--source ovirt-production \
--target openshift-target \
--network-pairs "ovirtmgmt:default,production:prod-net,dmz:dmz-network"
kubectl mtv create mapping storage --name ovirt-storage \
--source ovirt-production \
--target openshift-target \
--storage-pairs "data:standard-rwo,shared:shared-rwx,fast:premium-ssd" \
--default-volume-mode Filesystem
# OpenStack to OpenShift mapping
kubectl mtv create mapping network --name openstack-to-ocp \
--source openstack-prod \
--target openshift-target \
--network-pairs "internal:default,external:multus-system/external-net,provider:provider-network"
kubectl mtv create mapping storage --name openstack-storage \
--source openstack-prod \
--target openshift-target \
--storage-pairs "__DEFAULT__:standard-rwo,ssd:premium-ssd,ceph:ceph-rbd" \
--default-volume-mode Block
Advanced Mapping Scenarios
Network Mapping Patterns
Multus Network Integration
1
2
3
4
5
# Complex Multus network mapping with multiple namespaces
kubectl mtv create mapping network --name multus-complex \
--source vsphere-prod \
--target openshift-target \
--network-pairs "Frontend-VLAN:web-namespace/frontend-net,Database-VLAN:db-namespace/database-net,Management:kube-system/management,Monitoring:monitoring/prometheus-net,Storage-Network:rook-ceph/cluster-network"
Security Zone Mapping
1
2
3
4
5
# Security zone-based network mapping
kubectl mtv create mapping network --name security-zones \
--source vsphere-security \
--target openshift-security \
--network-pairs "Public-DMZ:dmz-namespace/public-dmz,Internal-DMZ:dmz-namespace/internal-dmz,Secure-Zone:secure-namespace/secure-net,Management-Zone:mgmt-namespace/mgmt-secure,Guest-Network:ignored"
VLAN-to-Namespace Mapping
1
2
3
4
5
# Map VLANs to specific namespaces
kubectl mtv create mapping network --name vlan-namespace \
--source vsphere-prod \
--target openshift-target \
--network-pairs "VLAN-100:production/prod-net,VLAN-200:development/dev-net,VLAN-300:testing/test-net,VLAN-400:staging/stage-net"
Storage Mapping Patterns
1
2
3
4
5
6
# Map storage tiers to appropriate StorageClasses
kubectl mtv create mapping storage --name performance-tiers \
--source vsphere-prod \
--target openshift-target \
--storage-pairs "NVMe-Tier1:ultra-fast-nvme;volumeMode=Block;accessMode=ReadWriteOnce,SSD-Tier2:fast-ssd;volumeMode=Block;accessMode=ReadWriteOnce,SATA-Tier3:standard-storage;volumeMode=Filesystem;accessMode=ReadWriteOnce,NFS-Shared:shared-nfs;volumeMode=Filesystem;accessMode=ReadWriteMany" \
--default-volume-mode Block
Application-Specific Storage
1
2
3
4
5
# Application-specific storage class mapping
kubectl mtv create mapping storage --name app-specific \
--source vsphere-prod \
--target openshift-target \
--storage-pairs "Database-Storage:database-optimized;volumeMode=Block;accessMode=ReadWriteOnce,Web-Storage:web-optimized;volumeMode=Filesystem;accessMode=ReadWriteOnce,Log-Storage:log-aggregation;volumeMode=Filesystem;accessMode=ReadWriteMany,Backup-Storage:backup-tier;volumeMode=Filesystem;accessMode=ReadOnlyMany"
Multi-Vendor Storage Array Integration
1
2
3
4
5
6
7
# Multiple storage vendor integration
kubectl mtv create mapping storage --name multi-vendor \
--source vsphere-enterprise \
--target openshift-target \
--storage-pairs "FlashSystem-Gold:flashsystem-tier1;offloadPlugin=vsphere;offloadVendor=flashsystem;volumeMode=Block,NetApp-Silver:ontap-tier2;offloadPlugin=vsphere;offloadVendor=ontap;volumeMode=Filesystem,Pure-Platinum:pure-tier0;offloadPlugin=vsphere;offloadVendor=pureFlashArray;volumeMode=Block,Dell-Bronze:powermax-tier3;offloadPlugin=vsphere;offloadVendor=powermax;volumeMode=Block" \
--default-volume-mode Block \
--default-access-mode ReadWriteOnce
Mapping Validation and Testing
Validate Network Mappings
1
2
3
4
5
6
7
8
# Check network availability in target
kubectl get networks -A | grep -E "(prod-net|mgmt-net|dmz-network)"
# Verify Multus network definitions
kubectl get network-attachment-definitions -A
# Test network connectivity
kubectl mtv get inventory network --provider openshift-target
Validate Storage Mappings
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# Check StorageClass availability
kubectl get storageclass
# Verify storage array integration
kubectl get csidriver
# Test storage provisioning
kubectl apply -f - << EOF
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: test-pvc
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 1Gi
storageClassName: premium-ssd
EOF
Mapping Pre-Migration Validation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
#!/bin/bash
# Pre-migration mapping validation script
NETWORK_MAPPING = "enterprise-network"
STORAGE_MAPPING = "enterprise-storage"
NAMESPACE = "konveyor-forklift"
echo "Validating network mapping..."
kubectl describe networkmapping " $NETWORK_MAPPING " -n " $NAMESPACE "
echo "Validating storage mapping..."
kubectl describe storagemapping " $STORAGE_MAPPING " -n " $NAMESPACE "
echo "Checking target resources..."
kubectl get storageclass
kubectl get network-attachment-definitions -A
echo "Validation complete"
Troubleshooting Mapping Issues
Common Mapping Problems
Network Mapping Issues
1
2
3
4
5
6
7
8
# Check if target networks exist
kubectl get network-attachment-definitions -A | grep target-network-name
# Verify Multus installation
kubectl get pods -n kube-system | grep multus
# Check network mapping status
kubectl describe networkmapping mapping-name -n konveyor-forklift
Storage Mapping Issues
1
2
3
4
5
6
7
8
9
10
11
# Check StorageClass availability
kubectl get storageclass storage-class-name
# Verify CSI driver installation
kubectl get csidriver
# Check storage mapping status
kubectl describe storagemapping mapping-name -n konveyor-forklift
# Test storage provisioning
kubectl get pv,pvc -A | grep storage-class-name
Mapping Syntax Validation
1
2
3
4
5
# Test network pairs syntax
echo "VM Network:default,Management:mgmt-net" | tr ',' '\n'
# Test storage pairs syntax
echo "ds1:sc1;volumeMode=Block,ds2:sc2;accessMode=ReadWriteMany" | tr ',' '\n'
Debug Mapping Creation
1
2
3
4
5
6
7
8
9
# Enable verbose logging
kubectl mtv create mapping network --name test-mapping \
--source vsphere-prod \
--target openshift-target \
--network-pairs "VM Network:default" \
-v = 2
# Check mapping resource creation
kubectl get networkmapping,storagemapping -A
Integration with Migration Plans
Mappings integrate seamlessly with migration plan creation:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Create migration plan using mappings
kubectl mtv create plan --name enterprise-migration \
--source vsphere-production \
--target openshift-production \
--network-mapping enterprise-network \
--storage-mapping enterprise-storage \
--vms "web-server-01,db-server-01,app-server-01"
# Alternative: Use inline mapping pairs
kubectl mtv create plan --name inline-migration \
--source vsphere-prod \
--network-pairs "VM Network:default,Management:mgmt-net" \
--storage-pairs "datastore1:standard-ssd,datastore2:premium-nvme" \
--vms "test-vm-01,test-vm-02"
Best Practices for Mapping Management
Network Mapping Best Practices
Use Descriptive Names : Create mappings with clear, descriptive names
Plan Network Isolation : Map security zones to appropriate target networks
Consider Performance : Route high-bandwidth workloads to appropriate networks
Document Dependencies : Maintain mapping documentation for operations teams
Storage Mapping Best Practices
Match Performance Requirements : Map high-IOPS workloads to fast storage classes
Consider Access Patterns : Use appropriate volume modes and access modes
Leverage Storage Array Features : Use offloading for compatible storage systems (see Chapter 12: Storage Array Offloading for detailed information)
Plan for Scale : Consider storage capacity and performance implications
Operational Best Practices
Test Mappings : Validate mappings before production migrations
Version Control : Maintain mapping configurations in version control
Monitor Resources : Ensure target resources have sufficient capacity
Update Gradually : Use patching for incremental mapping updates
Next Steps
After mastering mapping management:
Plan Creation : Use mappings in Chapter 13: Migration Plan Creation
VM Customization : Apply mappings to specific VMs in Chapter 14: Customizing Individual VMs
Optimization : Leverage mapping insights in Chapter 16: Migration Process Optimization
Advanced Patching : Learn plan patching in Chapter 18: Advanced Plan Patching
Previous: Chapter 10: Query Language Reference and Advanced Filtering
Next: Chapter 12: Storage Array Offloading and Optimization