Documentation Improvement Request for VMware ESXi iSCSI MPIO Configuration

Real-life scenario:
We deployed VMware vSphere ESXi on IBM Cloud Bare Metal Servers and mounted IBM Cloud Block Storage via iSCSI for datastore usage. During the setup, we followed the official documentation for MPIO configuration. However, the instructions were unclear and incomplete, which led to incorrect configurations on some ESXi hosts.

Problem statement / Pain points:

• The documentation only explains how to configure one iSCSI target address, while two are required for proper MPIO.

• No screenshots are provided, making the steps difficult to follow.

• There is no guidance on correcting configurations where both static and dynamic discovery methods were used, which can cause performance degradation.

Current workaround(s):

• We manually researched VMware best practices and adjusted configurations host by host.

• This process is time-consuming and error-prone, especially for environments with multiple ESXi hosts.

Proposed solution(s):

• Update the documentation to include:

  1. Clear steps for configuring both iSCSI target addresses for MPIO.

  2. Screenshots for each step to avoid confusion.

  3. Guidance on correcting configurations where both static and dynamic discovery were used, as per the note:
     “Do not configure an iSCSI target to be discovered by both static and dynamic device discovery methods. The consequence of using redundant discovery methods might be slow performance when the initiator is communicating with the iSCSI target device.”

Benefits / Value:

• Reduces configuration errors and improves performance.

• Saves time for administrators by providing clear, accurate instructions.

• Enhances customer experience and trust in IBM Cloud documentation.

# of users impacted and frequency:

• Impacted users: VMware ESXi administrators using IBM Cloud Block Storage (hundreds globally).

• Frequency: Every time new ESXi hosts are deployed or storage is reconfigured (common in enterprise environments).