cosmos-explorer/scripts/README.md

Cosmos DB Connectivity Diagnostic Script - README

Overview

This is a standalone PowerShell diagnostic script that captures network connectivity, private endpoint configuration, and Azure RBAC status for Cosmos DB accounts. It's designed to be run locally on a customer's machine to help troubleshoot HTTP 0.0 and connection errors.

Key Features:

• ✅ DNS resolution verification
• ✅ TCP 443 connectivity testing
• ✅ HTTPS reachability probe
• ✅ Private endpoint detection
• ✅ Private network route analysis
• ✅ Azure CLI optional context (network config, RBAC)
• ✅ Structured JSON output for triage automation
• ✅ Sensitive data redaction for safe sharing
• ✅ Interactive and non-interactive modes

---

Quick Start

Prerequisites

• PowerShell 5.0+ (works on Windows, Linux, macOS)
• If querying Azure config: Azure CLI installed and authenticated (az login)
• Outbound network access to documents.azure.com

Option 1: Interactive Mode (Recommended for First Run)

Simplest approach—script prompts for inputs:

.\Diagnose-CosmosConnectivity.ps1 -Interactive

The script will display a guide showing where to find each input, then prompt:

• Endpoint URL
• Subscription ID
• Resource Group
• Account Name
• (Optional) Private Endpoint IP
• (Optional) VPN Subnet Range

Option 2: Non-Interactive Mode (Scripted/Automated)

Provide all parameters directly:

.\Diagnose-CosmosConnectivity.ps1 `
  -EndpointUrl "https://my-cosmos-account.documents.azure.com" `
  -SubscriptionId "12345678-1234-1234-1234-123456789012" `
  -ResourceGroup "my-resource-group" `
  -AccountName "my-cosmos-account"

Option 3: Non-Interactive with Redaction (Safe for Support)

Output JSON with sensitive data masked:

