MTV-6116_sco_multi_array_rdm - #956
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughDocumentation adds multi-array RDM storage copy offload guidance, NAA-based datastore matching details, custom NAA-to-vendor ConfigMap configuration, VMware planning references, and troubleshooting procedures. ChangesMulti-array RDM documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@documentation/modules/proc_configuring-naa-oui-map.adoc`:
- Around line 21-26: Update the ConfigMap instructions to separate creation from
editing: provide a valid command or manifest/application path that creates
forklift-naa-oui-map when it does not exist, and retain oc edit configmap only
for modifying an existing ConfigMap.
- Around line 34-45: Update the ConfigMap example near metadata.namespace to
replace the invalid `//` annotation with valid YAML comment syntax, while
preserving the namespace placeholder and keeping the manifest valid.
- Around line 54-58: Document one concrete validation path for custom NAA
mappings: in documentation/modules/proc_configuring-naa-oui-map.adoc at lines
54-58, add the exact oc command and controller-log check confirming
forklift-naa-oui-map was consumed and the new mapping is active; in
documentation/modules/ref_troubleshooting-storage-copy-offload.adoc at lines 22
and 36-38, document the expected NAA-matching failure symptoms and the log
message or status signal indicating custom mappings were not applied.
- Around line 17-18: Use the {namespace} attribute consistently for the
forklift-naa-oui-map ConfigMap location. In
documentation/modules/proc_configuring-naa-oui-map.adoc lines 17-18 and 28,
replace <namespace> with +{namespace}+ in both the oc edit command and manifest;
in documentation/modules/ref_troubleshooting-storage-copy-offload.adoc lines
30-32, state that the ConfigMap must be created in +{namespace}+.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 3007a27f-287e-4619-92bb-4408a356a3d0
📒 Files selected for processing (6)
documentation/doc-Planning_your_migration/assemblies/assembly_planning-migration-vmware.adocdocumentation/modules/con_about-storage-maps.adocdocumentation/modules/con_multi-array-rdm-support.adocdocumentation/modules/proc_configuring-naa-oui-map.adocdocumentation/modules/proc_creating-form-based-storage-maps-ui-vmware.adocdocumentation/modules/ref_troubleshooting-storage-copy-offload.adoc
| // Info needed: What namespace should this ConfigMap be created in? Is it the same namespace where MTV is installed (typically openshift-mtv)? | ||
|
|
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Show the relevant files with line numbers
sed -n '1,120p' documentation/modules/proc_configuring-naa-oui-map.adoc | cat -n
printf '\n---\n'
sed -n '1,120p' documentation/modules/ref_troubleshooting-storage-copy-offload.adoc | cat -n
printf '\n=== namespace references ===\n'
rg -n "openshift-mtv|namespace|ConfigMap" documentation/modules/proc_configuring-naa-oui-map.adoc documentation/modules/ref_troubleshooting-storage-copy-offload.adocRepository: kubev2v/forklift-documentation
Length of output: 9430
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Find all mentions of the ConfigMap and likely namespace guidance
rg -n -C 3 "forklift-naa-oui-map|openshift-mtv|namespace" documentation
printf '\n=== files mentioning custom NAA-to-vendor mapping ===\n'
rg -n "custom NAA-to-vendor|NAA-to-vendor|naa-oui-map" documentationRepository: kubev2v/forklift-documentation
Length of output: 50387
🌐 Web query:
"forklift-naa-oui-map ConfigMap namespace MTV openshift-mtv"
💡 Result:
The forklift-naa-oui-map ConfigMap is a configuration resource used in the Migration Toolkit for Virtualization (MTV) to define custom Network Address Authority (NAA) to vendor mappings [1][2]. This mechanism allows administrators to disambiguate RDM (Raw Device Mapping) storage devices by mapping specific NAA prefixes to their corresponding storage vendors without requiring a rebuild of the forklift controller [1][3]. Key details regarding this ConfigMap include: Namespace Requirement The forklift-naa-oui-map ConfigMap must be created in the same namespace where the MTV Operator is deployed, which is typically openshift-mtv [4][5]. Purpose and Function It enables manual configuration of NAA vendor prefixes, which is particularly useful for identifying storage backends in environments with multiple storage arrays (e.g., multi-array RDM scenarios) [1][2]. By providing these mappings, the MTV controller can perform longest-common-prefix matching to correctly resolve storage provider mappings for RDM disks [1][6]. Recent Changes In recent updates to the Forklift project, the management of this ConfigMap has been refined [7]. Specifically, the automated template deployment (configmap-naa-oui-map.yml.j2) was removed from the operator deployment to emphasize the use of user-defined overrides for these mappings [7]. Administrators are expected to manage this ConfigMap directly in the operator namespace to ensure the controller utilizes the intended custom vendor definitions [1].
Citations:
- 1: MTV-5738 | Add multi-array RDM disambiguation and configurable NAA prefixes forklift#6988
- 2: kubev2v/forklift@1ce1ab2
- 3: kubev2v/forklift@ff8b72b
- 4: https://docs.redhat.com/en/documentation/migration_toolkit_for_virtualization/2.10/html/planning_your_migration_to_red_hat_openshift_virtualization/assembly_installing-mtv-operator_mtv
- 5: https://developers.redhat.com/learning/learn:openshift:get-started-migration-toolkit-for-virtualization/resource/learn:openshift:get-started-migration-toolkit-for-virtualization-prerequisites-and-step-step-guide
- 6: kubev2v/forklift@6e25ab0
- 7: kubev2v/forklift@f76f113
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Look for exact namespace wording around the ConfigMap in the repo
rg -n -C 2 "forklift-naa-oui-map|configmap-naa-oui-map|openshift-mtv|same namespace|operator namespace|{namespace}" documentationRepository: kubev2v/forklift-documentation
Length of output: 437
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Search with escaped braces and targeted terms
rg -n -C 2 'forklift-naa-oui-map|configmap-naa-oui-map|openshift-mtv|same namespace|operator namespace|\{namespace\}' documentation/modules
printf '\n=== specific install namespace definitions ===\n'
rg -n -C 2 'openshift-mtv|\{namespace\}|project-short is installed|operator' documentation/modules/proc_installing-mtv-operator.adoc documentation/modules/ref_* documentation/modules/proc_*Repository: kubev2v/forklift-documentation
Length of output: 50387
🌐 Web query:
"forklift-naa-oui-map openshift-mtv namespace same namespace MTV operator"
💡 Result:
The forklift-naa-oui-map ConfigMap is used in the Migration Toolkit for Virtualization (MTV) to allow administrators to define custom Network Address Authority (NAA) to vendor mappings, which assists in resolving storage provider issues for Raw Device Mapping (RDM) disks [1][2]. To function correctly, this ConfigMap must be deployed in the same namespace where the MTV Operator is installed (typically the openshift-mtv namespace) [3][4][5]. Key technical context: 1. Purpose: It supports multi-array RDM disambiguation by enabling admins to provide custom OUI (Organizationally Unique Identifier) prefixes that the Forklift controller uses to map storage device NAAs to the correct vendor [1][2]. 2. Requirement: Similar to other configuration maps used by the MTV operator—such as forklift-vsphere-osmap or forklift-ovirt-osmap—the forklift-naa-oui-map must reside in the operator's deployment namespace to be accessible to the controller [1][3][5]. 3. Deployment Note: While earlier versions included templates for such maps, recent updates have moved toward manual administration via ConfigMap overrides to provide flexibility without requiring operator rebuilds [1][6][7]. Always ensure that any custom ConfigMap names used to override defaults are correctly referenced within the ForkliftController custom resource if required by your specific MTV version [3][5].
Citations:
- 1: MTV-5738 | Add multi-array RDM disambiguation and configurable NAA prefixes forklift#6988
- 2: kubev2v/forklift@6e25ab0
- 3: https://docs.redhat.com/en/documentation/migration_toolkit_for_virtualization/2.11/html/planning_your_migration_to_red_hat_openshift_virtualization/assembly_installing-mtv-operator_mtv
- 4: https://developers.redhat.com/learning/learn:openshift:get-started-migration-toolkit-for-virtualization/resource/learn:openshift:get-started-migration-toolkit-for-virtualization-prerequisites-and-step-step-guide
- 5: https://docs.redhat.com/documentation/migration_toolkit_for_virtualization/2.11/html/planning_your_migration_to_red_hat_openshift_virtualization/assembly_installing-mtv-operator_mtv
- 6: kubev2v/forklift@f76f113
- 7: kubev2v/forklift@1ce1ab2
Use {namespace} for the ConfigMap location
documentation/modules/proc_configuring-naa-oui-map.adoc#L21-L38: replace<namespace>with +{namespace}+ in both theoc editcommand and the manifest.documentation/modules/ref_troubleshooting-storage-copy-offload.adoc#L30-L32: state that theforklift-naa-oui-mapConfigMap must be created in +{namespace}+, matching the install docs.
📍 Affects 2 files
documentation/modules/proc_configuring-naa-oui-map.adoc#L17-L18(this comment)documentation/modules/proc_configuring-naa-oui-map.adoc#L28-L28documentation/modules/ref_troubleshooting-storage-copy-offload.adoc#L30-L32
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@documentation/modules/proc_configuring-naa-oui-map.adoc` around lines 17 -
18, Use the {namespace} attribute consistently for the forklift-naa-oui-map
ConfigMap location. In documentation/modules/proc_configuring-naa-oui-map.adoc
lines 17-18 and 28, replace <namespace> with +{namespace}+ in both the oc edit
command and manifest; in
documentation/modules/ref_troubleshooting-storage-copy-offload.adoc lines 30-32,
state that the ConfigMap must be created in +{namespace}+.
| . Create or edit the `forklift-naa-oui-map` ConfigMap: | ||
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ oc edit configmap forklift-naa-oui-map -n <namespace> | ||
| ---- |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Do not use oc edit for the “create” path.
oc edit configmap ... fails when forklift-naa-oui-map does not already exist, so the step cannot perform the advertised “create or edit” operation. Provide a creation command or manifest/application path, and retain oc edit only for the existing-ConfigMap case.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@documentation/modules/proc_configuring-naa-oui-map.adoc` around lines 21 -
26, Update the ConfigMap instructions to separate creation from editing: provide
a valid command or manifest/application path that creates forklift-naa-oui-map
when it does not exist, and retain oc edit configmap only for modifying an
existing ConfigMap.
| // Info needed: How long does it take for the controller to pick up ConfigMap changes? Is there a way to verify that the new mappings are active? | ||
|
|
||
| .Verification | ||
|
|
||
| // Info needed: What is the recommended way to verify that custom NAA-to-vendor mappings are working correctly? Are there logs to check or a test procedure to follow? |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n## proc_configuring-naa-oui-map.adoc\n'
sed -n '1,140p' documentation/modules/proc_configuring-naa-oui-map.adoc | cat -n
printf '\n## ref_troubleshooting-storage-copy-offload.adoc\n'
sed -n '1,140p' documentation/modules/ref_troubleshooting-storage-copy-offload.adoc | cat -n
printf '\n## search related terms\n'
rg -n "NAA|ConfigMap|controller|copy offload|verification|log" documentation/modules -SRepository: kubev2v/forklift-documentation
Length of output: 50386
Document one concrete validation path for custom NAA mappings
documentation/modules/proc_configuring-naa-oui-map.adoc#L54-L58: add the exactoc/log check that shows the controller picked upforklift-naa-oui-mapand the new mapping is active.documentation/modules/ref_troubleshooting-storage-copy-offload.adoc#L22-L22and#L36-L38: add the expected NAA-matching failure symptoms plus the log message or status signal users should look for when custom mappings are not applied.
📍 Affects 2 files
documentation/modules/proc_configuring-naa-oui-map.adoc#L54-L58(this comment)documentation/modules/ref_troubleshooting-storage-copy-offload.adoc#L22-L22documentation/modules/ref_troubleshooting-storage-copy-offload.adoc#L36-L38
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@documentation/modules/proc_configuring-naa-oui-map.adoc` around lines 54 -
58, Document one concrete validation path for custom NAA mappings: in
documentation/modules/proc_configuring-naa-oui-map.adoc at lines 54-58, add the
exact oc command and controller-log check confirming forklift-naa-oui-map was
consumed and the new mapping is active; in
documentation/modules/ref_troubleshooting-storage-copy-offload.adoc at lines 22
and 36-38, document the expected NAA-matching failure symptoms and the log
message or status signal indicating custom mappings were not applied.
| {project-short} automatically resolves storage mapping when multiple storage arrays from the same vendor are present. When a storage map contains multiple destination candidates for a single vendor, {project-short} uses Network Address Authority (NAA) identifier matching to determine the correct target datastore. | ||
|
|
||
| The system matches the Raw Device Mapping (RDM) disk's NAA identifier with the backing device NAA identifiers of candidate datastores using longest-common-prefix logic. This ensures that each disk is paired with the correct storage array without manual intervention. | ||
|
|
There was a problem hiding this comment.
@bodnopoz : Does this NAA matching apply only to RDM disks, or does it also work with VMDK files? Are there any disk types that are excluded from this automatic matching?
| * Disks distributed across multiple storage arrays from the same vendor | ||
| * Disks distributed across multiple storage arrays from different vendors | ||
| * Mixed storage array configurations in a single migration plan | ||
|
|
There was a problem hiding this comment.
@bodnopoz: Are there any limitations on mixing different storage vendors in a single migration plan? For example, can you have some disks on Dell PowerMax and others on Pure Storage FlashArray in the same VM migration?
|
|
||
| * Multiple OUI prefixes per vendor (for example, Dell EMC Symmetrix and VMAX prefixes are both recognized under PowerMax) | ||
| * Support for both standard NAA hexadecimal formats and VML (vSphere Managed Object) formats | ||
|
|
There was a problem hiding this comment.
@bodnopoz What is the complete list of supported storage vendors and their OUI prefixes? This information would be helpful for users planning migrations.
| ---- | ||
| + | ||
| // Info needed: What is the exact format for the vendor_name value? Should it match specific strings from a predefined list, or can it be any descriptive string? Are there naming conventions to follow? | ||
|
|
There was a problem hiding this comment.
@bodnopoz What is the exact format for the vendor_name value? Should it match specific strings from a predefined list, or can it be any descriptive string? Are there naming conventions to follow?
| . Save the ConfigMap. | ||
| + | ||
| The {project-short} controller automatically detects the ConfigMap changes and applies the new mappings without requiring a restart. | ||
|
|
There was a problem hiding this comment.
@bodnopoz How long does it take for the controller to pick up ConfigMap changes? Is there a way to verify that the new mappings are active?
| // Info needed: How long does it take for the controller to pick up ConfigMap changes? Is there a way to verify that the new mappings are active? | ||
|
|
||
| .Verification | ||
|
|
There was a problem hiding this comment.
@bodnopoz What is the recommended way to verify that custom NAA-to-vendor mappings are working correctly? Are there logs to check or a test procedure to follow?
| * The storage arrays are properly configured and accessible. | ||
| * The NAA identifiers are correctly reported by the storage arrays. | ||
| * If using custom vendor mappings, the `forklift-naa-oui-map` ConfigMap is correctly configured. | ||
|
|
There was a problem hiding this comment.
@bodnopoz What are the specific error messages that users might see if NAA matching fails? What logs should they check? What are the common causes of NAA matching failures?
|
|
||
| . Verify that the ConfigMap changes have been picked up by the controller. | ||
| + | ||
| // Info needed: What logs should users check to verify that the ConfigMap was loaded? What is the log message that confirms the custom mappings are active? |
There was a problem hiding this comment.
@bodnopoz What logs should users check to verify that the ConfigMap was loaded? What is the log message that confirms the custom mappings are active?
This update documents the new multi-array Raw Device Mapping (RDM) support feature for storage copy offload migrations. The feature enables migration of VMs with up to 60 disks across multiple storage arrays from the same or different vendors. Key changes: - Add concept module explaining multi-array RDM support and NAA-based disambiguation logic - Add procedure for configuring custom NAA-to-vendor mappings via ConfigMap - Update storage map documentation to reference multi-array capability - Add troubleshooting guidance for ambiguous storage mapping errors and ConfigMap configuration issues - Integrate new modules into VMware planning assembly The documentation includes placeholders marked with "Info needed" comments for missing technical details that require input from development or product management. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
dfe9e55 to
4bd74f3
Compare
1 participant
MTV 2.12.x
This PR resolves https://redhat.atlassian.net/browse/MTV-6116 by adding documentation for multi-array Raw Device Mapping (RDM) support in storage copy offload migrations.
Key features documented:
Documentation changes:
Files changed:
documentation/modules/con_multi-array-rdm-support.adoc(new)documentation/modules/proc_configuring-naa-oui-map.adoc(new)documentation/modules/con_about-storage-maps.adoc(modified)documentation/modules/proc_creating-form-based-storage-maps-ui-vmware.adoc(modified)documentation/modules/ref_troubleshooting-storage-copy-offload.adoc(modified)documentation/doc-Planning_your_migration/assemblies/assembly_planning-migration-vmware.adoc(modified)Note: Documentation includes "Info needed" placeholders for missing technical details. See
MTV-6116_MISSING_INFO.txtin local repo (not included in PR) for complete list of questions requiring SME input.🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Documentation