|
| 1 | +--- |
| 2 | +title: "Task 12: Install FC HBA Drivers (Conditional)" |
| 3 | +sidebar_label: "Task 12: FC HBA Drivers" |
| 4 | +sidebar_position: 12 |
| 5 | +description: "Install Fibre Channel HBA drivers on Azure Local nodes for SAN disaggregated deployments" |
| 6 | +category: "Runbook" |
| 7 | +scope: "FC HBA driver installation for SAN deployments" |
| 8 | +purpose: "Install and verify FC HBA drivers so nodes can present WWPNs to the FC fabric before zoning" |
| 9 | +author: "Azure Local Cloud" |
| 10 | +created: 2026-05-02 |
| 11 | +updated: 2026-05-02 |
| 12 | +version: "1.0.0" |
| 13 | +tags: |
| 14 | + - azure-local |
| 15 | + - cluster-deployment |
| 16 | + - os-configuration |
| 17 | + - san |
| 18 | + - fibre-channel |
| 19 | +keywords: |
| 20 | + - FC HBA |
| 21 | + - Fibre Channel |
| 22 | + - HBA drivers |
| 23 | + - WWPN |
| 24 | + - SAN |
| 25 | +status: "Active" |
| 26 | +--- |
| 27 | + |
| 28 | +import Tabs from '@theme/Tabs'; |
| 29 | +import TabItem from '@theme/TabItem'; |
| 30 | + |
| 31 | +# Task 12: Install FC HBA Drivers (Conditional) |
| 32 | + |
| 33 | +[](./index.mdx) |
| 34 | +[](./index.mdx) |
| 35 | +[](https://learn.microsoft.com/en-us/azure-stack/hci/) |
| 36 | + |
| 37 | +> **DOCUMENT CATEGORY**: Runbook |
| 38 | +> **SCOPE**: FC HBA driver installation |
| 39 | +> **PURPOSE**: Install and verify FC HBA drivers so nodes present WWPNs to the FC fabric |
| 40 | +> **MASTER REFERENCE**: [Microsoft Learn — Prepare hardware for Azure Local SAN deployment](https://learn.microsoft.com/en-us/azure/azure-local/plan/fiber-channel-no-backup-disaggregated-pattern?view=azloc-2604) |
| 41 | +
|
| 42 | +**Status**: Active |
| 43 | + |
| 44 | +:::info Skip this task if deploying Storage Spaces Direct (S2D) |
| 45 | +This task applies only to **disaggregated SAN deployments**. If you are deploying with Storage Spaces Direct (hyperconverged), skip to [Task 15: Complete Combined Script](./task-15-complete-combined-script-all-steps.mdx). |
| 46 | +::: |
| 47 | + |
| 48 | +## Overview |
| 49 | + |
| 50 | +Azure Local disaggregated deployments require Fibre Channel Host Bus Adapters (HBAs) in each node. Before zoning can be configured in the FC fabric, the HBA drivers must be installed and WWPNs collected. This task installs vendor-provided drivers and records each node's WWPN for FC fabric zoning. |
| 51 | + |
| 52 | +--- |
| 53 | + |
| 54 | +## When to Run |
| 55 | + |
| 56 | +| Scenario | Run? | |
| 57 | +|---|---| |
| 58 | +| SAN disaggregated deployment | ✅ Yes — all nodes | |
| 59 | +| Storage Spaces Direct (S2D) deployment | ❌ Skip | |
| 60 | +| HBA drivers already installed from OEM image | ✅ Yes — verify and collect WWPNs | |
| 61 | + |
| 62 | +--- |
| 63 | + |
| 64 | +## Prerequisites |
| 65 | + |
| 66 | +| Requirement | Details | |
| 67 | +|---|---| |
| 68 | +| Tasks 01–11 complete | Nodes named, storage cleaned | |
| 69 | +| HBA hardware installed | FC HBAs seated in PCIe slots on all nodes | |
| 70 | +| HBA vendor driver package | Download from your HBA vendor (Emulex, QLogic, Broadcom, Marvell, etc.) | |
| 71 | +| FC fabric access | Fabric admin ready to configure zoning after WWPN collection | |
| 72 | + |
| 73 | +--- |
| 74 | + |
| 75 | +## Variables from variables.yml |
| 76 | + |
| 77 | +| Path | Type | Description | |
| 78 | +|------|------|-------------| |
| 79 | +| `cluster_nodes[].management_ip` | string | PSRemoting target IP (orchestrated mode) | |
| 80 | +| `cluster_nodes[].hostname` | string | Node display name for logging | |
| 81 | +| `cluster_nodes[].fc_hba[].wwpn` | string | Record here after collection — used for FC zoning | |
| 82 | + |
| 83 | +--- |
| 84 | + |
| 85 | +## Execution Options |
| 86 | + |
| 87 | +<Tabs groupId="deployment-method"> |
| 88 | +<TabItem value="direct" label="Direct (On Node)" default> |
| 89 | + |
| 90 | +Run on each node individually via console, RDP, or PSRemoting. |
| 91 | + |
| 92 | +**Toolkit script:** `scripts/deploy/04-cluster-deployment/phase-03-os-configuration/task-12-install-fc-hba-drivers-conditional/powershell/Install-FcHbaDrivers-Direct.ps1` |
| 93 | + |
| 94 | +```powershell |
| 95 | +# Task 12 - Install FC HBA Drivers (run on each node) |
| 96 | +# Consult your HBA vendor documentation for the correct .inf driver path |
| 97 | +
|
| 98 | +# Stage 1: Install driver via PnP |
| 99 | +# Replace <path-to-driver.inf> with the vendor-provided INF file path |
| 100 | +PNPUTIL /add-driver "<path-to-driver.inf>" /install |
| 101 | +
|
| 102 | +# Stage 2: Confirm HBA ports are detected |
| 103 | +Get-InitiatorPort | Select-Object NodeAddress, PortAddress, ConnectionType | |
| 104 | + Where-Object { $_.ConnectionType -eq 'Fibre Channel' } | |
| 105 | + Format-Table -AutoSize |
| 106 | +
|
| 107 | +# Stage 3: Record WWPNs for each node (save to variables.yml) |
| 108 | +# PortAddress field contains the WWPN in XX:XX:XX:XX:XX:XX:XX:XX format |
| 109 | +Get-InitiatorPort | Where-Object { $_.ConnectionType -eq 'Fibre Channel' } | |
| 110 | + Select-Object @{N='Node';E={$env:COMPUTERNAME}}, NodeAddress, PortAddress | |
| 111 | + Export-Csv -Path "C:\Temp\wwpn-$env:COMPUTERNAME.csv" -NoTypeInformation |
| 112 | +``` |
| 113 | + |
| 114 | +</TabItem> |
| 115 | +<TabItem value="orchestrated" label="Orchestrated Script"> |
| 116 | + |
| 117 | +Run from the management server against all nodes. |
| 118 | + |
| 119 | +**Toolkit script:** `scripts/deploy/04-cluster-deployment/phase-03-os-configuration/task-12-install-fc-hba-drivers-conditional/powershell/Invoke-FcHbaDrivers-Orchestrated.ps1` |
| 120 | + |
| 121 | +```powershell |
| 122 | +# Task 12 - Install FC HBA Drivers (orchestrated) |
| 123 | +# variables.yml: cluster_nodes[].management_ip -> $ServerList |
| 124 | +
|
| 125 | +$ConfigPath = "$env:USERPROFILE\variables.yml" |
| 126 | +$ServerList = (Get-Content $ConfigPath | Select-String 'management_ip:\s+"?([^"'' ]+)' | |
| 127 | + ForEach-Object { $_.Matches[0].Groups[1].Value.Trim() }) |
| 128 | +
|
| 129 | +# Collect WWPNs from all nodes |
| 130 | +Invoke-Command -ComputerName $ServerList -ScriptBlock { |
| 131 | + Get-InitiatorPort | Where-Object { $_.ConnectionType -eq 'Fibre Channel' } | |
| 132 | + Select-Object @{N='Node';E={$env:COMPUTERNAME}}, NodeAddress, PortAddress |
| 133 | +} | Sort-Object Node | Format-Table -AutoSize |
| 134 | +``` |
| 135 | + |
| 136 | +> **Note:** Driver installation requires staging the vendor INF to each node before running. Consult your HBA vendor documentation for the driver package appropriate to the installed HBA model. |
| 137 | +
|
| 138 | +</TabItem> |
| 139 | +<TabItem value="standalone" label="Standalone Script"> |
| 140 | + |
| 141 | +> **When to use**: Use this option for a self-contained deployment without a shared configuration file. |
| 142 | +
|
| 143 | +**Script**: See [`azurelocal-toolkit`](https://github.com/AzureLocal/azurelocal-toolkit) → `scripts/deploy/` for the standalone script for this task. |
| 144 | + |
| 145 | +:::note Content Pending |
| 146 | +Standalone script content references the toolkit repository. See the Orchestrated Script tab for the primary implementation. |
| 147 | +::: |
| 148 | + |
| 149 | +</TabItem> |
| 150 | +</Tabs> |
| 151 | + |
| 152 | +--- |
| 153 | + |
| 154 | +## Validation |
| 155 | + |
| 156 | +```powershell |
| 157 | +# Confirm HBA ports are online and WWPNs visible |
| 158 | +$ServerList = @("<node1-ip>", "<node2-ip>") |
| 159 | +Invoke-Command -ComputerName $ServerList -ScriptBlock { |
| 160 | + Get-InitiatorPort | Where-Object { $_.ConnectionType -eq 'Fibre Channel' } | |
| 161 | + Select-Object @{N='Node';E={$env:COMPUTERNAME}}, PortAddress, ConnectionType, OperationalStatus |
| 162 | +} | Sort-Object Node | Format-Table -AutoSize |
| 163 | +``` |
| 164 | + |
| 165 | +**Expected:** Each node shows 1–4 FC initiator ports depending on HBA count. `OperationalStatus` should be `Online` once fabric-connected. |
| 166 | + |
| 167 | +--- |
| 168 | + |
| 169 | +## WWPN Collection Worksheet |
| 170 | + |
| 171 | +| Node | HBA Port | WWPN | Fabric (A/B) | |
| 172 | +|------|----------|------|--------------| |
| 173 | +| NODE01 | Port 0 | ___________________________ | A | |
| 174 | +| NODE01 | Port 1 | ___________________________ | B | |
| 175 | +| NODE02 | Port 0 | ___________________________ | A | |
| 176 | +| NODE02 | Port 1 | ___________________________ | B | |
| 177 | + |
| 178 | +:::note Provide WWPNs to FC Fabric Admin |
| 179 | +Once WWPNs are collected, provide them to the FC fabric administrator for zoning configuration. Zoning must be completed **after** Arc registration (Phase 04) — the storage array's port WWPNs are needed to complete the zone configuration. |
| 180 | +::: |
| 181 | + |
| 182 | +--- |
| 183 | + |
| 184 | +## Rolling Reboot (if required) |
| 185 | + |
| 186 | +Driver installation may require a node restart. In a cluster, reboot one node at a time to maintain availability: |
| 187 | + |
| 188 | +```powershell |
| 189 | +# Drain and reboot one node at a time |
| 190 | +Suspend-ClusterNode -Name "<NodeName>" -Drain |
| 191 | +# Wait for roles to migrate |
| 192 | +Restart-Computer -ComputerName "<node-ip>" -Force |
| 193 | +# Wait for node to rejoin |
| 194 | +Resume-ClusterNode -Name "<NodeName>" |
| 195 | +``` |
| 196 | + |
| 197 | +For initial pre-cluster deployment (Phase 03), simply reboot each node and confirm the OS comes back online. |
| 198 | + |
| 199 | +--- |
| 200 | + |
| 201 | +## Validation Checklist |
| 202 | + |
| 203 | +- [ ] HBA drivers installed on all nodes |
| 204 | +- [ ] FC initiator ports visible (`Get-InitiatorPort` shows Fibre Channel ports) |
| 205 | +- [ ] WWPNs collected and recorded in `variables.yml` under `cluster_nodes[].fc_hba[].wwpn` |
| 206 | +- [ ] WWPN list provided to FC fabric administrator |
| 207 | + |
| 208 | +--- |
| 209 | + |
| 210 | +## Navigation |
| 211 | + |
| 212 | +[← Task 11: Clear Storage](./task-11-clear-previous-storage-configuration-conditional.mdx) · [↑ Phase 03](./index.mdx) · [Task 13: Configure MPIO →](./task-13-configure-mpio-and-vendor-msdsm-conditional.mdx) |
| 213 | + |
| 214 | +--- |
| 215 | + |
| 216 | +## Version Control |
| 217 | + |
| 218 | +| Version | Date | Author | Changes | |
| 219 | +|---------|------|--------|---------| |
| 220 | +| 1.0.0 | 2026-05-02 | Azure Local Cloud | Initial release | |
0 commit comments