.\Diagnose-CosmosConnectivity.ps1 `
  -EndpointUrl "https://my-cosmos-account.documents.azure.com" `
  -SubscriptionId "12345678-1234-1234-1234-123456789012" `
  -ResourceGroup "my-resource-group" `
  -AccountName "my-cosmos-account" `
  -Redact

---

Detailed Usage

Getting Your Inputs

1. Endpoint URL (Required)

Location: Azure Portal → Cosmos DB Account → Overview

1. Go to Azure Portal
2. Search for "Cosmos DB"
3. Click your Cosmos DB account
4. Look for the "URI" field in the Overview tab
5. Copy the entire URL (e.g., https://my-cosmos-account.documents.azure.com)

Format: https://<account-name>.documents.azure.com (do NOT include trailing slash or :443/)

Note: If using a regional endpoint, use the primary endpoint. Private endpoints will have the same hostname with different IP resolution.

---

2. Subscription ID (Required)

Location: Azure Portal → Subscriptions or Portal → Home

1. Go to Azure Portal
2. Click on "Subscriptions" (or search for it)
3. Find your subscription
4. Copy the Subscription ID (looks like 12345678-1234-1234-1234-123456789012)

Alternative: From your Cosmos account page, look at the breadcrumb at the top or search box.

---

3. Resource Group (Required)

Location: Azure Portal → Cosmos DB Account (top-right corner)

1. Open your Cosmos DB account
2. At the top of the page, you'll see breadcrumbs
3. Look for "Resource group: " in the top-right
4. Or on the Overview page, find the "Resource group" field

Example: my-production-rg or cosmos-resources

---

4. Account Name (Required)

Location: Extract from endpoint URL or Azure Portal

From URL:

• Endpoint: https://my-cosmos-account.documents.azure.com
• Account Name: my-cosmos-account (the part before .documents.azure.com)

From Portal:

• Open Cosmos DB account → Look at the account name in the breadcrumb or page title

---

5. Private Endpoint IP (Optional but Recommended)

Location: Azure Portal → Cosmos DB Account → Private Endpoint Connections

1. Open your Cosmos DB account
2. Go to Settings → Private Endpoint Connections
3. If any connections exist, look for "Private IP address" column
4. Copy the IP (e.g., 10.123.171.30)

When to provide:

• If your Cosmos account has private endpoints configured
• Otherwise, leave blank (press Enter in interactive mode)

Format: 10.x.x.x, 172.16-31.x.x, or 192.168.x.x (RFC 1918 ranges)

---

6. VPN Subnet Range (Optional)

Location: Ask your network team or VPN client properties

If you're connecting via VPN, your network team should know your VPN subnet CIDR.

Example: 10.0.0.0/24 (network: 10.0.0.0–10.0.0.255)

When to provide:

• If you're behind a VPN
• If you suspect VPN routing is the issue
• Otherwise, leave blank

---

Understanding Output

Console Summary

After running, you'll see:

═════════════════════════════════════════════════════════════════════════════
DIAGNOSTIC COMPLETE
═════════════════════════════════════════════════════════════════════════════

Summary:
  DNS Resolution: ✓ PASS
  TCP Connectivity: ✗ FAIL
  Private Network: Detected (Private Endpoint)
  Classification: FAILURE - tcp_connectivity_blocked

Full report saved to: cosmos-diagnostic-20260513_143045.json

Summary:
TCP 443 connection failed to private endpoint. Network path is blocked.

Recommended Actions:
  1. Verify VPN connectivity and that your client subnet can route to the private endpoint subnet
  2. Ask your network team to verify routing from DESKTOP-ABC123 to private endpoint 10.123.171.30
  3. Check Azure network security groups (NSGs) rules for port 443 inbound
  4. Verify Azure Virtual Network peering and User Defined Routes (UDRs)
  5. Check if corporate firewall/NVA is blocking the connection
  6. Manually run: Test-NetConnection -ComputerName my-cosmos-account.documents.azure.com -Port 443

Full JSON Report:
...

JSON Output File

A file like cosmos-diagnostic-20260513_143045.json is automatically saved in the current directory.

Use this file to:

• Share with support (can use -Redact to mask sensitive data)
• Parse with automation tools
• Retain diagnostic history

---

Common Scenarios

Scenario 1: "I can't connect to Cosmos DB from my machine"

Run this:

.\Diagnose-CosmosConnectivity.ps1 -Interactive

Interpret results:

• If dns_resolution_failed → Check VPN/proxy DNS settings
• If tcp_connectivity_blocked → Ask network team to check firewall/NSG rules
• If network_connectivity_healthy → Issue is auth/RBAC, not network

---

Scenario 2: "Private endpoint isn't working"

Run this:

.\Diagnose-CosmosConnectivity.ps1 `
  -EndpointUrl "https://my-cosmos.documents.azure.com" `
  -SubscriptionId "your-sub-id" `
  -ResourceGroup "your-rg" `
  -AccountName "your-account" `
  -PrivateEndpointIP "10.123.171.30"

Interpret results:

• If resolved IP matches private endpoint IP but TCP fails → VPN route blocked
• If resolved IP differs from provided IP → Route misconfiguration
• If network is healthy → Check private DNS zone configuration

---

Scenario 3: "How do I share this with support safely?"

Run with redaction:

.\Diagnose-CosmosConnectivity.ps1 `
  -EndpointUrl "https://my-cosmos.documents.azure.com" `
  -SubscriptionId "your-sub-id" `
  -ResourceGroup "your-rg" `
  -AccountName "your-account" `
  -Redact

Then share the generated JSON file. Sensitive data (subscription ID, usernames, tenant ID) will be masked as REDACTED.

---

Scenario 4: "I need the diagnostics in a pipeline"

Non-interactive with JSON output capture:

$json = .\Diagnose-CosmosConnectivity.ps1 `
  -EndpointUrl "https://my-cosmos.documents.azure.com" `
  -SubscriptionId "your-sub-id" `
  -ResourceGroup "your-rg" `
  -AccountName "your-account" 2>&1 `
  | Select-String -Pattern '^\{' -SimpleMatch | ConvertFrom-Json

