Update how-to-validate-cables.md

1 - Include information on Uknown/Not-connected should be validated
2 - Include BOM link
3 - Add Troubleshooting failures (Storage SAS URL missing or Token expired, Ports speed/cable model issues, Unknown types but should be compliant
4 - HTML conversion

Author: bartpinto

articles/operator-nexus/how-to-validate-cables.md

@@ -13,14 +13,32 @@ ms.date: 04/15/2024
 
 This article explains the  Fabric cable validation, where the primary function of the diagnostic API is to check all fabric devices for potential cabling issues. The Diagnostic API assesses whether the interconnected devices adhere to the Bill of Materials (BOM), classifying them as compliant or noncompliant. The results are presented in a JSON format, encompassing details such as validation status, errors, identifier type, and neighbor device ID. These results are stored in a customer-provided Storage account. It's vital to the overall deployment that errors identified in this report are resolved before moving onto the Cluster deployment step.
 
+For BOM details, refer to [Azure Operator Nexus SKUs](./reference-operator-nexus-skus.md)
+
 ## Prerequisites
 
 - Ensure the Nexus Network Fabric is successfully provisioned.
 - Provide the Network Fabric ID and storage URL with WRITE access via a support ticket.
+- The storage account has these prerequisites:
+  - The storage account must be in a different Azure region than the Network Fabric Azure region.
+  - `Storage Blob Data Contributor` role must be assigned to the `Nexus Network Fabric RP` with access assigned to the storage account.
+- Microsoft Support must patch the Nexus Network Fabric with an active storage SAS URL before running cabling validation.
 
 > [!NOTE]
 > The Storage URL (SAS) is short-lived. By default, it is set to expire in eight hours. If the SAS URL expires, then the fabric must be re-patched.
 
+## Generate the storage URL
+
+Refer to [Create a container](../storage/blobs/blob-containers-portal.md#create-a-container) to create a container.  
+
+> [!NOTE]
+> Enter the name of the container using only lowercase letters.
+
+Refer to [Generate a shared access signature](../storage/blobs/blob-containers-portal.md#generate-a-shared-access-signature) to create the SAS URL of the container. Provide Write permission for SAS.
+
+> [!NOTE]
+> SAS URLs are short lived. By default, it is set to expire in eight hours. If the SAS URL expires, then you must open a Microsoft support ticket to add a new URL.
+
 ## Validate cabling
 
 1. Execute the following Azure CLI command:
@@ -29,25 +47,40 @@ This article explains the  Fabric cable validation, where the primary function o
     az networkfabric fabric validate-configuration –resource-group "<NFResourceGroupName>" --resource-name "<NFResourceName>" --validate-action "Cabling" --no-wait --debug  
     ```
 
-    The following (truncated) output appears. Copy the URL through **private preview**. This portion of the URL is used in the following step to check the status of the operation.
+    The following (truncated) output appears. Copy the URL from the `Azure-AsyncOperation` section of the debug output. This portion of the URL is used in the following step to check the status of the operation.
 
     ```azurecli
-    https://management.azure.com/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/providers/Microsoft.ManagedNetworkFabric/locations/EASTUS2EUAP/operationStatuses/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e*A9E6DB3DF5C58D67BD395F7A608C056BC8219C392CC1CE0AD22E4C36D70CEE5C?api-version=2022-01-15-privatepreview&t=638485032018035520&c=MIIHHjCCBgagAwIBAgITfwKWMg6goKCq4WwU2AAEApYyDjANBgkqhkiG9w0BAQsFADBEMRMwEQYKCZImiZPyLGQBGRYDR0JMMRMwEQYKCZImiZPyLGQBGRYDQU1FMRgwFgYDVQQDEw9BTUUgSW5mcmEgQ0EgMDIwHhcNMjQwMTMwMTAzMDI3WhcNMjUwMTI0MTAzMDI3WjBAMT4wPAYDVQQDEzVhc3luY29wZXJhdGlvbnNpZ25pbmdjZXJ0aWZpY2F0ZS5tYW5hZ2VtZW50LmF6dXJlLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALMk1pBZQQoNY8tos8XBaEjHjcdWubRHrQk5CqKcX3tpFfukMI0_PVZK-Kr7xkZFQTYp_ItaM2RPRDXx-0W9-mmrUBKvdcQ0rdjcSXDek7GvWS29F5sDHojD1v3e9k2jJa4cVSWwdIguvXmdUa57t1EHxqtDzTL4WmjXitzY8QOIHLMRLyXUNg3Gqfxch40cmQeBoN4rVMlP31LizDfdwRyT1qghK7vgvworA3D9rE00aM0n7TcBH9I0mu-96JE0gSX1FWXctlEcmdwQmXj_U0sZCu11_Yr6Oa34bmUQHGc3hDvO226L1Au-QsLuRWFLbKJ-0wmSV5b3CbU1kweD5LUCAwEAAaOCBAswggQHMCcGCSsGAQQBgjcVCgQaMBgwCgYIKwYBBQUHAwEwCgYIKwYBBQUHAwIwPQYJKwYBBAGCNxUHBDAwLgYmKwYBBAGCNxUIhpDjDYTVtHiE8Ys-
+    cli.azure.cli.core.sdk.policies:     'Azure-AsyncOperation': '<Azure-AsyncOperation-endpoint url>'
+    ```
 
+    If the following error is returned, this typically indicates the Fabric has not been patched with a valid SAS URL:
+    ```azurecli
+    azure.core.exceptions.HttpResponseError: Operation returned an invalid status 'OK'
     ```
 
 1. You can programmatically check the status of the operation by running the following command:
 
     ```azurecli
     az rest -m get -u "<Azure-AsyncOperation-endpoint url>" 
+    {
+      "endTime": "<OPERATION_COMPLETION_TIME>",
+      "id": "<OPERATION_ID>",
+      "name": "OPERATION_NAME",
+      "properties": {
+        "url": "CABLING_REPORT_STORAGE_URL"
+      },
+      "resourceId": "<FABRIC_RID>",
+      "startTime": "<OPERATION_START_TIME>",
+      "status": "Succeeded"
+    }
     ```
 
     The operation status indicates if the API succeeded or failed.
 
     > [!NOTE]
     > The operation takes roughly 20~40 minutes to complete based on the number of racks.  
 
-1. Download and read the validated results from the storage URL.
+1. Download and read the validated results from the `<CABLING_REPORT_STORAGE_URL>` retuned from the completed command.
 
 Example output is shown in the following sections.
 
@@ -161,8 +194,8 @@ networkFabricInfoSkuId": "M8-A400-A100-C16-ab",
 |Status Type  |Definition  |
 |---------|---------|
 |Compliant     | When the status is compliant with the BOM specification         |
-|Non-Compliant     | When the status isn't compliant with the BOM specification         |
-|Unknown     | When the status is unknown         |
+|NonCompliant     | When the status isn't compliant with the BOM specification         |
+|Unknown     | When the tool is unable to retrieve interface connection details or lldp data. This can occur when destintation device is powered off, missing or disconnected cables or if validation is not supported for this interface type.         |
 
 #### Validation attributes
 
@@ -177,19 +210,24 @@ networkFabricInfoSkuId": "M8-A400-A100-C16-ab",
 
 ## Known issues and limitations in cable validation
 
-- Post Validation Connections between TORs and Compute Servers isn't supported.
-- Cable Validation for NPB isn't supported because there's no support for "show lldp neighbors" from Arista.  
+- Cable Validation of connections between TORs and Compute Servers that are powered off or unprovisioned in the Nexus cluster are not supported. These interfaces will show `Unknown` status in the report.
+- Cable Validation of connections between MGMT interfaces and Compute Servers that are powered off or unprovisioned in the Nexus cluster or the Compute Server Controllers are not supported. These interfaces will show `Unknown` status in the report.
+- Cable Validation for NPB isn't supported for `loopback` and `nni-direct` interfaces because there is no vendor support currently for `show lldp neighbors`. These interfaces will show `Unknown` status in the report.
 - The Storage URL must be in a different region from the Network Fabric. For instance, if the Fabric is hosted in East US, the storage URL should be outside of East US.
-- Cable validation supports both four rack and eight rack BOMs.
-
-## Generate the storage URL
+- Cable validation supports both four rack wih 16 Computes per rack and eight rack wih 16 Computes per rack BOMs.
+- When destintation device is powered off, cables are missing or disconnected, or if validation is not supported for the interface type, then the inteface will show `Unknown` status. **It is important to evaluate all `Unknown` interfaces that are `Not-Connected` against the BOM to determine if repair action is required.**
 
-Refer to [Create a container](../storage/blobs/blob-containers-portal.md#create-a-container) to create a container.  
+## Typical cable validation `NonCompliant` and `Unknown` Issues
 
-> [!NOTE]
-> Enter the name of the container using only lowercase letters.
+|validationType |Status |Error  |Resolution  |
+|---------------|-------|-------|------------|
+| CableValidation |`NonCompliant`|`Device cable connection is incorrect.` | Verify connections on the source and destination interfaces match the BOM. The `deviceConfiguration` can help identify the destination port date returned on the interface. |
+| CableValidation |`Unknown`     |`Unable to fetch data from the device.` | Verify connections on the source and destination interfaces are connected and match the BOM |
+| CableValidation |`NonCompliant`|`Device cabling in <INTERFACE> incorrect.` | The interface is not connected. Verify connections on the source and destination interfaces are connected  match the BOM. |
+| CableValidation  |`Unknown`     |`Port <INTERFACE> has no connections as per device response.` | Verify connections on the source and destination interfaces are connected and match the BOM |
+| CableSpecificationValidation  |`Unknown`     |`Unable to fetch Interface Status for <INTERFACE>.` | Verify connections on the source and destination interfaces are connected and match the BOM |
+| CableSpecificationValidation  |`NonCompliant`     |`Device cable connection is incorrect` | Verify interface card and cables match BOM specification in this <INTERFACE>.|
 
-Refer to [Generate a shared access signature](../storage/blobs/blob-containers-portal.md#generate-a-shared-access-signature) to create the SAS URL of the container. Provide Write permission for SAS.
+## Converting cabling validation report to html format
 
-> [!NOTE]
-> ESAS URLs are short lived. By default, it is set to expire in eight hours. If the SAS URL expires, then you must open a Microsoft support ticket to add a new URL.
+Sample python script to convert cabling validation report JSON output to html: [cable-html.py](media/cable-html.py)