# Now use $json in automation
if ($json.classification.code -eq "network_connectivity_healthy") {
    Write-Host "Network OK, escalating to app team"
} else {
    Write-Host "Network issue: $($json.classification.summary)"
}

---

Classification Codes

The script produces one of these classification codes:

Code	Meaning
network_connectivity_healthy	✓ Network works. If errors, check auth/RBAC.
dns_resolution_failed	✗ Cannot resolve endpoint hostname.
tcp_connectivity_blocked	✗ DNS works, but TCP 443 blocked.
private_endpoint_network_path_blocked	✗ Private endpoint detected, TCP fails.
rbac_insufficient	⚠ Network OK, but RBAC permissions missing.
azure_config_check_skipped	⚠ Azure CLI not authenticated.

See CLASSIFICATION_MATRIX.md for detailed playbooks and support guidance.

---

Advanced Usage

Running Specific Checks

The script always runs all checks, but you can parse the JSON to focus on specific ones:

# Get just DNS results
$report = Get-Content cosmos-diagnostic-*.json | ConvertFrom-Json
$report.diagnostics.dns | ConvertTo-Json

# Get classification only
$report.classification | ConvertTo-Json

# Check if RBAC is sufficient
$report.diagnostics.rbac.classification

---

Integration with Support Ticketing

When opening a support case:

1. Run the script (interactive mode is fine)
2. Include the generated JSON file in your ticket
3. Or use -Redact flag if sharing with external support

Example ticket text:

Title: Cosmos DB Connection Errors

Body:
Experiencing connection errors to my Cosmos DB account.
Attached diagnostic results (cosmos-diagnostic-*.json).

Network Status: [paste classification.status]
Issue Code: [paste classification.code]
Endpoint: [paste target.hostname]

---

Troubleshooting the Script Itself

Script won't run (permission denied)

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Then re-run the script.

"Azure CLI not found" but I need RBAC checks

Install Azure CLI:

• Windows: https://learn.microsoft.com/en-us/cli/azure/install-azure-cli-windows
• Mac: brew install azure-cli
• Linux: Follow docs at https://learn.microsoft.com/en-us/cli/azure/install-azure-cli-linux

Then:

az login

Re-run the script.

Endpoint validation error

Error: "Invalid format. Expected: https://.documents.azure.com"

Fix: Remove trailing slash or port from URL:

• ❌ https://my-cosmos.documents.azure.com/ (trailing slash)
• ❌ https://my-cosmos.documents.azure.com:443/ (with port)
• ✅ https://my-cosmos.documents.azure.com (correct)

---

File Outputs

Generated Files

After running, the script creates:

cosmos-diagnostic-<timestamp>.json

• Full diagnostic report in JSON format
• Machine-readable for automation
• Can be shared with support
• Keep for troubleshooting history

---

JSON Schema

For details on JSON structure, field definitions, and sample outputs, see DIAGNOSTIC_SCHEMA.md.

---

Support Routing

Based on classification code, route as follows:

Classification	Route To
network_connectivity_healthy	Application/Auth team—network verified working
dns_resolution_failed	VPN/Network team—DNS issue
tcp_connectivity_blocked (public IP)	Firewall/ISP team—outbound port blocked
private_endpoint_network_path_blocked	Network team—PE routing issue
rbac_insufficient	Cosmos DB Access Control team
azure_config_check_skipped	Customer: Run az login first

---

Version

Script Version: 1.0.0
Schema Version: 1.0.0
Last Updated: 2026-05-13

---

License

This script is provided as-is for diagnosing Cosmos DB connectivity issues. See LICENSE for terms.

---

Next Steps

1. Run the script: .\Diagnose-CosmosConnectivity.ps1 -Interactive
2. Review output: Check the JSON report and console summary
3. Follow recommended actions based on the classification code
4. Share with support if needed (use -Redact for sensitive data masking)

For questions or issues with the script itself, contact the Cosmos DB team.